estimate_weighted_expmap

Context: contrib

Synopsis

Return the estimated exposure map value by weighting an ARF by a spectral model.

Syntax

estimate_weighted_expmap( id=None, arf=None, elo=None, ehi=None,
specresp=None, fluxtype="photon", par=None, pvals=None )

Description

The estimate_weighted_expmap() command returns an estimate of the weighted exposure map using the spectral model associated with the dataset as the weighting function. The exposure map is estimated by using an ARF; this can either be the ARF associated with the PHA dataset or can be explicitly given, as a filename, crate, or set of three arrays for the bin edges and bin value.

The routine can be used to estimate the exposure map with the current set of model parameters, or it can be given an array of values for a single parameter and return the exposure map for each parameter value.

Loading the routine

The routine can be loaded into Sherpa by saying:

from sherpa_contrib.utils import *

Arguments

Name	Default value	Description
id	None (which means use the value of get_default_id)	Which dataset to use.
arf	None	If given then this should be either the name of the ARF to read in or a crate containing the ARF (e.g. the return value of the read_file or read_arf commands).
elo	None	If arf is set to None then this argument is used to send in an array of the low-values of each bin, in keV. It should have the same number of elements as ehi and specresp.
ehi	None	If arf is set to None then this argument is used to send in an array of the high-values of each bin, in keV. It should have the same number of elements as elo and specresp.
specresp	None	If arf is set to None then this argument is used to send in an array of the ARF value for each bin, in cm^2. It should have the same number of elements as elo and ehi.
fluxtype	"photon"	The units for the return value are cm^2 count / <fluxtype>. The valid options for this argument are "photon" (the default) or "erg".
par	None	If not None, it should be a parameter of the source model which will be set to each entry in the pvals array.
pvals	None	If par is not None then this defined the parameter values over which the exposure map is to be calculated.

Estimating the source flux

If source_counts is the number of counts in the source, emap is the return value of estimate_weighted_expmap(), and exposure is the exposure time in seconds, then

source_counts / (exposure * emap)

is an estimate of the source flux, with units of either photon / cm^2 / s or erg / cm^2 / s, depending on the value of the fluxtype argument. This is only an estimate of the source flux, since it depends on how closely the source resembles the model spectrum, as well as the energy range used and how the background is estimated. For instance, the background is likely to have a significantly different spectrum to the source, and the correction factor from counts to flux can vary significantly (by 50% or more) with spectral shape.

Note: no 'de-reddening'

Note that the calculation above does not "de-redden" the source flux; if the model includes Galactic absorption then you will want to account for this in calculating the intrinsic flux of the source.

Estimating the sensitivity of the exposure map to the input spectrum

The estimate_weighted_expmap() routine can be used to estimate how sensitive the exposure map, and hence the flux conversion factor, is to energy range or spectral model. As an example, if the source model is a power law called "pl", with the parameter gamma, then the conversion factor can be estimated for a range of gamma values:

gamma_vals = np.arange(0.1,5,0.1)
expmap_vals = estimate_weighted_expmap(par=pl.gamma, pvals=gamma_vals)

The curve gamma_vals, expmap_vals shows how the conversion factor (i.e. weighted exposure map) value varies as gamma changes from 0.1 to 4.9.

Examples

Example 1

sherpa> load_data("src.pi")
sherpa> notice(0.5, 7)
sherpa> set_source(xsphabs.gal * xsmekal.clus)
sherpa> gal.nh = 0.45
sherpa> clus.kt = 2
sherpa> clus.abundanc = 0.5
sherpa> plot_instmap_weights()
sherpa> estimate_weighted_expmap()
531.66632
sherpa> estimate_weighted_expmap(fluxtype="erg")
1.722337e+11
sherpa> clus.kt = 5
sherpa> estimate_weighted_expmap()
487.28174
sherpa> estimate_weighted_expmap(fluxtype="erg")
1.1962892e+11

A dataset is loaded, an energy range chosen, and a spectral model set up. The plot_instmap_weights() call is used to show what the weights look like, and then the estimate_weighted_expmap() call is used to estimate the exposure map for two different model parameters (kT = 2 keV and then kT = 5 keV). The first calculation for each parameter value calculates a value with units of cm^2 count / photon (with values around 500), and the second call calculates a value of cm^2 count / erg (values around 1e11). The values were calculated using the ARF that was read in with the data file (i.e. given by the ANCRFILE keyword in the file src.pi). The values can vary strongly given the ARF, spectral model, and energy grids used in the analysis.

Approximate count fluxes

The estimated source flux (for the kT=2 keV case) is therefore

source_counts / (exposure * 531.66632)

in units of photon / cm^2 / s and

source_counts / (exposure * 1.722337e+11)

in units of erg / cm^2 / s, where source_counts is the measured number of source counts in the 0.5 to 7 keV band, and exposure is the exposure time of the observation, in seconds. Please note that these values are only approximate; please see the Calculating Spectral Weights thread and related documentation for a discussion of the reliability of this approach.

Example 2

sherpa> dataspace1d(2.5,5,0.1)
sherpa> set_source(xsphabs.gal * xsmekal.clus)
sherpa> gal.nh = 0.45
sherpa> clus.kt = 2
sherpa> clus.abundanc = 0.5
sherpa> estimate_weighted_expmap(arf="src.arf")
421.69598
sherpa> estimate_weighted_expmap(arf="src.arf", fluxtype="erg")
7.9162262e+10
sherpa> clus.kt = 5
sherpa> estimate_weighted_expmap(arf="src.arf")
420.05133
sherpa> estimate_weighted_expmap(arf="src.arf", fluxtype="erg")
7.5432468e+10

In this example we manually create a data space for the model evaluation. Since there is no associated ARF in this case one has to be given when calling estimate_weighted_expmap(); we chose to give the file name via the arf argument. It would have been slightly more efficient to read in the ARF using the Crates routine read_file (or read_arf) and then send the crate to the routine: for example

sherpa> cr = read_file("src.arf")
sherpa> estimate_weighted_example(arf=cr)

The exposure-map values are more consistent as the kT parameter is varied in this example compared to the previous one because the Chandra ARF shows much less variation over the energy range 2.5 to 5 keV than the 0.5 to 7 keV band used previously. The degree of variation with model parameters also depends on whether the output is in "photon" or "erg" units and the shape of the spectral model.

Example 3

sherpa> estimate_weighted_expmap(2, elo=x1, ehi=x2, specresp=arf)

In this example the ARF is defined by the three arrays x1, x2, and arf. The x1 and x2 arrays give the low and high edges of each bin, and are in keV, and the arf array gives the ARF for each bin in cm^2. All three arrays should contain the same number of elements.

The ARF does not have to have the same energy gridding as the dataspace, but should cover the same energy range.

Example 4

sherpa> kts = 10**np.linspace(-1,1,11)
sherpa> evals = estimate_weighted_expmap(2, elo=x1, ehi=x2,
specresp=arf, par=clus.kt, parvals=kts)

In this example the exposure map is evaluated as the clus.kt parameter is varied from 0.1 to 10, using logarithmically-spaced bins.

Changes in the scripts 4.8.2 (January 2016) release

The routine has been updated to work in CIAO 4.8.

Bugs

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