Syntax

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:

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.

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

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.