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 the output units are the ARF are in square centimeters (except for the "flat" model, see below).
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:
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.
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.
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=YESwhere 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=NICTZFIXand the following response should be produced
NICTZFIX= T / Fix for NICER TIMEZERO bug in placeIf 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.
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.evtwhere
xti/events_cl/niNNNNNNNNNN_0mpu7_cl.evtis 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.mkfwhere
auxil/niNNNNNNNNNN.mkfis 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.
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.
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.arfThe $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.arfNote 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.
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=targvigfileThe 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=targvigfileThe 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.
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
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)