Last modified: December 2023

URL: https://cxc.cfa.harvard.edu/sherpa/ahelp/eqwidth.html
AHELP for CIAO 4.16 Sherpa

eqwidth

Context: utilities

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)

lo - optional
hi - optional
id - int or string, optional
bkg_id - int or string, optional
error - bool, optional
params - 2D array, optional
otherids - sequence of integer or strings, optional
niter - int, optional
covar_matrix - 2D array, optional

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 Definition
src The continuum model (this may contain multiple components).
combo The continuum plus line (absorption or emission) model.
lo 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 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 The data set that provides the data. If not given then all data sets with an associated model are used simultaneously.
bkg_id 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 The parameter indicates whether the errors are to be calculated or not. The default value is False
params 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 Other data sets to use in the calculation.
niter The number of draws to use. The default is 1000 .
covar_matrix 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.

See Also

data
get_bkg_chisqr_plot, get_bkg_delchi_plot, get_bkg_fit_plot, get_bkg_model_plot, get_bkg_plot, get_bkg_ratio_plot, get_bkg_resid_plot, get_bkg_source_plot
info
list_model_ids, show_bkg_model, show_bkg_source
modeling
add_model, add_user_pars, clean, create_model_component, delete_bkg_model, delete_model, delete_model_component, get_model, get_model_autoassign_func, get_model_component, get_model_component_image, get_model_component_plot, get_model_plot, get_num_par, get_num_par_frozen, get_num_par_thawed, get_order_plot, get_par, get_pileup_model, get_source, get_source_component_image, get_source_component_plot, get_source_contour, get_source_image, get_source_plot, get_xsabund, get_xscosmo, get_xsxsect, get_xsxset, image_model, image_model_component, image_source, image_source_component, integrate, link, load_table_model, load_template_interpolator, load_template_model, load_user_model, normal_sample, reset, save_model, save_source, set_bkg_model, set_bkg_source, set_full_model, set_model, set_model_autoassign_func, set_pileup_model, set_source, set_xsabund, set_xscosmo, set_xsxsect, set_xsxset, t_sample, uniform_sample
plotting
get_cdf_plot, get_pdf_plot, get_pvalue_plot, get_pvalue_results, plot_cdf, plot_model, plot_model_component, plot_pdf, plot_pvalue, plot_scatter, plot_source, plot_source_component, plot_trace
psfs
delete_psf, load_conv
saving
save_delchi, save_resid
utilities
calc_chisqr, calc_energy_flux, calc_model_sum, calc_photon_flux, calc_source_sum, calc_stat
visualization
contour_model, contour_ratio, contour_resid