eqwidth

sherpa.astro.ui.eqwidth(src, combo, id: IdType | None = None, lo=None, hi=None, bkg_id: IdType | None = None, error: bool = False, params: np.ndarray | None = None, otherids: IdTypes = (), niter: int = 1000, covar_matrix: np.ndarray | None = None)

Calculate the equivalent width of an emission or absorption line.

The equivalent width (EW) is calculated following George & Fabian (1991) as “(combo - src) / src”. As combo is assumed to be the continuum model (src) combined with the source model, e.g. “src + line”, then this is equivalent to “line / src”. This means that emission lines have a positive EW and absorption lines a negative EW.

Changed in version 4.18.0: If covar_matrix is left unset then the covariance matrix is now always re-calculated. This means that covar is no-longer needed to be called before this routine. The error analysis now correctly handles the case when otherids is not empty.

Changed in version 4.16.0: The random number generation is now controlled by the set_rng routine.

Changed in version 4.10.1: 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.

Parameters:

  • 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 matrix is calculated for the dataset given by the id argument.

Returns:

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.

Return type:

retval

See also

calc_model_sum

Sum up the fitted model over a pass band.

calc_source_sum

Calculate the un-convolved model signal.

get_default_id

Return the default data set identifier.

set_model

Set the source model expression.

Examples

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

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

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

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

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. These values can be displayed with Sherpa plotting commands.

>>> 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
>>> plot_pdf(ews)    # probability density
>>> plot_cdf(ews)    # cumulative distribution

Fit dataset 2, assumed to contain components p2 and g2, calculate the covariance matrix, and then send this matrix to the eqwidth call:

>>> fit(2)
>>> covar(2)
>>> cmat = get_covar_results().extra_output
>>> res2 = eqwidth(p2, p2 + g2, id=2, covar_matrix=cmat, error=True)

Evaluate the equivalent-width distributions using datasets 1, 2, and 3:

>>> res = eqwidth(p, p + g, id=1, otherids=[2,3], error=True)