sxsmkrmf - Create an SXS RMF file and/or an RSP file for selected SXS pixels and grades
sxsmkrmf infile outfile resolist regmode region
'sxsmkrmf' is a script that calculates an SXS redistribution
matrix file (RMF) for selected grades and pixels properly
weighted. The file of weights is calculated with an input event file
for the pixel / grade combination. The rmf is calculated
by running 'sxsrmf' with the file of weights appropriate for
the pixel/grade combination.
If an arf file is provided 'sxsmkrmf' output a total response (RSP) file.
The inputs to 'sxsmkrmf' are: (1) a cleaned SXS event file from which
spectra are to be extracted; (2) a list of resolution grades (see
'resolist' parameter); and (3) a list of pixels. The selected
grades and pixels should match the lists used to extract the
spectra and to create the arf.
The pixels selection may be determined in two manners. (1) Input a
DS9-format region file ('region') either in DET or SKY coordinates
(see 'regmode' parameter). The task 'coordpnt' converts the region
into a pixel list using the CALDB teldef file (see 'teldeffile' parameter).
By default, the conversion from SKY coordinates uses the pointing
recorded in the RA_NOM, DEC_NOM, and PA_NOM keywords of the input event file.
However, these may be overridden using the 'rapoint', 'decpoint', and 'roll'
parameters. The 'pixeltest' parameter determines the criteria for
including pixels based on the region. If 'region=ALLPIX', all pixels
are included. (2) If 'region=NONE', the pixel selection is
done by entering pixel number in the 'pixelist' parameter.
The selection of grades and pixels determined by the 'sxsmkrmf'
parameters is used to construct a file containing the weights for each
combination of grade and pixel (sxsfrac.fits) that is utilized by the
'sxsrmf' task to create the RMF file. 'sxsrmf' calculates the RMF for
each pixel and grade by using the line spread function (LSF)
parameters stored in a CALDB file. The LSF is assumed to consist
of (1) a Gaussian core with a
pixel-dependent FWHM, (2) a low-energy exponential tail due to energy
loss at the surface of the absorbers, (3) an extended low energy
electron loss continuum, and (4) discrete escape peaks from M-shell
fluorescence of Hg or Te in the absorber. The parameters of the first
component are contained in LINESIGMA extension of the CALDB file
given by the 'rmfsigma' parameter, and of the latter three components
in the LINETAU extension of CALDB file given by the 'rmftau' parameter.
Four types of RMF files may be created. The small (s/S) accounts only
for the Gaussian core. The medium (m/M) includes also the exponential
tail. The large (l/L) includes the escape peaks and the x-large (x/X)
adds the continuum down to the minimum energy given by the 'emincont'
parameter. Note that the x-large may exceed the 2.1 GB default limit
for the FITS file structure used in response files. Thus the successful
creation and application (e.g., in XSPEC) of x-large RMF files cannot be
assured, and this option is not recommended for normal usage.
The script writes out an output RMF containing the response
matrix; and an EBOUNDS extension which lists the energy boundaries of each
The energy bin size(s) of the RMF may be set with the 'dein'
parameter, with 'eminin' and 'nchanin' determining the energy range
for those bins (see below for more detail). The input energy grid may
have multiple values for the number of energies and grid spacing to
support a nonuniform grid; however, the single-grid default parameter
values of 'eminin=0', 'dein=0.5', and 'nchanin=32768' are recommended.
Furthermore, the 'EBOUNDS' energy grid must match the PI grid of the
spectrum file. If the parameter 'useingrd=yes', the output grid is set
equal to the input grid. This is the recommended binning. However, the
'EBOUNDS' energy grid can be independently specified by setting the
parameter values of 'deout', 'eminout', and 'nchanout'. If
'useingrd=yes', the output grid parameters ignored.
If the parameter 'outrsp=yes', an RSP file may be created to combine the RMF, calculated by 'sxsrmf',
and the ARF input to sxsmkrmf (see parameter 'arfinfile') . The RSP output filename may be entered
in the parameter 'outrspfile'.
- infile [filename]
- Input event file used to calculate the grade and pixel weighting
factors. This should be the cleaned event file used to extract the
- outfile [filename]
- Name of output RMF file.
- resolist [string]
- List of grades (ITYPE). ITYPE=0 for grade Hp, ITYPE=1 for Mp,
ITYPE=2 for Ms, ITYPE=3 for Lp, ITYPE=4 for Ls.
Multiple numerical values may be entered separated by a comma ,e.g. resolist=1,2,3.
If 'resolist' is ALL, all grades are considered.
- regmode [string]
- Coordinate system for the region file. This is either DET or SKY.
- region [string]
- Region file name. If region is set to ALLPIX, all pixels are used
and regmode is ignored.
- (pixlist = 0-35) [string]
- List of pixels, in the form of commas separated ranges, e.g.
e.g. '0-3,7,13-25,30'. The content of this parameter only used only if region = NONE.
- (pixeltest = PARTIAL) [string]
- Pixel inclusion option. 'pixeltest=PARTIAL' (the default):
if any part of the pixel is within the region, the all pixel is included
in the region; 'pixeltest=CENTER': the pixel is included in the region only if the pixel center is within the region;
'pixeltest=TOTAL': the pixel is included in the region only if the entire pixel is within the region.
- (rapoint = -999.0) [real]
- Pointing RA [deg]. If rapoint is set to -999, the RA is read from the
RA_NOM keyword on the event file.
- (decpoint = -999.0) [real]
- Pointing DEC [deg]. If decpoint is set to -999, the DEC is read from the
DEC_NOM keyword on the event file.
- (roll = -999.0) [real]
- Roll angle [deg]. If roll is set to -999, the roll is read from the
PA_NOM keyword on the event file.
- (teldeffile = CALDB) [filename]
- Input teldef filename.
- (outrsp = no) [boolean]
- If yes, an output RSP file is created by combining the rmf with
the input arf file specified by the 'arfinfile' parameter (yes/[no]).
- (outrspfile) [filename]
- Name of output response (RSP) file. This parameter is ignored if outrsp=no.
- (arfinfile = NONE) [filename]
- Name of input ARF file. This parameter is ignored if outrsp=no.
- (time = 2014-01-01T00:00:00) [string]
- Start time for validity of RMF file in YYYY-MM-DD format. The task
selects the CALDB file corresponding to this time.
- (whichrmf = L) [string]
- Type of RMF to construct -- S(mall), M(edium), L(arge), or
X(tra-large). The 'X' option is not recommended for general use.
- (rmfsigma = CALDB) [filename]
- Input file containing the parameters for the Gaussian core. If set
to CALDB, the file is read from the calibration database.
- (rmftau = CALDB) [filename]
- Input file containing the parameters for the exponential tail,
electron continuum, and escape peaks. If set to CALDB, the file is
read from the calibration database.
- (eminin = 0.0) [real]
- Minimum energy of the MATRIX grid in eV.
- (dein = 0.5) [string]
- Spacing of energy bins (in eV) in each interval of the MATRIX
grid. A single value (e.g., 0.5 as the default) applies a constant
grid spacing for the entire matrix. Multiple values separated by
commas (e.g., '0.5,2.0') create a variable grid spacing starting at
eminin. The number of channels in each energy interval must be
specified with nchanin. The values may be floating point.
- (nchanin = 32768) [string]
- Number of channels in each interval of the MATRIX grid. Combined
with the default values of the previous two parameters, the
default means that the output MATRIX has 32768 channels with 0.5
eV size up to 16384 eV. If, instead, dein='0.5,2.0' and
nchanin='26000,6500' the output MATRIX would have 26000 bins (with
0.5 eV size) up to 13000 eV, and 6500 bins (with 2 eV size) above
13000 eV (hence up to 26000 eV). dein and nchanin must have the
same number of intervals. The values of nchanin must be
- (useingrd = yes) [boolean]
- If useingrd is set to yes the output grid is set equal to the input
grid, and the output grid parameters are ignored. In this case nchanin
and dein may only have single values. If useingrd is set to no the output grid
is determined by eminout, deout, and nchanout ([yes]/no).
- (eminout = 0.0) [real]
- Minimum energy of EBOUNDS in eV. The default value is 0.0. This parameter is
ignored if useingrd is set to yes.
- (deout = 0.5) [real]
- Spacing of the EBOUNDS energy grid in eV. This must be consistent
with the assumed energy grid of the PI file (i.e., 0.5 eV for the
SXS). This parameter is ignored if useingrid is set to yes.
- (nchanout = 32768) [integer]
- Number of channels in EBOUNDS. This must be consistent with the
number of PI channels in the PHA file. The default value for SXS is
32768. This parameter is ignored if useingrd is set to yes.
- (rmfthresh = 1.0e-9) [real]
- Low threshold for the RMF construction. For a given X-ray photon
energy, the normalized probability (i.e., a value less than 1) of
producing a certain PI value is calculated for each channel and
written in the MATRIX extension. If the probability is less than this
threshold, 0 (zero) is written for that element. Using the default
value (1.0e-9) is secure enough for most cases.
- (emincont = 10.0) [real]
- Lower energy limit [eV] of electron continuum.
- (buffer = -1) [integer]
- Rows to buffer (-1=auto, 0=none, >0=numrows).
- (clobber = no) [boolean]
- Overwrites the existing output file if set to yes (yes/[no]).
- (chatter = 1) [integer]
- Chatter level for output. Set to 0 to suppress output,
or to 1, 2, or 3 for increasing the chatter of the output.
- (logfile = !DEFAULT) [string]
- Log filename. If set to DEFAULT uses the name of the task and, if
preceded by '!', overwrite the file if it exists. If set to NONE no
log file is created.
- (debug = no) [boolean]
- Diagnostic output is printed out on the screen if set to yes
- (history = yes) [boolean]
- Records tool parameters in HISTORY ([yes]/no).
- (mode = ql) [string ql|hl|q]
- Mode to query the parameter file.
Acceptable values include: 'ql' (query and learn/remember), 'hl' (hidden and learn/remember), 'q' (query but don't remember), 'h' (hidden).
1. Create a large-sized RMF file, sxs_allpix_large.rmf, for high-resolution events using all pixels, with weights derived from the cleaned SXS event file, sxs_cl.evt.
sxsmkrmf infile=sxs_cl.evt outfile=sxs_allpix_large.rmf resolist=0 region=ALLPIX
2. Create a small-sized (line-spread function Gaussian core only) RMF file, sxs_region_small.rmf, for high-resolution and mid-resolution primary events, using pixels with any part in the sky region sxs_sky.reg. Also create an rsp file sxs_region_small.rsp using the arf file sxs_region_small.arf.
sxsmkrmf infile=sxs.evt outfile=sxs_region_small.rmf resolist=0,1 region=sxs_sky.reg outrsp=yes outrspfile=sxs_region_small.rsp \
27 January 2016