NAME
sxsrmf - Create a Hitomi SXS redistribution matrix file (RMF) for selected
SXS pixels and grades with weighting factors.
USAGE
sxsrmf infile outfile
DESCRIPTION
The sxsrmf task first calculates the redistribution matrix file (RMF)
for a selection of SXS pixels and resolution grades (High, Mid, or
Low) by using the line spread function (LSF) parameters stored in two
extensions of a calibration database (CalDB) file, CALDB.
The task then combines these into one RMF
file according to the input file specified by the 'infile' parameter
that contains weighting factors for each combination of pixel and
grade. This file is created by the sxsmkrmf task, and sxsmkrmf is
generally used to create SXS RMF files that encompass multiple pixels
and/or grades. It is a FITS file with three columns, named 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. Alternatively, the RMF for a single pixel (specified by the
'pixel' parameter) and grade (specified by the 'resol' parameter) may
be computed by sxsrmf if 'infile=NONE'.
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 line spread function
(LSF) parameters are stored in designated extensions of the CALDB
files specified by the 'rmfsigma' and 'rmftau' parameters. 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; (3) The large option
(l/L) also includes the escape peaks; and (4) the x-large option (x/X)
also includes the electron loss continuum down to the minimum energy
given by the 'emincont' parameter. Note: the x-large matrix file 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; this option is not
recommended for normal usage.
The output file specifed by 'outfile' is a FITS Standard output RMF
containing the response matrix in the MATRIX extension, and the PI
channel definitions in the EBOUNDS extension. If the parameter
'outrsp=yes', an RSP file with filename specified by the parameter
'outrspfile' may be created by combining the RMF with the ARF
specified by the parameter 'arffile'.
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=32768' 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 = sxsfrac.fits [filename NONE|file name]
- Name of input FITS file containing the weighting factors. If set
to NONE, the RMF for a single pixel and grade is created, as
specifed by the settings of the 'pixel' and 'resol' parameters.
- outfile = response.rmf [filename]
- Name of output RMF file, or NONE if creating only an RSP file.
- (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 'arffile' parameter.
- (arffile = NONE) [filename NONE|file name]
- Name of input ARF file; this parameter is ignored if 'outrsp=no'.
- (rspfile = response.rsp) [filename]
- Name of output RSP file; this parameter is ignored if 'outrsp=no'.
- (pixel = 0) [integer]
- SXS array pixel (0-35) for which the RMF is calculated. For each
run, only one pixel maybe be input. This parameter is ignored unless
'infile' is set to NONE.
- (resol = H) [string H|M|L]
- SXS event resolution grade - (H)igh, (M)id, or (L)ow - for which
the RMF is calculated. For each run, only one grade maybe be input.
This parameter is ignored unless 'infile' is set to NONE.
- (time = 2014-01-01T00:00:00) [string]
- Start time, in YYYY-MM-DDThh:mm:ss format, for validity of RMF LSF
CALDB file extensions 'rmfsigma' and 'rmftau'.
- (whichrmf = L) [string S|M|L|X]
- 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 CALDB|file name]
- Input file containing the parameters for the Gaussian core. If the
parameter is set to CALDB, the file is read from the calibration database, CalDB.
- (rmftau = CALDB) [filename CALDB|file name]
- Input file containing the parameters for the exponential tail,
electron loss continuum, and escape peaks. If the parameter is set to
CALDB, the file is read from the CalDB.
- (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'.
- (nchanin = 32768) [string]
- Number of channels in each energy interval of the input energy
grid for the RMF MATRIX. If a single value (e.g., 'dchanin=32768')
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.
- (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 'useingrid=yes'.
- (nchanout = 32768) [integer]
- Number of channels in the RMF EBOUNDS extension (ouput) energy
grid; this parameter is ignored if 'useingrid=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
'outfile'.
- (emincont = 10.0) [double]
- Lower energy limit [eV] of electron loss continuum.
- (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 an RMF with the default settings, using a weighting factor file.
sxsrmf infile=weightfactor.fits outfile=SXS_output.rmf
- Create RMF and RSP files using the additional input 'arffile' parameter.
sxsrmf infile=weightfactor.fits outfile=SXS_output.rmf outrsp=YES arffile=SXS_input.arf \
rspfile=SXS_output.rsp
- Create a large-sized RMF, SXS_pixel28_Hrez.rmf, for high-resolution
events for pixel 28.
sxsrmf infile=NONE outfile=SXS_pixel28_Hrez.rmf pixel=28 resol=H whichrmf=L
- Create a small-sized (LSF Gaussian core only)
RMF, SXS_pixel18_Mrez.rmf, for mid-resolution events for pixel 18.
sxsrmf infile=NONE outfile=SXS_pixel18_Mrez.rmf pixel=18 resol=M whichrmf=S
- Create a large-sized RMF, SXS_pixel0_Hrez.rmf, for high-resolution
events for pixel 0, where the input grid has variable grid-spacing.
sxsrmf infile=NONE outfile=SXS_pixel0_Hrez.rmf pixel=0 eminin=0 dein="0.5,2.0" nchanin="26000,6500" useingrd=no
SEE ALSO
sxsmkrmf
LAST MODIFIED
November 2, 2023