NAME

nicerarf - calculate NICER effective area (ARF)

USAGE

nicerarf infile ra dec attfile selfile outfile

DESCRIPTION

The nicerarf task computes the effective area, or ARF, 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 an ARF (Ancillary Response File), which can be used for NICER spectral analysis.

The ARF is basically the total energy-dependent throughput of NICER's optics and detector systems. It includes the effects of reflectivity of NICER's X-ray Concentrators (XRCs), thermal films and windows, and the Focal Plane Module (FPM) detector quantum efficiency. Some of these effects depend on the conditions of each individual observation, therefore, they must be calculated on a case by case basis.

The task nicerarf is the combination of the following processes.

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

The primary output of nicerarf is the single summed ARF file representing the energy-dependent effective area 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 savedetarf=YES, the user can save individual per-module ARFs. The effective area column is named "SPECRESP" and he output units are the ARF are in square centimeters (except for the "flat" model, see below).

Specifying Target Location and Spatial Characteristics

The target position must be specified using the "ask" parameters ra and dec. These are the Right Ascension and Declination, respectively, in J2000 degrees.

By default nicerarf calculates the response for a point source. However it is capable of calculating the response for more complicated spatial surface brightness profiles:

Please see the help for the nivignette task for more information and details. An important warning to bring up is that except for the "flat" profile, nicerarf calculates for all other profiles response to the total flux (i.e. if only 50% of the sources surface brightness profile overlaps with the NICER field of view, the response will be about half of that for an on-axis point source).

For objects with spatial extent smaller than about 10 arcsec, it is worth using the "point" profile; for objects larger than about 180 arcsec radius, the performance of the "flat" model will be dramatically faster.

The "flat" model is special in that it computes the response to a source with uniform surface brightness. The output in this case is area x solid angle units. The solid angle unit depends upon the angunit setting. (Example, for angunit="sr" the output units are cm2*sr). Please beware that when using modeling software like XSPEC, the "flux" norm of the model should be considered as flux per unit solid angle.

Specifying Accurate Time Filtering

It is important to supply accurate time filtering information so that nicerarf can estimate an accurate weight for each detector's contribution. Users can specify a Good Time Interval (GTI) file which running nicerarf 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, nicerarf 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.

Important Bug Fix: Correcting NICER TIMEZERO Bug

Users of NICER software version 8b or earlier are affected by a bug in how FPM Selection data is computed. This bug is due to timestamp calculation error related to the TIMEZERO keyword, hence the "NICER TIMEZERO bug." This causes a 1 second shift between the GTI and the FPM selection calculation.

For a typical NICER observation, the effect of the NICER TIMEZERO bug may be less than 0.1%; but in cases of many small good time intervals (also known as "shredded" GTIs), the effect may be highly magnified, with errors of 10-30%, or more.

This bug has been fixed in NICERDAS 8c and later (HEASoft 6.29c or later). NICERDAS 8c inserts a keyword into output event files called NICTZFIX, which indicates that the problem has been fixed. nicerarf will look for this keyword, and if it is not found, require the event file to be fixed.

For existing event files, the FPM selection information can be fixed without re-running nicerl2 or any data selections. The niextract-events task (distributed with NICERDAS 8c) will fix existing files and insert the required keyword. Run the task as follows,

   niextract-events events.evt events_fixed.evt clobber=YES
where events.evt is the event file to be fixed, and events_fixed.evt is the fixed event file. You can verify that the event file has been fixed by looking for the required NICTZFIX keyword, using the following command,
  ftlist events_fixed.evt'[FPM_SEL]' K include=NICTZFIX
and the following response should be produced
NICTZFIX=                    T / Fix for NICER TIMEZERO bug in place
If no line is printed, or the value of the keyword is not the expected value of 'T'rue, the niextract-events fix above should be applied.

Understanding How nicerarf Deals With Enabled/Disabled 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).

NICER's response calculators can handle all of these situations.

Detector on-off and select-deselect information is stored in either the event file, which should have a full set of "FPM Selection" data, or the filter file, which has only on-off data. Both of these options are described in more detail in the following paragraphs.

For data processed with HEASoft 6.29 or later, the event file should contain "FPM Selection" information. This information is encapsulated in an extension named "FPM_SEL" as well as several trailing GTI extensions. For most users that have processed their data with recent software, it is recommended to set

selfile=xti/events_cl/niNNNNNNNNNN_0mpu7_cl.evt
where
xti/events_cl/niNNNNNNNNNN_0mpu7_cl.evt
is the full path to the "cleaned" event file with FPM Selection extensions. This will provide the most accurate exposure and detector weighting information.

If an event file with FPM Selection data is not available (for example, because of event files processed with older software revisions), it is still possible to use nicerarf. The filter file (or .mkf file) is located in the observation directory under auxil/niNNNNNNNNNN.mkf (where NNNNNNNNNN is the 10-digit observation ID). The column FPM_ON in the filter file contains the enable/disable information for each individual detector. This will allow the ARF to be weighted by enabled/disabled detectors, but individual detectors that have been removed from the event file by the analyst will need to be specified by hand on the command line using the detlist parameter.

Only if the analyst has a file without FPM Selection information, they should set

selfile=auxil/niNNNNNNNNNN.mkf
where
auxil/niNNNNNNNNNN.mkf
is the full path to the filter file. Since manual filtering of event files is not handled properly when using this method, the user will also have to set the detlist parameter.

The nicerarf parameters that control the detector-selection behavior of nicerarf are selfile (an "ask" parameter), and detlist (defaults to "launch"). selfile provides the name of the file with detector selection information, typically the cleaned event file (although the filter file can be used with some loss of information), and selcol is the name of the column to use to retrieve the information, which by default nicerarf will determine automatically. detlist is a comma-separated list of detectors to include or exclude.

Let us take a step back now and consider several use cases.

Calibration Inputs

The nicerarf 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 nicerarf task specify the correct CALDB specifications and the user is not recommended to change them.

Saving Additional Detailed ARF Information

By default, nicerarf saves the total effective area for the selected detectors as described above.

In some cases, the user may wish more detailed information about the inputs to the final summed ARF. There are several parameters that control these output options.

Use savedetarf=YES to save per-detector ARFs 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.arf
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.arf, the above pattern will save per-detector ARFs to
  source_detid00.arf
  source_detid01.arf
  ...
  source_detid67.arf
Note that the original source.arf name has its ".arf" extension removed, and then the _detidNN.arf string is appended.

Each of the per-detector ARF 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 nicerarf run was based upon. If you change the GTI, then you need to re-run nicerarf.

An additional level of detail can be revealed using the saveshellarf=YES setting. When this is set, the per-module ARFS contain the individual area contributions of each XRC optic shell. There are 24 shells per optic, so there are 24 additional columns in each file when saveshellarf=YES. The columns are named AREA_Dnn_SHnn where the first nn is the detector ID and the second nn is the shell number, from 01 through 24. These columns are in the same units as the per-module and array total ARF values.

Saving Execution Time For Repeated Runs

In some cases, the user may wish to run nicerarf many times, but for different input spectra, or to select different detectors.

Some nicerarf activities can be run once and be re-used multiple times thereafter. These activities also may be particularly time-consuming for long observations or diffuse targets. The outputs of these activities are known as the targdet and targvig files. They contain generic target coordinate and vignette profile information before any selection by time or detector has been performed. Thus, they can be re-used in later runs.

To activate this behavior of nicerarf, the first time the task is run, use these settings,

   targvigop=CALC targdetfile=targdetfile targvigfile=targvigfile 
The targvigop=CALC parameter setting tells nicerarf to calculate these two files and save them in the files named by targdetfile and targvigfile. These files can have any name desired (but not the same as the other).

To re-use these files, use these settings,

   targvigop=REUSE targdetfile=targdetfile targvigfile=targvigfile 
The only change is now targvigop is REUSE. Use the same file names as when the files were CALC'd. nicerarf will use these files and skip past much of the time-consuming computation work.

IMPORTANT NOTE: the REUSE feature should not be used if the source profile changes (i.e. surface brightness profile is different), or if you changed to a different observation or filter file. In that case you must go back to targvigop=CALC.

PARAMETERS

infile [filename]
Input spectrum file name for which the ARF is to be calculated. This name can be used as pattern substitution $INFILE for some parameters.
ra [real]
Right ascension of target in J2000 degrees.
dec [real]
Declination of target in J2000 degrees.
attfile [filename]
Name of file containing attitude information. This can be either the filter file or a NICER niNNNNNNNNNN.att attitude file.
selfile [filename]
FPM selection file. This should be either the event file that has FPM Selection information (preferred), or the filter file.
outfile [filename]
Name of output ARF file. This name can be used as pattern substitution $OUTFILE for some parameters.
(selcol="INDEF") [string]
Column to use in the FPM Selection file, or "INDEF" to select the column automatically. Although changing the default is usually not necessary, the correct column for a filter file would be FPM_ON and for an event file with FPM Selection information is FPM_SEL.
(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.
(updatepha=NO) [boolean]
If set, then update ANCRFILE keywords of the PHA file to reflect the ARF file. Note that only the filename component of the file is added and not the path component, since this often causes problems with XSPEC.
(profile="point") [string]
X-ray surface brightness profile name. Must be one of "point" (point-like), "flat" (flat sky background), "gaussian" (Gaussian).
(profpar="NONE") [string]
Special parameters for given X-ray surface brightness profile. For the gaussian profile (profile="gaussian") it is required to specify the Gaussian sigma value as profpar="sigma:value" where value is the Gaussian standard deviation of each axis. For other profiles that do not require special parameters, set profpar=NONE
(angunit="arcsec") [string]
Specifies the units of angular quantities. In particular, when profile="flat", angunit specifies the units of solid angle. Allowed values are "arcsec", "arcmin", "deg", "rad", "sr". For example, when angunit="arcsec" the output units will be arcsec^2.
(detlist="launch") [string]
A comma-separated list of detectors to include or exclude. This list is evaluated from left to right, in that order. Each list item can be: If the first list item is an exclusion, then it is assumed that "launch" detectors are enabled to begin with.
(outwtfile="NONE") [string]
Output file to write detector weighting factors, useful for input to nicerrmf when performing non-ARF weighting of the RMF. A value of "NONE" disables this output.
(outvigsumfile="NONE") [string]
Output file to write the vignette summation file. This data is used internally for ARF calculation and may be used externally for debugging purposes. A value of "NONE" disables this output.
(outdetlisfile="NONE") [string]
Name of file, which upon output contains a list of per-detector ARFs created by this task. If set to NONE, then this file is not created. This file is useful as input to nicerrmf when performing ARF-weighting of the RMF.
(vigfile="CALDB") [string]
Vignette profile calibration file, or CALDB.
(xrcshellfile="CALDB") [string]
XRC shell calibration file, or CALDB.
(xrcalignfile="CALDB") [string]
XRC alignment calibration file, or CALDB.
(ebinfile="CALDB:BASE") [string]
Name of file containing response matrix to use as energy binning. This should be a response matrix file MATRIX extension containing columns ENERG_LO and ENERG_HI. A value of "CALDB:BASE" queries CALDB for the "base" RMF.
(efftabfiles="CALDB:XRC_SHIELD,CALDB:DET_WINDOW,CALDB:DET_QE,CALDB:XRC_CORR") [string]
Comma-separated list of efficiency tables. Each list item should be a file name conforming to the OGIP window transmission function standard. It can also be CALDB:elem, where elem is an element stored in CALDB. The listed elements in the default, XRC_SHIELD, DET_WINDOW and DET_QE should not be changed.
(targdetfile="NONE") [string]
Name of targdet file. When targvigop=CALC, the targdet file is saved with this file name. When targvigop=REUSE, then nicerarf uses the listed file for target coordinates.
(targvigfile="NONE") [string]
Name of targvig file. When targvigop=CALC, the targvig file is saved with this file name. When targvigop=REUSE, then nicerarf uses the listed file for vignette profile data.
(targvigop="CALC") [string]
The operation for calculating or re-using the targdet and targvig files, as described in the main text. Either "CALC" or "REUSE".
(savedetarf=NO) [boolean]
A boolean indicating whether per-module ARF files should be saved. If NO, these intermediate values are not saved for final output.
(outdetform="$OUTFILE_detid$DETID.arf") [string]
If savedtarf=YES, per-module ARFs 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.
(saveshellarf=NO) [boolean]
A boolean indicating whther per-shell ARF data is included in the per-module ARF files or not.
(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 nicerarf task parameters that were used to produce the output file.

EXAMPLES

Run nicerarf for myspectrum.pha, using the spectrum's GTI. The target's RA and Dec are 1.23 and -17.32, respectively, in degrees, and is a point source. The filter file is ni1234567890.mkf. The output is saved in myspectrum.arf.

nicerarf myspectrum.pha 1.23 -17.32 ni1234567890.mkf ni1234567890.mkf myspectrum.arf

The same operation as above, but exclude detectors 14 and 34.

nicerarf myspectrum.pha 1.23 -17.32 ni1234567890.mkf ni1234567890.mkf myspectrum.arf \
   detlist=launch,-14,34

The same operation as above, but using an FPM selection file named myspectrum_fpmsel.fits, with selection column FPM_SEL.

nicerarf myspectrum.pha 1.23 -17.32 ni1234567890.mkf myspectrum_fpmsel.fits myspectrum.arf \
   selcol=FPM_SEL

The same operation as the first, but for a target with gaussian surface brightness distribution (with gaussian sigma of 60 arcsec).

nicerarf myspectrum.pha 1.23 -17.32 ni1234567890.mkf ni1234567890.mkf myspectrum.arf \
   profile=gaussian profpar=sigma:60

The same operation as the first, but for a uniform (flat) sky background. Fluxes in XSPEC will be measured per square degree.

nicerarf myspectrum.pha 1.23 -17.32 ni1234567890.mkf ni1234567890.mkf myspectrum.arf \
   profile=flat angunit=deg

SEE ALSO

nitargdet

nivignette

niprefilter

nicerrmf

OGIP CAL/GEN/92-024 - "THE OGIP FORMAT FOR FILES CONTAINING FILTER & WINDOW TRANSMISSIONS"

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

Mar 2021