NAME

USAGE

DESCRIPTION

'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 PI channel.

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

PARAMETERS

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 spectrum.

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 integers.

(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 (yes/[no]).

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

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.

  sxsmkrmf infile=sxs_cl.evt outfile=sxs_allpix_large.rmf resolist=0 region=ALLPIX

  sxsmkrmf infile=sxs.evt outfile=sxs_region_small.rmf resolist=0,1 region=sxs_sky.reg outrsp=yes outrspfile=sxs_region_small.rsp \
  arfinfile=sxs_region_small.arf whichrmf=s

SEE ALSO

LAST MODIFIED