NICER Response Bug Fixes (Weighting and TIMEZERO)

Overview

This page documents two bugs in NICER response calculators distributed in NICERDAS 8, 8a and 8b (distributed with HEASoft releases 6.29, 6.29a, and 6.29b). The two bugs are:

• For most cases, detector weighting in FPM Selection Data is ignored, leading to incorrect response calculation.
• A 1-second time offset leads to incorrect response calculations, which is magnified for "shredded GTIs" (could be 10-30% error).

These bugs are fixed in NICERDAS 8c (distributed with HEASoft 6.29c). Users will need to apply the following remedies to repair ARFs and event files.

Read this thread if you want to: Understand response calculator bugs and how to fix them.

Last update: 2021-09-03

Introduction

NICER response calculators nicerarf and nicerrmf are used to compute an accurate response. The conditions of a scientist's observation, such as pointing, optical light, and number of detectors, alters the response. Therefore the calculators are meant to take these conditions into account. For more information on the response calculators, please see the NICER Responses Analysis Thread. This page is exclusively about specific bugs and how to fix them.

Unfortunately, there are two bugs in the NICER ARF calculators which silently lead to potential errors in the calculation. The data sets used to test the operation of the response calculators during development did not reveal these bugs.

Scientists must upgrade to HEASoft 6.29c (which contains NICERDAS version 8c), to obtain correct results. In addition, existing event files will need to be "fixed" using a simple procedure described below. Please see our Setting Up a NICER Analysis Environment thread for more information about upgrading software and calibration data.

Discussion of the Response Calculator Bugs

As noted above, there are actually two separate problems with the NICER analysis software.

Bug 1. Weighting: nicerarf ignores FPM Selection Information

Bug Description. The nicerarf response calculator can erroneously ignore the FPM Selection information stored in an event file, causing incorrect weighting. This happens to most NICER event files and filter files used as the "selfile" input to nicerarf. Command-line selection of detectors using the "detlist" parameter of nicerarf does function properly.

Affected versions. nicerarf version 1.5 and earlier, which was distributed with HEASoft 6.29b / NICERDAS 8b (or earlier).

Impact. If 52 detectors are not operating, nicerarf will overestimate the response by the ratio 52/NUM_FPM_ON, leading to an under-estimate of the flux by the same ratio.

Affected results. Assume incorrect all ARFs relying upon the "selfile" parameter to determine on-off or deselected detectors. If the scientist has independent knowledge that all 52 detectors are operating in a NICER observation, the generated ARF should be OK. Analysis using the previously released precomputed ARFs and RMFs are not affected by this bug, but it is still up to the analyst to determine which detectors are on or off, as described on that page.

Remedy. The solution is to re-calculate the ARF using the recommended version of HEASoft (6.29c or later). The fixed version of nicerarf correctly uses FPM Selection information to calculate the per-detector ARF.

Bug 2. NICER TIMEZERO bug

Bug Description. Three NICER tools, nicerarf, niextract-events and nifpmsel, contain an off-by-one timestamp error caused by the "TIMEZERO" keyword. Thus, we are naming this the "NICER TIMEZERO bug." This bug causes FPM Selection information to be inserted into the wrong row in the FPM_SEL table in a cleaned event file.

Affected versions. HEASoft 6.29b / NICERDAS 8b (or earlier).

Impact. Incorrect FPM Selection information is generated for cleaned event files. Generally speaking there is always an science impact to this bug, but for typical 1 ksec snapshots of a target, the impact is about 0.1%. However, in cases of a large number of short good time intervals ("shredded GTIs"), the off-by-one error causes mis-retrieval for the beginning of each GTI. This may lead to 10-30% errors (or even more), depending on how many short GTIs are present, relative to long GTIs.

Affected results. All event files generated with the indicated versions are affected. The FPM Selection data itself is incorrect (shifted by 1 second).

Remedy. Users should upgrade to a recent version of the NICER software (HEASoft 6.29c or later). One solution is to re-run nicerl2 for all affected observations, which will correct the error. However, this may be heavy handed in many cases, and is not necessary.

For existing event files, the FPM selection information can be fixed without re-running nicerl2 or changing any data selections. The niextract-events task (distributed with NICERDAS 8c) will fix existing files. 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 new 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.

Please note that the revised version of 'nicerarf' will also refuse to operate on event files that do not have the required NICTZFIX keyword. The user will be required to fix the event file as described above before using nicerarf is possible.

Summary of User-Required Actions

To recover from these two bugs, the user should do the following.

• Upgrade to HEASoft 6.29c or later;
• Re-generate ARF files generated with nicerarf;
• Fix event files using the simple niextract-events command listed above (or run nicerl2 from scratch)

Modifications

• 2021-09-01 - initial draft
• 2021-09-03 - add comment that precomputed ARFs and RMFs are not affected by these bugs