nicerrmf HEADAS help file

NAME

nicerrmf - calculate NICER response (RMF or RSP)

USAGE

nicerrmf infile mkfile outfile

DESCRIPTION

The nicerrmf task computes the NICER response matrix, either RMF or RSP, for the NICER observatory. This is a high level task that combines the operation of several lower lower level tasks with multiple calibration files. The output is a NICER response matrix, which can be used for NICER spectral analysis.

The RMF encapsulates the detector-dependent effects of of so-called "redistribution." These effects correspond to physics which causes a range of pulse heights to be measured even when a monochromatic X-ray source is incident upon the detector. These effects include resolution, partial or incomplete charge collection, and broadening due to finite detector thickness. The RMF also contains the effects of the detector "trigger efficiency function," which is the energy dependent shape of the lower level discriminator througput profile. Some of these effects depend on the conditions of each individual observation, therefore, they must be calculated on a case by case basis.

Another response file type, commonly known as "RSP", combines both the "ARF" and "RMF" effects into a single file. nicerrmf is capable of generating RSP files if a list of ARFs is supplied. This is the recommended mode of operation.

The inputs to nicerrmf are described in more detail below, but can be summarized as:

Input spectrum (.pha file)
Filter file (used for undershoots)
Optional list of detectors, although nicerrmf can take a list of ARFs produced by nicerarf (recommended).
GTI attached to input spectrum
Calibration inputs, typically retrieved from CALDB (Detector parameter file and "base" RMF file).

The primary output of nicerrmf is the single averaged RMF (or summed RSP) file representing the energy-dependent response of the entire NICER detector array. NICER uses the OGIP standards for response files, which are compatible with most X-ray spectral analysis packages. Optionally, if savedetrmf=YES, the user can save individual per-module RMFs.

Specifying a Detector List

Like other NICER tasks, nicerrmf accepts the "detlist" parameter, which can be used to calculate the response for the all or some detectors.

NICER consists of 56 individual modules, of which 52 are nominally operational since before launch. The response of each module is slightly different from the others, so it is important to compute the response of the correct list of detectors.

While the standard complement of detectors is 52, it is possible that fewer detectors are enabled for a given observation. This may be intentional: for example, for very intense targets, the NICER operations team may disable some detectors in order to reduce the telemetry load. It also may be unintentional: for example, detectors may disable themselves as a response to a reported fault condition.

Of course, list of enabled detectors may not even be constant during an observation. This adds to the complication of calculating a correct response.

Finally, for reasons other than operational disabling detectors, the analyst may wish to de-select certain detectors (for example if they are on but noisy).

The "detlist" parameter has several flexible ways to specify a list of detectors.

detlist=@arffiles.lis (recommended) The recommended way to use this task is to specify a list of ARF files, as produced by nicerarf's outdetlisfile parameter. nicerrmf will read each ARF and automatically weight each detector's RMF by the corresponding ARF value. This gives the most accurate estimate of the total detector throughput and resolution. When using outmode=RSP, you must specify a list of ARF files in this manner.
detlist=list of detectors and weights The analyst can manually specify a list of detectors with weights in a comma-separated list, or as an @file.lis form. This format is produce by nicerarf's outwtfile parameter, for ease of transfer of number of detectors from the ARF stage to the RMF stage, and is recommended if the @arffiles.lis method is not used. The form of each list element is
detector_number weight
where weight is a floating point number. Example:
detlist="00 1.0,01 1.1,02 1.2"
would consider detector 00 with weight 1, 01 with weight 1.1 and 02 with weight 1.2. Analysts should use outmode=RMF in this case, so that the total weights are divided out.
detlist=list of detectors. The analyst can specify a simple comma-separated list of detectors. This technique is most useful when the user has manually selected certain detectors and wishes to calculate a response for the same detectors. The list elements specify which detectors are to be enabled, or disabled (by preceding the detector number with a '-' minus sign). Additionally, the shorthand notation of "all" or "launch" in the first position of the list indicates to enable all or pre-launch detector subset. The list is read from left to right, so it is possible to specify both. Example:
detlist=launch,-14,-34
considers all detectors functioning at launch, but excluding detectors 14 and 34.

RMF versus RSP

As described above, the analyst can output either an RMF or RSP, by specifying the outmode parameter as weither "RMF" or "RSP".

For most spectral analysis, it is recommended to set detlist=@arffiles.lis and outmode=RSP. This gives the convenience of having a single response file, and in addition, the response is slightly more correctly used within XSPEC. When using outmode=RMF with input ARFs, the responses are averaged, which is not quite as correct as using a combined output (although the differences are very small). A downside to this approach is that the user must run nicerarf with savedetarf=YES, which produces 52 separate ARF files; this can be cumbersome to manage.

If the analyst has a single ARF file (as produced by nicerarf with savedetarf=NO), or just simply wishes to perform spectral analysis with a separate RMF and ARF file, the user can set outmode=RMF.

If the analyst specifies either kind of manual detector list, they are recommended to set outmode=RMF. This produces an averaged RMF which can be used within XSPEC.

Specifying Accurate Time Filtering

It is important to supply accurate time filtering information so that nicerrmf can estimate an accurate weight for each detector's contribution. Users can specify a Good Time Interval (GTI) file which running nicerrmf using the gtifile parameter.

Normally, a GTI file is attached to the input .pha file, and for NICER the extension name is "GTI". For that reason, the default value for gtifile is "$INFILE[GTI]". At runtime, nicerrmf substitutes the name of the input file for "$INFILE" before attempting to use the name. Therefore, for most cases, the user can leave the default value of gtifile unchanged, and it will use the GTI extension of the input file. If, for whatever reason, this is not the correct action, the user can always specify an explicity filename and [extension] for the gtifile parameter.

Calibration Inputs

The nicerrmf task uses multiple calibration inputs to compute an accurate ARF. These are typically accessed from NICER's Calibration Database, or CALDB. The default values of the nicerrmf task specify the correct CALDB specifications and the user is not recommended to change them.

Saving Additional Detailed RMF Information

By default, nicerrmf saves the average RMF for the selected detectors as described above.

In some cases, the user may wish more detailed information about the per-detector responses that went into the final response output. There are several parameters that control these output options.

Use savedetrmf=YES to save per-detector RMFs as separate files. One file is created per detector. The parameter outdetform is used to create each file. The format looks something like this

  $OUTFILE_detid$DETID.rmf

The $DETID pattern is replaced with the detector ID, and the $OUTFILE pattern is replaced by the outfile parameter (with any trailing suffix removed). For example if outfile=source.rmf, the above pattern will save per-detector ARFs to

  source_detid00.rmf
  source_detid01.rmf
  ...
  source_detid67.rmf

Note that the original source.rmf name has its ".rmf" extension removed, and then the _detidNN.rmf string is appended.

Each of the per-detector RMF files contains a valid ARF that could be used for analysis of a spectrum from a single detector. IMPORTANT: it is still required that any such single-detector spectrum have the same GTI as for the full-array spectrum the nicerrmf run was based upon. If you change the GTI, then you need to re-run nicerrmf.

PARAMETERS

infile [filename]: Input spectrum file name for which the RMF is to be calculated. This name can be used as pattern substitution $INFILE for some parameters.
mkfile [filename]: Name of the filter file (.mkf file). This file contains undershoot information.
outfile [filename]: Name of output RMF file. This name can be used as pattern substitution $OUTFILE for some parameters.
(detlist=launch) [string]: List of detectors to process, as describe above. This can be a list of ARFs, a list of detectors, or a list of detector+weight pairs. The @file.lis syntax can also be used to read from a file. See above for more details and examples.
(gtifile="$INFILE[GTI]") [string]: File name[extension] containing the Good Time Interval used to create the input spectrum file. The patterns $INFILE and $OUTFILE are replaced by the infile and outfile parameters. Therefore, the default setting of "$INFILE[GTI]" will look for the GTI extension of the input file.
(detparfile=CALDB) [string]: Name of detector response parameter file, or CALDB.
(lotrigfile=AUTO) [string]: Name of detector lower energy trigger efficiency file name. A value of "AUTO" indicates to use the same file as detparfile, which is the default. Users can also choose "PI" or "PI_FAST" explicitly to choose the trigger efficiency from the slow or fast channel respectively (which is searched in CALDB). A value of "NONE" indicates to not apply a lower trigger efficiency curve (not recommended). Note that if trigeff=NO, then this file is ignored.
(hitrigfile=NONE) [string]: Name of detector lower energy trigger efficiency file name. A value of "AUTO" or "NONE" indicates to not apply a lower trigger efficiency curve, which is the default. Users can also choose "PI" or "PI_FAST" explicitly to choose the trigger efficiency from the slow or fast channel respectively (which is searched in CALDB). Note that if trigeff=NO, then this file is ignored.
(basermf=CALDB:BASE) [string]: Name of the "base" RMF to use for response calculations, or "CALDB:BASE" to retrieve from CALDB (recommended).
(chantype=AUTO) [string]: Name of channel type of the spectrum being operated on, either "PI" or "PI_FAST". A value of "AUTO" will cause the task to query the input spectrum file for which channel type to use (recommended).
(updatepha=NO) [boolean]: If set, then update metadata keywords of the input file to reflect the RMF file. Note that only the filename component of the file is added and not the path component, since this often causes problems with XSPEC.
(outmode=RMF) [string]: Specifies format of the output file, as described above. The RMF corresponds to a pure detector redistribution (RMF) file, while RSP corresponds to a combined (RMF+ARF) file. RSP should only be used if detlist is a list of ARF files.
(filtexpr=NONE) [string]: A filtering expression to be applied to the filter file, or NONE. The GTI time filtering is performed in addition to filtexpr.
(undercol="MPU_UNDERONLY_COUNT") [string]: Name of undershoot column in the filter file.
(underbin=10.0) [real]: Bin size for internal histogram used for undershoots, in units of undershoots per second per detector.
(undermax=800.0) [real]: Maximum value for internal histogram used for undershoots, in units of undershoots per second per detector.
(thrcol="DELTA_SLOW_LLD") [string]: Name of array-averaged threshold setting, which is used to calculate the low-energy trigger efficiency function. If the column is not found, the task assumes the threshold setting is nominal.
(thrbin=1.0) [real]: Bin size for internal histogram used for threshold setting, in units of threshold ADU values, relative to nominal.
(thrmin=-10.0) [real]: Minimum value for internal histogram used for threshold setting, in units of threshold ADU values, relative to nominal.
(thrmax=300.0) [real]: Maximum value for internal histogram used for threshold setting, in units of threshold ADU values, relative to nominal.
(pimax=1500) [integer]: Maximum PI value. This should match the maximum PI value in the spectra to be analyzed.
(pigain=0.010) [real]: Number of keV per PI bin. This value should not be changed by the user.
(trigeff=YES) [boolean]: If yes, compute trigger efficiency function. If no, then the trigger efficiency profile is ignored. Note that even if trigeff=YES, no trigger efficiency is calculated for lower trigger efficiency curve when lotrigfile=NONE, and for high trigger efficiency curve when hitrigfile=NONE.
(npad=23) [integer]: Number of PI bins of padding used in convolution calculation.
(nsigma=4.0) [real]: Number of "sigma" widths to calculate for gaussian convolution kernel.
(savedetarf=YES) [boolean]: A boolean indicating whether per-module RMF files should be saved. If NO, these intermediate values are not saved for final output.
(outdetform="$OUTFILE_detid$DETID.rmf") [string]: If savedtarf=YES, per-module RMFs are saved with this file name format pattern. $INFILE and $OUTFILE are replaced by the infile and outfile parameters, after removing any trailing suffix. $DETID is replaced by the detector ID number.
(lothresh=40.0e-7) [real]: Lower level threshold to apply to all output responses. Values less than this are artificially set to zero. Because of the convolution operation, there is some noise, which lothresh can screen out.
(cleanup="YES") [boolean]: If yes, then clean up temporary files. If no, temporary files remain. This is typically for debugging.
(clobber = NO) [boolean]: If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.
(chatter = 2) [integer, 0 - 5]: Controls the amount of informative text written to standard output. Setting chatter = 4 or higher will produce detailed diagnostic output; chatter = 1 prints out a basic diagnostic message. The default is to produce a brief summary on output.
(history = YES) [boolean]: If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the nicerrmf task parameters that were used to produce the output file.

EXAMPLES

Run nicerrmf for myspectrum.pha, using the spectrum's GTI, for all pre-launch operating detectors. The filter file is ni1234567890.mkf. The output is saved in myspectrum.rmf and is an RMF file.

nicerrmf myspectrum.pha ni1234567890.mkf myspectrum.rmf detlist=launch outmode=RMF

Same as above, but calculate an RMF file using per-detector ARFs as energy-dependent weighting. These ARFs are assumed to be of the form myspectrum_detid??.arf.

ls myspectrum_detid??.arf > myspectrum_arf.lis
nicerrmf myspectrum.pha ni1234567890.mkf myspectrum.rmf detlist=@myspectrum_arf.lis outmode=RMF

(note that the "ls" command locates all files that match the given ARF pattern and saves them to the file myspectrum_arf.lis).

Same as above, but calculate an RSP file using per-detector ARFs as energy-dependent weighting. This will be a total response (RSP file)

ls myspectrum_detid??.arf > myspectrum_arf.lis 
nicerrmf myspectrum.pha ni1234567890.mkf myspectrum.rsp detlist=@myspectrum_arf.lis outmode=RSP

LAST MODIFIED

Jan 2022