NICER Response Common Issues


NICER provides a sophisticated way to estimate ARF and RMF responses for a particular spectrum. However, there may be issues or problems encountered. This thread discusses various issues encountered when generating NICER responses, and how they can be corrected.

Read this thread if you want to: Understand and correct NICER response calculation issues.

Last update: 2022-04-28


Starting with HEASoft 6.29, NICER provided a new way to generate responses for NICER spectra. These tools, nicerarf and nicerrmf, and very powerful because they can calculate responses which are tailored to the specific conditions encountered by NICER when observing the spectrum.

In previous software releases, NICER supported precomputed responses, which were designed for the specific case of an on-axis point-like target, observed in benign conditions. The new response calculators take into account the possibility of an off-axis target, enabled and disabled detectors, and the possibility of enhanced optical loading conditions, which may slightly change the NICER spectral resolution. Because these types of conditions are not constant, and indeed may vary even during a single observation, the response calculator tools must use recorded housekeeping data in order to estimate the impacts to the responses. The response tools must have accurate target coordinate, timestamps, housekeeping and detector enable/disable information in order to estimate an accurate response.

To read more about the response calculators, please see the NICER ARF & RMF analysis thread for more information.

The following sections will discuss problems commonly encountered when generating NICER responses.

Response Calculator Inputs Must All Be Unbarycentered

The NICER ARF and RMF tools are not compatible with barycentered data. The event list and spectrum used as input to nicerarf and nicerrmf must not be barycentered.

The reason for this restriction is accurate timestamp matching. There are multiple inputs that are used by 'nicerarf' which contain timestamps and GTIs. This includes the filter file, the event list, the event file's FPM selection data, and the spectrum's GTI. All of these sets of information must be recorded in the same time system, i.e. the unbarycentered time system.

Using barycentered event files as direct input to nicerarf will lead to incorrect results. The same is true if a spectrum generated from barycentered data is provided to nicerarf. The problem is that, while the event file and/or spectrum's GTIs are barycentered, the filter file and FPM selection information are NOT barycentered. This will cause nicerarf to cross-index to the incorrect values.

In some cases it will APPEAR that nicerarf produced a response file when using barycentered inputs, but this result may not be correct. This would happen when nicerarf was still able to find matching barycentered and non-barycentered timestamps, but the refer to the wrong measurements.

REMEDY: The remedy for this condition is to use non-barycentered files for ALL inputs to the response calculators. This includes the spectrum, which should have been generated from non-barycentered event files.

As of HEASoft 6.30, warning / error messages are produced in most circumstances when the user attempts to use barycentered spectra.

The Correct Target Coordinates Must be Used

One of the powerful benefits of nicerarf is that it can compute the response for off-axis sources. For this capability to work properly, the correct target coordinates must be used.

If one uses incorrect target coordinates, it is possible that the response will be considered off-axis, which will bias the fitted fluxes high.

In the cases of extreme errors (erroneous positions >6 arcseconds), the NICER response tools may report zero response. This is because the erroneous position is so far outside the NICER field of view that there is no response. As of HEASoft 6.30, nicerarf may report such problems with the following warning, WARNING: Mean response is less than 10% of on-axis response. nicerarf may produce incorrect results. This may indicate that an incorrect target position was used. It may also indicate that NICER was not pointed on-target. Carefully check the target coordinates. This warning indicates that the user has likely supplied an incorrect position.

Please consider the following important notes:

  • NICER software does not check in any way that target coordinates are the true target positions. It is up to the scientist/analyst to supply correct information.
  • The NICER nominal pointing direction (keywords RA_NOM and DEC_NOM) may NOT be the true target coordinates. For various reasons the NICER pointing direction may be intentionally or unintentionally offset from the true target position.
  • Furthermore, even the recorded target coordinates (keywords RA_OBJ and DEC_OBJ) may not always be correct. If the planning team had the incorrect target coordinates (or, for example, the target position was updated after NICER observations began), then these keywords may not be correct.
  • For this reason, it is important to check and double-check the true target (and not NICER pointing) coordinates.
  • The R.A. and Dec. coordinate inputs to all NICER tools are in decimal J2000 degrees. Hour angle and sexigesimal (hour-minute-second or degree-arcminute-arcsecond) position notations are not supported.

REMEDY: enter correct target coordinates in decimal J2000 degrees to all NICER tools.

The NICER Spectrum Must Have Non-Zero Exposure

This may seem obvious, but when requesting responses for a spectrum the spectrum must have non-zero exposure.

During automated processing, the screening criteria may produce no good time. It is perfectly legal to extract a spectrum with no good time. The result will be a spectrum with zero counts and zero exposure. When nicerarf attempts to estimate responses for the spectrum, it will not find any matching timestamps (since there is no good time).

To check this, one can use the following command:
ftlist spectrum.pha+1 K include=EXPOSURE where spectrum.pha is the name of the spectrum of interest. If EXPOSURE=0, this indicates no exposure was found. (Another symptom of this condition will be the keyword TSTART=0.) The user may need to examine the screening criteria more closely (and potentially loosen them) to obtain more exposure.

REMEDY: there is no remedy for this situation without changing screening criteria. Users should not expect valid responses for a spectrum with good exposure time. However, users can check whether changing the screening criteria can select more data.

The NICER Spectrum Must Have Some Detectors Selected

This may also seem obvious, when requesting responses for a spectrum you must have at least some detectors enabled and selected. If you have deselected all detectors using nifpmsel (see Screening Data with FPM Selections thread) then there will be no good exposure for any detector, and you will get an error when trying to generate an ARF or RMF.

To check the per-detector exposure, you can use the NICER niexposum task. It will print the exposure of each detector during a time interval of interest, such as the good time intervals of a spectrum. Use the following command: ftcopy cleaned.evt'[FPM_SEL]' cleaned_fpmsel.fits copyall=NO niexposum cleaned_fpmsel.fits - gtifile=spectrum.pha selcol=FPM_SEL where cleaned.evt is your cleaned event file and spectrum.pha is your spectrum. The output of the task will be a list of (detector,exposure) pairs like this, 00 379.00000 01 379.00000 ... 67 379.00000 where (00,01,...,67) are detector IDs, and in this example 379 is the exposure in seconds of each detector. The exposure must be non-zero for at least some detectors in order for response generation to work.

Always be sure you have at least some detectors selected before trying to extract a spectrum or responses.

Users Must Provide Files from the Same Observation

In most cases users may be analyzing data from many observational datasets. Users should take care to provide as inputs to the response calculators files from the same observation. As noted above, the response tools require all of their inputs to match in time, and not doing so will result in incorrect results.

For example, if a spectrum was extracted from from one observation but the user supplies a filter file from another observation, an ARF with all zeroes may be generated.

This problem may creep in more subtly if the user has "merged" data sets. For example if they merged the event list from observations 1, 2, and 3, then the other inputs must also be merged from the same data sets. Filter files can be merged using the nimkfmerge tool, which is more flexible than ftmerge.

REMEDY: always supply inputs to the response tools that match in time coverage.

HEASoft 6.29c (or Higher) Must Be Used

Analysts should use the most recent software and calibration that is available when embarking upon an analysis project. This is expecially true for response calculation.

HEASoft versions 6.29, 6.29a and 6.29b contained some bugs related to response calculation. Users should use HEASoft 6.29c or later when generating responses. For more information, please see the NICER TIMEZERO Bug analysis thread.

REMEDY: use the most recent version of HEASoft (6.29c or later recommended).

Related Topics


  • 2022-04-25 - initial draft