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
SEE ALSO
niprefilter
nicerarf
OGIP CAL/GEN/92-019 - "THE OGIP FORMAT FOR EFFECTIVE AREA FILES"
OGIP CAL/GEN/92-002 - "The Calibration Requirements for Spectral Analysis"
(Definition of RMF and ARF file formats)
LAST MODIFIED
Jan 2022