NAME

USAGE

DESCRIPTION

'sxsrmf' calculates the RMF for each SXS pixel and resolution grade (High, Mid, or Low), by using the line spread function (LSF) parameters stored in two extensions of a CALDB file. Then the task combines these RMFs into one RMF file according to an input file with weighting factors for combinations of pixel and grade. The weighting factor file is created by the 'sxsmkrmf' script, and consist of a fits file with three columms (PIXEL, GRADE, WEIGHT), where WEIGHT is defined as the ratio of counts for the specific PIXEL and GRADE combination of the rmf genertaion to the total in all selected PIXELS.

'sxsrmf' may be run to create an RMF for any SXS pixel and grade combination. This is achived by setting 'infile=none' and use the parameters 'pixel' and 'resol' to select the the pixel and the grade, respectively. If the 'outrsp' parameter is 'yes' and an ARF file is given with the 'arffile' parameter, the task also calculates and outputs an RSP file with filename given by the 'outrspfile' parameter.

The LSF consists 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 latter three components are assumed to be pixel-independent. All these components are stored in CALDB file in the 'linesigma' and 'linetau' tables . Four types of RMF files may be created small, medium, large and x-large. The small (s/S) accounts only for the Gaussian core calculated with a width, defined in the CALDB linesigma table (see 'rmfsigma' parameter). The medium (m/M) includes also the exponential tail for the line defined in the caldb linetau table (see 'rmftau' parameter); the large (l/L) includes the escape peaks. The x-large (x/X) adds the continuum down to the minimum energy given by the 'emincont' parameter. Note that the x-large requires a minimum of 2 GB of memory, so this option is not recommended for normal usage.

The output RMF contains a MATRIX extension, which contains the reponse 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.

PARAMETERS

infile [filename]

Name of input FITS file containing the weighting factora. If set to NONE the rmf for a single pixel and grade is created corresponding to the settings of the pixel and resol parameters, respectively.

outfile [filename]

Name of output RMF file.

(outrsp = no) [boolean]

If yes, an output RSP file is created by combining the rmf with the input arf file specified by the arffile parameter (yes/[no]).

(arffile = NONE) [filename]

Name of input ARF file. This parameter is ignored if outrsp=no.

(rspfile) [filename]

Name of output response (RSP) file. This parameter is ignored if outrsp=no.

(pixel = 0) [integer]

SXS array pixel (0-35) for which the RMF is calculated. Fof each run only one pixel maybe be input. This parameter is ignored unless infile is set to NONE.

(resol = H) [string]

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 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 requires a minimum of 2 GB of memory, and 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]

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

EXAMPLES

1. Create an RMF file with the default settings, using a weighting factor file.

      sxsrmf infile=weightfactor.fits outfile=SXS_output.rmf

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

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

4. Create a small-sized (line-spread function 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

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

LAST MODIFIED