NAME

sxsmkrmf - Create a Hitomi SXS redistribution matrix file (RMF) and/or an RSP file for selected SXS pixel and grade combinations, with weighting factors derived from an input event file and region.

USAGE

sxsmkrmf infile outfile resolist regmode regionfile

DESCRIPTION

The sxsmkrmf task is a script that calculates an SXS 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 sxsrmf task. If an ARF is provided, sxsmkrmf can output a total response (RSP) file upon request.

The required inputs to sxsmkrmf are: (1) a cleaned SXS event file ('infile') that should be the same as is 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 sxsmkrmf parameters is used to construct a file containing the weights for each combination of grade and pixel (sxsfrac.fits). This file consists of 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 RMF for each pixel and grade is calculated by the sxsrmf task using the line spread function (LSF) parameters stored in designated extensions of the CALDB files specified by the 'rmfsigma' and 'rmftau' parameters. 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.

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 'arfinfile'.

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 = input.fits [filename]
Name of input event file used to calculate the grade and pixel weighting factors.

outfile = response.rmf [filename]
Name of output RMF file, or NONE if creating only an RSP 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.

regmode =SKY [string SKY|DET]
Coordinate system for the region file.

regionfile = ALLPIX [string ALLPIX|NONE|file name]
Region file name. 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 event file.

(decpoint = -999.0) [double]
Pointing DEC [deg]. If 'decpoint' is set to -999, the DEC is read from the DEC_NOM keyword in the event file.

(roll = -999.0) [double]
Roll angle [deg]. If 'roll' is set to -999, the roll is read from the PA_NOM keyword in the event file.

(teldeffile = CALDB) [filename]
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.

(outrspfile = response.rsp) [filename]
Name of output RSP file; this parameter is ignored if 'outrsp=no'.

(arfinfile = NONE) [filename NONE|file name]
Name of input ARF file; this parameter is ignored if 'outrsp=no'.

(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 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 bins 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.

(cleanup = yes) [boolean yes|no]
Delete temporary files.

(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

  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.
  2.    sxsmkrmf infile=sxs_cl.evt outfile=sxs_allpix_large.rmf resolist=0 regionfile=ALLPIX
    
  3. 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.
  4.    sxsmkrmf infile=sxs.evt outfile=sxs_region_small.rmf resolist="0,1" regmode=SKY regionfile=sxs_sky.reg outrsp=yes \ 
          outrspfile=sxs_region_small.rsp arfinfile=sxs_region_small.arf whichrmf=s
    

SEE ALSO

sxsrmf, coordpnt

LAST MODIFIED

November 2, 2023