NAME
rslmkrmf - Create a XRISM Resolve redistribution matrix file (RMF) and/or a
response (RSP) file for selected Resolve pixel and grade combinations, with
weighting factors derived from an input event file and region
USAGE
rslmkrmf infile outfileroot resolist regmode regionfile
DESCRIPTION
The rslmkrmf task is a script that calculates a Resolve redistribution
matrix file (RMF) for selected grade and pixel combinations, weighted
according to relative counts. After a file containing the weights is
calculated based on the pixel and grade distributions in the input
event file, the RMFs for single pixels and grades are individually
calculated and then combined accordingly using the rslrmf task. If an
ARF is provided, rslmkrmf can output a total response (RSP) file upon
request.
The required inputs to rslmkrmf are: (1) a cleaned Resolve event file
('infile') that should be the same as that used to extract the spectrum
to which the RMF is to be applied; (2) a list of resolution grades
('resolist'); and (3) a list of pixels. The selected grades and pixels
should match the lists that were used to extract the spectrum and to
create the ARF.
The following two options for specifying the list of pixels are
supported. (1) The user may input a DS9-format region file in either
DET or SKY coordinates by setting the 'regmode' and 'regionfile'
parameters. The task 'coordpnt' is then used to convert the region
into a pixel list using the teldef CalDB file specified by the
'teldeffile' parameter. If 'regmode=SKY', 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 in the region. If 'regionfile=ALLPIX', all pixels are
included. (2) If 'regionfile=NONE', the pixel selection is executed by
entering the pixel numbers in the 'pixlist' parameter.
The selection of grades and pixels determined by the rslmkrmf
parameters is used to construct a file containing the weights for each
combination of grade and pixel (rslfrac.fits). This file is a
FITS file with three columns: PIXEL, GRADE, and WEIGHT, where WEIGHT
is defined as the ratio of counts for the specific PIXEL and GRADE
combination to the total over the selected pixels. The rslfrac.fits
file can be retained and used to enable the user to re-run rslrmf in a
slightly different configuration without having to re-run rslmkrmf.
The RMF for each
pixel and grade is calculated by the rslrmf task using the line spread
function (LSF) parameters stored in designated extensions of the CalDB
file specified by the 'rmfparamfile' parameter. The LSF is
assumed to consist of (1) a Gaussian core with a pixel-dependent FWHM,
(2) a pixel-dependent low-energy exponential tail due to energy
loss at the surface of the absorbers, (3) a pixel-dependent extended low-energy
electron loss continuum, (4) pixel-dependent discrete escape peaks from
M-shell fluorescence of Hg or Te in the absorber, and (5) a pixel-dependent Si K
alpha emission line.
Four types of RMF files may be created by setting the 'whichrmf'
parameter. (1) The small option (s/S) includes only the Gaussian core;
(2) the medium option (m/M) also includes the exponential tail and
Si K alpha emission line; (3)
the large option (l/L) also includes the escape peaks and Si K alpha line; and (4) the
x-large option (x/X) also includes the electron loss continuum down to
the minimum energy given by the 'emincont' parameter.
The x-large matrix file may become very large (more than 2 GB), impractical to use,
or even cause downstream software failures. In such cases the user should use the
option to split the response function into two matrices using the 'splitrmf=yes' option.
One matrix handles the "core" response,
in which a significant number of off-diagonal elements are zero, and the
other matrix handles the electron loss continuum (ELC), which is not
sparsely filled but can be heavily binned to a coarser energy resolution
(using the parameter 'elcbinfac'). If the 'splitrmf=yes' option is
invoked and RSP matrices are requested (using 'outrsp=yes'), then the
rslrmf task creates a second ARF output file that corresponds to the
input ARF file binned to match the coarse ELC matrix. Note that
'splitrmf=yes' is only effective if 'whichrmf=X'. In general, the option 'outrsp=yes'
deletes the RMF files that are used to make the RSP file by combing the RMF and ARF files.
The output file specifed by 'outfileroot'+".rmf" or 'outfileroot'+".rsp"
is a FITS standard, containing the response matrix in the MATRIX extension
and the PI channel definitions in the EBOUNDS extension.
Output file names for the ELC component when 'splitrmf=yes'
have "_elc" appended to the root name, before the ".rsp", ".rmf", or ".arf"
file extension is appended. If 'splitcomb=yes', the two response matrices
made with 'splitrmf=yes' will be placed into a single file. If 'outrsp=yes', the
two ARFs will also be placed into a single file.
In XSPEC the correct RMF, RSP, or ARF is specified by appending {n} to the file name,
where n is an integer (and equal to the value of the keyword EXTVER in the header of
the desired data set). For the fine-binned (i.e. core) response, n=1, whilst for the
coarse-binned response (i.e. the ELC component), n=2.
Currently the CalDB parameter file only has calibration data for primaries because
the LSF has not been calibrated for secondaries. However, the task rslrmf accomodates
future versions of the CalDB file having independent calibration data for secondaries.
The action of rslrmf is to first search the CalDB file for independent Ms or Ls
calibration data if Ms or Ls events respectively are to be processed.
If the required secondaries calibration data are not found, and if 'secondaries=yes',
then the data for Mp and Lp are used in place of data for Ms and Ls respectively.
Otherwise, if secondaries calibration data are found, they are used, regardless of
the value of the 'secondaries' parameter. However,
if 'secondaries=no' and calibration data for Ms or Ls are needed but not found, then
the task aborts. There is also an option ('combps=yes') in rslmkrmf to make a weights file that
combines primaries and secondaries, resulting in only three effective grades (H, M, L). This
reproduces the behavior of the Hitomi task 'sxsmkrmf' and also results in faster
excecution. Note that if 'combps=yes', the parameter 'secondaries' has no effect because
all the events are effectively treated as primaries.
The energy bin widths of the input energy grid for the RMF may be set
with the 'dein' parameter, with 'eminin' and 'nchanin' determining the
energy range for those bins. The input energy grid may have multiple
values for the number of energies and grid spacing to support a
non-uniform grid. However, the single-grid default parameter values of
'eminin=0', 'dein=0.5', and 'nchanin=60000' are recommended. In this
case the RMF MATRIX has 32768 input bins of 0.5 eV width, and extends
to 16384 eV. If instead, for example, 'dein=0.5,2.0'
and 'nchanin=26000,6500', the MATRIX would have 26000 input 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).
The output energy grid (EBOUNDS) 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 are ignored.
PARAMETERS
- infile [filename]
- Name of input event file used to calculate the grade and pixel
weighting factors.
- outfileroot = response [filename]
- Output root name for all output files.
- (splitrmf = no) [boolean yes|no]
- If 'splitrmf=yes', split the RMF/RSP into core and ELC responses.
- (elcbinfac = 32) [integer]
- If 'splitrmf=yes', 'elcbinfac' is the rebinning factor for the ELC component of the RMF/RSP, which must be an exact
divisor of 'nchanin'. If 'splitrmf=no', 'elcbinfac' is ignored.
- (splitcomb = no) [boolean yes|no]
- If 'splitrmf=yes' and 'splitcomb=yes', the two response matrices
(corresponding to the core and ELC components) will be placed into a single file.
- resolist = 0 [string 0|1|2|3|4|ALL]
- List of grades (ITYPE). ITYPE=0 for grade Hp, ITYPE=1 for Mp,
ITYPE=2 for Ms, ITYPE=3 for Lp, and ITYPE=4 for Ls. Multiple
numerical values may be entered separated by a comma
(e.g. 'resolist=1,2,3'). If 'resolist=ALL', all grades are
considered.
- (combps = no) [boolean yes|no]
- If 'combps=yes', the primaries and secondaries will be combined in the weights file.
- (secondaries = yes) [boolean yes|no]
- If 'secondaries=yes' (and 'combps=no'), an attempt will first be made to find unique
secondaries calibration, otherwise Mp and Lp will be used for Ms and Ls, respectively.
- regmode = SKY [string DET|SKY]
- Coordinate system for the region file. DET and SKY are
currently the only allowed coordinate systems for the 'regmode'
parameter and must correspond to the 'regionfile' system, if
'regionfile' is set to a file name.
- regionfile = ALLPIX [string ALLPIX|NONE|file name]
- Region file name. If 'regmode=DET', 'regionfile' must be in DET coordinates.
If 'regmode=SKY', 'regionfile' must be in SKY coordinates. A 'regionfile'
in the incorrect coordinate system may not produce a useful error, so the
user should be particularly mindful of the coordinate system used.
If 'regionfile' is set to ALLPIX, all pixels are
used and 'regmode' is ignored. If 'regionfile=NONE' the pixel numbers
to include are specified by the parameter 'pixlist'.
- (pixlist = 0-35) [string]
- List of pixels in the form of comma-separated ranges, e.g.,
'pixlist=0-3,7,13-25,30'. This parameter is ignored unless
'regionfile=NONE'.
- (pixeltest = PARTIAL) [string PARTIAL|CENTER|TOTAL]
- Pixel inclusion option. If 'pixeltest=PARTIAL', the pixel is
included if any part of the pixel is within the region specified by
'regionfile'. If 'pixeltest=CENTER', the pixel is included only if
the pixel center is within the region. If 'pixeltest=TOTAL', the
pixel is included only if the entire pixel is within the region.
- (rapoint = -999.0) [double]
- Pointing RA [deg]. If 'rapoint' is set to -999, the RA is read from the
RA_NOM keyword in the input event file ('infile').
- (decpoint = -999.0) [double]
- Pointing DEC [deg]. If 'decpoint' is set to -999, the DEC is read from the
DEC_NOM keyword in the input event file ('infile').
- (roll = -999.0) [double]
- Roll angle [deg]. If 'roll' is set to -999, the roll is read from the
PA_NOM keyword in the input event file ('infile').
- (teldeffile = CALDB) [filename CALDB|file name]
- Input teldef filename. If set to CALDB, the file is read from the
calibration database, CalDB.
- (outrsp = no) [boolean yes|no]
- If 'outrsp=yes', an output RSP file is created by combining the RMF with
the input ARF file specified by the 'arfinfile' parameter. Note that if 'outrsp=yes',
the RMF file is deleted, keeping only the RSP file.
- (arfinfile = NONE) [filename NONE|file name]
- Name of input ARF file; this parameter is ignored if 'outrsp=no'.
- (time = 2019-01-01T00:00:00) [string]
- Start time, in YYYY-MM-DDThh:mm:ss format, for validity of the RMF LSF CalDB file extensions.
This parameter is needed when the task is run with no input event file.
- (rmfparamfile = CALDB) [filename CALDB|file name]
- Name of the input RMF parameter file. If set to CALDB, the file is read from the
CalDB.
- (whichrmf = L) [string S|M|L|X]
- Type of RMF to construct: (S)mall, (M)edium, (L)arge, or
(X)tra-large.
- (eminin = 0.0) [double]
- Minimum energy [eV] of the RMF MATRIX input energy grid.
- (dein = 0.5) [string]
- Energy bin width [eV] for each energy interval of the input
energy grid for the RMF MATRIX extension. If a single value (e.g.,
'dein=0.5') is input, a constant energy bin width for the entire
matrix is used. To create an energy grid starting at 'eminin' with
variable bin width, the user may input multiple values separated by
commas (e.g., 'dein=0.5,2.0'). The number of channels in each energy
interval is specified with 'nchanin'. Note that if 'splitrmf=yes',
then only a single energy range is allowed (i.e. only one value of
'dein' is permitted).
- (nchanin = 60000) [string]
- Number of channels in each energy interval of the input energy
grid for the RMF MATRIX. If a single value (e.g., 'nchanin=60000')
is input, a constant energy bin width for the entire MATRIX is
used. To create an energy grid starting at 'eminin' with variable
bin width, the user may input multiple values separated by commas
(e.g., 'nchanin=26000,6500'). In this case multiple grids are
created with numbers of bins given by each value, and variable
widths given by the corresponding value of "dein'. The 'dein' and
'nchanin' parameters must have the same number of entries, and the
values in 'nchanin' must be integers. Note that if 'splitrmf=yes',
then only a single energy range is allowed (i.e. only one value of
nchanin is permitted).
- (useingrd = yes) [boolean yes|no]
- If 'useingrd' is set to yes, the output energy grid is identical
to the input energy grid and the output grid parameters are
ignored. In this case 'nchanin' and 'dein' must have single values. If
'useingrd' is set to no, the output grid is determined by the
'eminout', 'deout', and 'nchanout' parameters.
- (eminout = 0.0) [double]
- Minimum energy [eV] of the RMF EBOUNDS extension (output) energy
grid; this parameter is ignored if 'useingrd=yes'.
- (deout = 0.5) [double]
- Width of the RMF EBOUNDS extension (output) energy grid bins [eV];
this parameter is ignored if 'useingrd=yes'.
- (nchanout = 60000) [integer]
- Number of channels in the RMF EBOUNDS extension (ouput) energy
grid; this parameter is ignored if 'useingrd=yes'.
- (rmfthresh = 1.0e-9) [double]
- Lower threshold for the RMF MATRIX. If the calculated MATRIX value
is less than 'rmfthresh' it is set to 0 before being recorded in
output RMF file.
- (emincont = 10.0) [double]
- Lower energy limit [eV] of electron loss continuum.
- (cleanup = yes) [boolean yes|no]
- Delete temporary files if 'cleanup=yes'.
- (buffer = -1) [integer -1|0|N]
- Rows to buffer (-1=auto, 0=none, N>0=numrows).
- (clobber = no) [boolean yes|no]
- Overwrites the existing output file if set to yes.
- (chatter = 1) [integer 0|1|2|3]
- 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 DEFAULT|NONE|file name]
- Log file name. If set to DEFAULT, uses the name of the task and, if
preceded by "!", overwrites the file if it exists. If set to NONE, no
log file is created.
- (debug = no) [boolean yes|no]
- Diagnostic output is printed to the screen if set to yes.
- (history = yes) [boolean yes|no]
- Records tool parameters in HISTORY.
EXAMPLES
- Create a large-sized RMF file (rsl_allpix_large.rmf) for high-resolution
events using all pixels with weights derived from the cleaned Resolve event
file, xa100050020rsl_p0px1010_cl.evt.
rslmkrmf infile=xa100050020rsl_p0px1010_cl.evt outfileroot=rsl_allpix_large resolist=0 regmode=SKY regionfile=ALLPIX
- Create a small-sized (line-spread function Gaussian core only) RMF file
(rsl_region_small.rmf) for high-resolution and mid-resolution primary events,
using pixels with any part in the sky region rsl_sky.reg. Also create an RSP
file (rsl_region_small.rsp) using the ARF file, rsl_region_small.arf.
rslmkrmf infile=xa100050020rsl_p0px1010_uf.evt outfileroot=rsl_region_small resolist="0,1" regmode=SKY \
regionfile=rsl_sky.reg outrsp=yes arfinfile=rsl_region_small.arf whichrmf=S
-
Create an x-large RSP file using all pixels, for high-resolution and
mid-resolution events, with weights derived from the cleaned Resolve event file,
xa100050020rsl_p0px1010_cl.evt, combining mid-resolution primary and secondary weights in the
weights file. Split the response matrix into a fine-binned core component and a
coarse-binned ELC component with a binning factor of 64, and place the two
matrices in a single RSP file. Set the input energy range to be 0 to 30 keV with
0.5 eV bin widths, and use the same grid for the output energies.
rslmkrmf infile=rsl_cl_bin64.evt outfileroot=rsl_allpix_xlarge_splitcomb resolist="0,1,2" regmode=SKY \
regionfile=ALLPIX arfinfile=rsl_allpix_xlarge_bin64.arf whichrmf=X outrsp=yes splitrmf=yes elcbinfac=64 combps=yes \
splitcomb=yes eminin=0 dein=0.5 nchanin=60000
SEE ALSO
rslrmf, coordpnt
LAST MODIFIED
February 28, 2024