eqwidth

Synopsis

Calculate the equivalent width of an emission or absorption line.

Syntax

eqwidth(src, combo, id=None, lo=None, hi=None, bkg_id=None,
error=False, params=None, otherids=(), niter=1000, covar_matrix=None)

Description

The equivalent width is calculated in the selected units for the data set (which can be retrieved with `get_analysis` ).

Examples

Example 1

Set a source model (a powerlaw for the continuum and a gaussian for the line), fit it, and then evaluate the equivalent width of the line. The example assumes that this is a PHA data set, with an associated response, so that the analysis can be done in wavelength units.

>>> set_source(powlaw1d.cont + gauss1d.line)
>>> set_analysis('wavelength')
>>> fit()
>>> eqwidth(cont, cont+line)
2.1001988282497308

Example 2

The calculation is restricted to the range 20 to 20 Angstroms.

>>> eqwidth(cont, cont+line, lo=20, hi=24)
1.9882824973082310

Example 3

The calculation is done for the background model of data set 2, over the range 0.5 to 2 (the units of this are whatever the analysis setting for this data set id).

>>> set_bkg_source(2, const1d.flat + gauss1d.bline)
>>> eqwidth(flat, flat+bline, id=2, bkg_id=1, lo=0.5, hi=2)
0.45494599793003426

Example 4

With the `error` flag set to `True` , the return value is enhanced with extra information, such as the median and one-sigma ranges on the equivalent width:

>>> res = eqwidth(p1, p1 + g1, error=True)
>>> ewidth = res[0]  # the median equivalent width
>>> errlo = res[1]   # the one-sigma lower limit
>>> errhi = res[2]   # the one-sigma upper limit
>>> pars = res[3]    # the parameter values used
>>> ews = res[4]     # array of eq. width values

which can be used to display the probability density or cumulative distribution function of the equivalent widths:

>>> plot_pdf(ews)
>>> plot_cdf(ews)

PARAMETERS

The parameters for this function are:

Parameter	Type information	Definition
src		The continuum model (this may contain multiple components).
combo		The continuum plus line (absorption or emission) model.
lo	optional	The lower limit for the calculation (the units are set by `set_analysis` for the data set). The default value ( none ) means that the lower range of the data set is used.
hi	optional	The upper limit for the calculation (the units are set by `set_analysis` for the data set). The default value ( none ) means that the upper range of the data set is used.
id	int, str, or None, optional	The data set that provides the data. If not given then all data sets with an associated model are used simultaneously.
bkg_id	int, str, or None, optional	The identifier of the background component to use. This should only be set when the line to be measured is in the background model.
error	bool, optional	The parameter indicates whether the errors are to be calculated or not. The default value is False
params	2D array, optional	The default is None, in which case get_draws shall be called. The user can input the parameter array (e.g. from running `sample_flux` ).
otherids	sequence of integer or strings, optional	Other data sets to use in the calculation.
niter	int, optional	The number of draws to use. The default is 1000 .
covar_matrix	2D array, optional	The covariance matrix to use. If none then the result from `get_covar_results().extra_output` is used.

Return value

The return value from this function is:

If error is False , then returns the equivalent width, otherwise the median, 1 sigma lower bound, 1 sigma upper bound, the parameters array, and the array of the equivalent width values used to determine the errors.

Changes in CIAO

Changed in CIAO 4.16

The random number generation is now controlled by the `set_rng` routine.

Changed in CIAO 4.11

The `error` parameter was added which controls whether the return value is a scalar (the calculated equivalent width), when set to `False` , or the median value, error limits, and ancillary values.

Bugs

See the bugs pages on the Sherpa website for an up-to-date listing of known bugs.