fake_pha

Context: data

Synopsis

Simulate a PHA data set from a model.

Syntax

fake_pha(id, arf=None, rmf=None, exposure=None, backscal=None,
areascal=None, grouping=None, grouped=False, quality=None, bkg=None,
method=None)

Description

The function creates a simulated PHA data set based on a source model, instrument response (given as an ARF and RMF), and exposure time, along with a Poisson noise term. A background component can be included.

Examples

Example 1

Fit a model - an absorbed powerlaw - to the data in the file src.pi and then simulate the data using the fitted model. The exposure time, ARF, and RMF are taken from the data in src.pi.

>>> load_pha("src.pi")
>>> set_source(xsphabs.gal * powlawd.pl)
>>> notice(0.5, 6)
>>> fit(1)
>>> fake_pha(1)

Example 2

Simulate the data but for a 1 Ms observation:

>>> fake_pha(1, exposure=1e6)

Example 3

Estimate the signal from a 5000 second observation using the ARF and RMF from "src.arf" and "src.rmf" respectively:

>>> set_source(1, xsphabs.gal * xsapec.clus)
>>> gal.nh = 0.12
>>> clus.kt, clus.abundanc = 4.5, 0.3
>>> clus.redshift = 0.187
>>> clus.norm = 1.2e-3
>>> fake_pha(1, 'src.arf', 'src.rmf', 5000)

Example 4

Simulate a 1 mega second observation for the data and model from the default data set. The simulated data will include an estimated background component based on scaling the existing background observations for the source. The simulated data set, which has the same grouping as the default set, for easier comparison, is created with the 'sim' label and then written out to the file 'sim.pi':

>>> arf = get_arf()
>>> rmf = get_rmf()
>>> bkg = get_bkg()
>>> bscal = get_backscal()
>>> grp = get_grouping()
>>> qual = get_quality()
>>> texp = 1e6
>>> set_source('sim', get_source())
>>> fake_pha('sim', arf, rmf, texp, backscal=bscal, bkg=bkg,
...          grouping=grp, quality=qual, grouped=True)
>>> save_pha('sim', 'sim.pi')

Example 5

Sometimes, the background dataset is noisy because there are not enough photons in the background region. In this case, the background model can be used to generate the photons that the background contributes to the source spectrum. To do this, a background model must be passed in. This model is then convolved with the ARF and RMF (which must be set before) of the default background data set:

>>> set_bkg_source('sim', 'const1d.con1')
>>> load_arf('sim', 'bkg.arf.fits', bkg_id=1)
>>> load_rmf('sim', 'bkg_rmf.fits', bkg_id=1)
>>> fake_pha('sim', arf, rmf, texp, backscal=bscal, bkg='model',
...          grouping=grp, quality=qual, grouped=True)
>>> save_pha('sim', 'sim.pi')

PARAMETERS

The parameters for this function are:

Parameter	Type information	Definition
id	int or str	The identifier for the data set to create. If it already exists then it is assumed to contain a PHA data set and the counts will be over-written.
arf	None or filename or ARF object or list of filenames, optional	The name of the ARF, or an ARF data object (e.g. as returned by `get_arf` or `unpack_arf` ). A list of filenames can be passed in for instruments that require multiple ARFs. Set this to `None` to use any arf that is already set for the data set given by id or for instruments that do not use an ARF separate from the RMF (e.g. XMM-Newton/RGS).
rmf	filename or RMF object or list of filenames, optional	The name of the RMF, or an RMF data object (e.g. as returned by `get_rmf` or `unpack_rmf` ). A list of filenames can be passed in for instruments that require multiple RMFs. Set this to `None` to use any rmf that is already set for the data set given by id.
exposure	number, optional	The exposure time, in seconds. If not set (i.e. is `None` ) then use the exposure time of the data set given by id.
backscal	number, optional	The 'BACKSCAL' value for the data set.
areascal	number, optional	The 'AREASCAL' value for the data set.
grouping	array, optional	The grouping array for the data (see `set_grouping` ). Set this to `None` to use any grouping that is already set for the data set given by id; the grouping is only applied if `grouped` is True .
grouped	bool, optional	Should the simulated data be grouped (see `group` )? The default is False . This value is only used if the `grouping` parameter is set.
quality	array, optional	The quality array for the data (see `set_quality` ).
bkg	optional	If left empty, then only the source emission is simulated. If set to a PHA data object, then the counts from this data set are scaled appropriately and added to the simulated source signal. To use background model, set bkg="model" . In that case a background dataset with bkg_id=1 has to be set before calling fake_pha . That background dataset needs to include the data itself (not used in this function), the background model, and the response.
method	callable or None, optional	If None, the default, then the data is simulated using the `sherpa.utils.poisson_noise` routine. If set, it must be a callable that takes a ndarray of the predicted values and returns a ndarray of the same size with the simulated data.

Notes

A model expression is created by using the supplied ARF and RMF to convolve the source expression for the dataset (the return value of `get_source` for the supplied `id` parameter). This expression is evaluated for each channel to create the expectation values, which is then passed to a Poisson random number generator to determine the observed number of counts per channel. Any background component is scaled by appropriate terms (exposure time, area scaling, and the backscal value) before it is passed to a Poisson random number generator. The simulated background is added to the simulated data.

Changes in CIAO

Changed in CIAO 4.17

Several bugs have been addressed when simulating data with a background: the background model contribution would be wrong if the source and background exposure times differ or if there were multiple background datasets. The arf, rmf, and exposure arguments are now optional.

Changed in CIAO 4.16

The method parameter was added.

Changed in CIAO 4.15

The arf argument can now be set to `None` when the data uses a RSP file (combined RMF and ARF).

Bugs

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