HEADAS help file

NAME

rslrmf - Create a XRISM Resolve redistribution matrix file (RMF) for selected Resolve pixels and grades with weighting factors

USAGE

rslrmf infile outfileroot

DESCRIPTION

The rslrmf task first calculates the redistribution matrix file (RMF) for a selection of Resolve pixels and resolution grades. There are five possible grades: Hp (high-res), Mp (mid-res, primaries), Ms (mid-res, secondaries), Lp (low-res, primaries), and Ls (low-res, secondaries). If 'outrsp=yes', the RMF is combined with the auxiliary response file (ARF) file specified by the parameter 'arfinfile' to create a total response (RSP) file. Note that the ARF must have an energy grid that matches the input energy grid of the RMF (set by the parameters 'eminin', 'dein', and 'nchanin'). The task uses the line spread function (LSF) parameters stored in multiple extensions of a calibration database (CalDB) file to calculate an RMF for each pixel and each grade. It 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 can be created by the rslmkrmf task (rslfrac.fits), which runs rslrmf to create Resolve RMFs that encompass multiple pixels and/or grades. 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 weights 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. Alternatively, the RMF for a single pixel (specified by the 'pixel' parameter) and grade (specified by the 'resol' parameter) may be computed by rslrmf if 'infile=NONE'.

Currently the CalDB parameter file (specified by 'rmfparamfile') 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.

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. The LSF parameters are stored in designated extensions of the CalDB file specified by the 'rmfparamfile' parameter. 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 the Si K alpha emission 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 combining the RMF and ARF files.

The output file specifed by 'outfileroot'+".rmf" or 'outfileroot'+".rsp" is a FITS standard, and contains 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.

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 = rslfrac.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.
outfileroot = response [string]: Output root name for all output files.
(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, retaining only the RSP file.
(arfinfile = NONE) [filename NONE|file name]: Name of input ARF file. This parameter is ignored if 'outrsp=no'.
(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.
(pixel = 0) [integer]: Resolve 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 = Hp) [string Hp|Mp|Ms|Lp|Ls]: Resolve event resolution grade to use for the response matrix calculation if not using the weights file. Hp: high-res, primary, Mp: mid-res, primary, Ms: mid-res, secondary, Lp: low-res, primary, and Ls: low-res secondary. For each run, only one grade may be input. This parameter is ignored unless 'infile' is set to NONE.
(secondaries = yes) [boolean yes|no]: If 'secondaries=yes', primaries calibration will be used for secondaries, if no secondaries calibration is available. Specifically, Mp calibration will be used for Ms, and Lp for Ls. If Ms or Ls calibration exists, it will always be used, regardless of the value of the 'secondaries' parameter, However, if 'secondaries=no' and no secondaries calibration is available, the task aborts.
(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, or CALDB.
(whichrmf = L) [string S|M|L|X]: Type of RMF to construct - (S)mall, (M)edium, (L)arge, or (X)tra-large. See the description section above for an explanation of which LSF components are included in each type of RMF.
(eminin = 0.0) [double]: Minimum energy [eV] of the RMF MATRIX extension 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 extension. 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 a calculated matrix element value is less than 'rmfthresh' it is set to 0 before being recorded in the output RMF file.
(emincont = 10.0) [double]: Lower energy limit [eV] of the electron loss continuum (ELC). For energies less than 'emincont' the ELC is effectively forced to zero, even if non-zero calibration data exist at those energies.
(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, rsl_output.rmf, with the default settings, using a weighting factor file, weightfactor.fits.

   rslrmf infile=weightfactor.fits outfileroot=rsl_output

Create an RSP file, rsl_output.rsp, using an input ARF, rsl_input.arf.

   rslrmf infile=weightfactor.fits outfileroot=rsl_output outrsp=YES arfinfile=rsl_input.arf

Create a large-sized RMF, rsl_pixel28_Hrez.rmf, for high-resolution events for pixel 28.

   rslrmf infile=NONE outfileroot=rsl_pixel28_Hrez pixel=28 resol=HP whichrmf=L

Create a small-sized (LSF Gaussian core only) RMF, rsl_pixel18_Mrez.rmf, for mid-resolution primary events for pixel 18.

   rslrmf infile=NONE outfileroot=rsl_pixel18_Mrez pixel=18 resol=MP whichrmf=S

Create a large-sized RMF, rsl_pixel0_Hrez.rmf, for high-resolution events for pixel 0, where the input grid has variable grid-spacing.

   rslrmf infile=NONE outfileroot=rsl_pixel0_Hrez pixel=0 eminin=0 dein="0.5,2.0" nchanin="26000,6500" useingrd=no

Create x-large RMFs that are split into the core (rsl_pixel0_0to30kev_MpForMs.rmf) and ELC (rsl_pixel0_0to30kev_MpForMs_elc.rmf) response for mid-resolution secondaries for pixel 0, forcing the use of calibration data for mid-resolution primaries. The matrix is binned by a factor of 64 compared to the core matrix.The input energy range is 0-30 keV in 0.5 eV bins and the output energy grid is set to be the same as the input energy grid.

    rslrmf infile=NONE outfileroot=rsl_pixel0_0to30kev_MpForMs pixel=0 whichrmf=X eminin=0 dein=0.5 \
       nchanin=60000 splitrmf=yes elcbinfac=64 resol=MS secondaries=yes useingrd=yes

Create x-large RSP files that are split into the core (rsl_pixel0_0to30kev_H.rsp) and ELC (rsl_pixel0_0to30kev_H_elc.rsp) response for high-resolution events, using the weights file weightfactor.fits and the ARF file rsl_input.arf. The ELC matrix is binned by a factor of 32 compared to the core matrix. The input energy range is 0-30 keV in 0.5 eV bins and the output energy grid is set to be the same as the input energy grid.

    rslrmf infile=NONE outfileroot=rsl_pixel0_0to30kev_H infile=weightfactor.fits outrsp=yes \
       arfinfile=rsl_input.arf whichrmf=X eminin=0 dein=0.5 nchanin=60000 splitrmf=yes useingrd=yes

LAST MODIFIED