Gain Calibration / Energy Scale


Over time, the NICER team improves its detector performance model. This includes the NICER energy scale or "gain" calibration, which assigns a nominal energy to each X-ray event. This thread describes where you can find out about gain calibration in your data and how to apply a new calibration if it is released.

Read this thread if you want to: Check or recalibration gain (energy scale).

Last update: 2023-07-20


The NICER team gradually improves its detector performance model. In addition to the typical response parameters such as ARF and RMF, the gain scale is also an important aspect of NICER's performance. Although NICER's detectors were manufactured to be alike, in practice there are small differences between the energy scales of each detector. The raw measured pulse heights are not an indicator of the true nominal energy measured by the detector, because the energy scales of each are not aligned. Calibration is required to obtain energy scale alignment.

As always, we recommend users to document which version of software they are using, especially for publication. This will help future analysts repeat your results. For more information, see the Reporting NICER software and calibration versions thread.

The NICER calibration process assigns a nominal energy to each X-ray event. It transforms the detector-measured quantity, PHA (Pulse Height Analyzer), to PI (Pulse Invariant). Since there are 52 detectors it is necessary to align NICER's 52 pulse height scales to a common energy scale.

It is the job of the NICER low-level task "nicerpi" to do the gain scale calibration. However, the higher-level task "nicerl2" is the typical way to acces the calibration in a way useful to scientists. This will be described more below.

Having a correct energy to channel relationship is important. Any error in the energy scale may appear as an error in the effective area, i.e. as unwanted residuals.

Two Gain Scales

Each of NICER's detectors actually has two energy scales. There are two analog chains registered by NICER, called the slow and the fast. Each analog chain differs regarding its shaping parameters, which are optimized for spectroscopy (slow) or timing (fast).

Here is a summary of both channels from a scientist perspective.


After calibration, a NICER event file will have four pulse height measurements. The PHA and PHA_FAST columns are the raw uncalibrated pulse heights that should not be used for scientific analysis because they are not calibrated.

The PI column is what should be used for most scientific analysis, and is the default for spectral extraction. The PI column is the calibrated slow channel pulse height which corresponds as closely as possible to calibration of an ideal reference detector.

The PI_FAST column is the calibrated fast channel pulse height, which is not recommended for scientific analysis because it is degraded resolution compared to the slow channel. PI_FAST is primarily useful for diagnostic analysis of the background since the slow and fast channels respond differently to background and real X-rays.

Although the fast channel may be of interest to calibrators, all of the information below refers to the slow channel only.

What are the Units of PHA and PI?

The units of PI and PHA are "channels."

The FITS files have metadata keywords that specify that the units of PHA, PHA_FAST, PI and PI_FAST are all "chan," which is the standard unit for pulse height channel quantities. XSPEC can show the spectrum in channel space ("setplot channel") and this is the native raw calibrated spectrum as measured by NICER. Think of "channel" as a bin number.

By itself channel number may not be useful, but because of the calibration process, PI and PI_FAST have a direct connection to the nominal photon energy, as described below.

How Does PI Translate to Energy (keV)?

After running the standard calibration, NICER event files are on a common energy scale. The PI (and PI_FAST) values in the event files are comparable between detectors.

Each PI (and PI_FAST) bin is 10 eV.

For the standard calibration, the PI values are binned into linear channels which are 10 eV wide, ranging linearly from 0 to 15.01 keV. Thus, PI=100 corresponds to 1.00 to 1.01 keV, PI=101 corresponds to 1.01 to 1.02 keV, and so on. The full range of PI from 0 to 1501 corresponds to 0.0 to 15.01 keV, but in practice the usable energy range for science will be less than the full energy scale range available.

The PI value is an integer and can be thought of as referring to the bottom of the energy bin. A PI value of 105 corresponds to nominal photon energy of between 1.05 keV ( = 105 x 0.010 keV) and 1.06 keV ( = 106 x 0.010 keV).

What is Meant by Nominal Energy?

In the discussion above, we refer to "nominal" photon energy, which is not necessarily the true photon energy. The reason for this distinction is that NICER's detectors, like all X-ray detectors, are not perfect charge collectors. Due to resolution effects, escape, dead layer effects and other lost charge effects, the detectors do not record the exact photon energy, but rather a distribution of energies.

These effects are called redistribution, and are handled by the response matrix and not the energy scale. NICER-specific redistribution effects may be called the "tail," "escape," "shelf," "flourescence," and so on. Please see the NICER Response page for more discussion of the response matrices.

But if NICER's detectors do not perfectly record the true X-ray photon energy, what exactly is the nominal energy? As is true for all X-ray detectors the "energy" we are discussing here is the nominal photopeak energy corresponding to the amount of charge that was collected by the detectors. NICER never tries to reconstruct the true photon energy.

Thus, if a 6.4 keV photon is incident upon the detector, but only 50% of the charge from that photon is collected, NICER will report a PI value of 320, which has a nominal energy value of 320 x 0.010 keV = 3.2 keV. While it seems counterintuitive that a true 6.4 keV photon is recorded as 3.2 keV, that is the only sensible thing to do, since NICER will never attempt to reconstruct the true X-ray photon energy. NICER's response matrix contains the information to know how much imperfect charge collection occurs for a given photon energy in a statistical sense, and thus it is possible to reconstruct the true energy spectrum of a source using forward folding techniques in XSPEC and other fitting software packages. NICER's responses also have a channel-to-energy mapping which allows plotting software like XSPEC to display a nominal energy for each channel.

So when should you think about NICER events in channel space versus in energy space?

Generally, all spectral fitting should occur in channel space, and XSPEC does this automatically. All response information calculated by NICER's software is first and foremost in PI channel space. XSPEC's default plot is in channel space ("setplot channel").

For display and filtering purposes, it is common to think in energy space. Thus, if you plan to make a light curve in the 1-3 keV range, you would filter on pulse height in the 100-300 range. In XSPEC, you can notice and ignore pulse height bins either using the bin number or using a nominal energy value. Also, when you plot in XSPEC, if you use the command "setplot energy" the X-axis will be the nominal photon energy. Just be aware that because of the detector imperfections noted above, the "Energy" value displayed may not be the true X-ray energy for each and every NICER count.

How is Gain Calibration Released? How to Check for New Releases?

NICER calibration products are released to the public via the HEASARC's Calibration Database (CALDB) system. You can check for the newest calibration release here: You can check for the overall release date from that page, or click onward to the "Latest CALDB" page, which shows individual calibration files. The relevant files are named nixtiflightpiYYYYMMDDvNNN.fits where YYYYMMDD is the validity date (not release date), and NNN is the version number. For example, as of this writing, the most recent file is nixtiflightpi20170601v008.fits | 2022-10-01 | MPU_GAIN | NICER XTI MPU gain coefficients The version 8 file was released on October 1st, 2022. The validity date is 2017-06-01, which is the approximate start date of the NICER mission.

The NICER Pipeline Does Not Always Use the Most Recent Calibration

You may have retrieved NICER data after the calibration release date. Does that mean your data have the most recent calibration? Most often, the answer is NO. Do not assume your data have the most recent calibration, no matter when you download it.

First, you may have downloaded data processed by an older version of the standard NICER pipeline. When a new calibration is released, the pipeline team does not necessarily go back and reprocess all old data sets. Even old data sets can sometimes gain tremendously by using a newer calibration.

Second, even after a new calibration is released, the standard NICER pipeline may not use the calibration for some time. There are a number of reasons for this. For example, NICER pipeline upgrades may wait for other software upgrades. But the key result is that you should not assume the calibration is up to date for any NICER data you download.

Do My NICER Data Need Recalibration?

You can check if your NICER data needs recalibration. Each file contains a record of which calibration file was used for its gain scale. In this example, we will use observation ID 1234567890.

Run the command: fkeyprint 1234567890/xti/event_cl/ni1234567890_0mpu7_ufa.evt GCALFILE and the result should look like this. GCALFILE= 'nixtiflightpi20170601v004.fits[1]' / Gain calibration file name If the keyword does not exist, or is out of date compared to a newly released calibration file, then you should re-calibrate your data.

If you are using HEASoft 6.29 (NICERDAS 8) or later, you can also check the CALDBVER keyword. fkeyprint 1234567890/xti/event_cl/ni1234567890_0mpu7_ufa.evt CALDBVER and the result should look like this. CALDBVER= 'xti20210707' / NICER CALDB version You should be able to directly compare the CALDBVER to the released calibration version and decide if there are newer releases available.

Please see the Calibration Recommendations page for more information about the currently-recommended calibration practices, including gain. NICER's energy scale calibration history is described in more detail on the Calibration Documents page (typically a document named "NICER-Cal-Energy-Scale-*.pdf".

Note that this example uses the full-array "MPU7 ufa" file. You could use any "ufa" or "cl" file to check. The unfiltered "uf" file will not be useful for this check since the "uf" file is never calibrated.

How to Recalibrate Your Data

The NICER team recommends that users run the task "nicerl2" to apply new calibration to their data. Please see the nicerl2 analaysis thread for more information about downloading the most recent CALDB and running nicerl2 for your dataset.


  • 2020-05-06 - initial draft
  • 2020-07-27 - update to xti20200722 calibration release
  • 2021-04-16 - add dicsussion of PI-to-keV conversion
  • 2021-04-16 - add navigation bar
  • 2021-07-16 - updated for optmv12 (xti20210707) and link to Reporting NICER software and calibration versions thread
  • 2022-07-18 - much expanded discussion of what PI/PHA means, the units, and what nominal energy means
  • 2022-12-20 - update example to reflect November 2022 gain cal release
  • 2023-07-20 - additional highlights