Definition of TIME in NICER Data Files
NICER is an observatory that provides precision timing capability to scientists. This thread provides information to scientists on how to understand time in the NICER system.
Read this thread if you want to: Understand the definition and accuracy of the NICER TIME column.
Last update: 2021-08-12
NICER provides precision timing capability to astronomers. To use NICER timestamps most precisely, one must understand their definition.
As for most X-ray observatories, NICER timestamps are stored as seconds-since-epoch, also known as Mission Elapsed Time (MET). All NICER FITS files have a column named TIME, which is Mission Elapsed time in units of seconds.
MET is a continuous running time system, in seconds, since the specified epoch. Unlike UTC or other civil time systems, there are no leap seconds in the NICER MET system. When converting from MET to UTC, leap seconds must be taken into account.
The following sections describe important facts about the NICER timing system, and the important keywords in FITS files. Throughout the document, we mention various time systems such as UTC, TT, TAI and TDB. Please see the glossary at the end of this document for more information on the definitions of these systems.
Throughout the document, we refer to various kinds of NICER data. Please take care to know which kind of data you are using, because there are important differences.
The NICER TIME ColumnAll NICER FITS files have a column titled TIME. Here are the relevant keywords describing this column.
TTYPE1 = 'TIME ' / Time of events
TFORM1 = '1D ' / data format of field
TUNIT1 = 's ' / physical unit of field
These keywords indicate that TIME is a scalar double-precision value in units of seconds. As of the time of writing in 2020, this double-precision time column can represent time with less than 40 nanosecond quantization error.
The NICER Epoch (Calibrated Data)The NICER EPOCH is
The NICER Time System (Calibrated and Unbarycentered)The NICER time system, as stored in FITS files, is TT (Terrestrial Time).
The relevant FITS keywords are:
The MJDREFI and MJDREFF keywords represent the NICER epoch, in Modified Julian Days (MJD) and the TT time system. The "I" part is the integer number of Modified Julian Days and the "F" part is the fractional part. The MJDREFF fractional part represents the offset in days between UTC and TT systems, which corresponds to the constant offset of 32.184 seconds (see glossary) as well as 35 leap seconds as of Janary 2014.
The TIMESYS='TT' indicates that NICER calibrated timestamps are expressed in the terrestrial TT time system.
The LEAPINIT keyword:
Converting to MJD or UTC (Calibrated and Unbarycentered)For calibrated but unbarycentered NICER data, the following formulae can be used to convert to other related time systems.
TIME(UTC) = TIME + TIMEZERO - LEAPINIT
Here TIME(UTC) would be a number of UTC seconds that have occurred since
the NICER epoch, including discontinuous steps due to leap seconds. LEAPINIT is the FITS keyword
MJD(UTC) = MJDREFI + (TIME + TIMEZERO - LEAPINIT)/86400.0
Here MJD(UTC) is the number of Modified Julian Days expressed in the
UTC time system. This is the most commonly desired civil time systems for
scientific publications. Please note that for UTC, use MJDREFI only
and not the fractional "F" part.
MJD(TT) = MJDREFI + MJDREFF + (TIME + TIMEZERO) / 86400.0
Here MJD(TT) is the number of Modified Julian Days expressed in
the TT time system.
Calibrated versus Uncalibrated DataThe discussion above refers to calibrated and unbarycentered timestamp data. The nicercal and nicerl2 tasks produce calibrated data sets. The outputs of these tasks are the "ufa" and "cl" event files as well as the filter file named niNNNNNNNNNN.mkf.
NICER also has uncalibrated data products. These are the unfiltered ("uf") event files, as well as orbit, attitude and housekeeping files. Uncalibrated files do not have a defined time system. Please do not make assumptions about the time system of these products. Specifically, there is a known 1 second error in raw NICER timestamps which is not necessarily corrected until after calibration has occurred.
Before calibration, the following CLOCKAPP keyword will be set to
Barycentered versus Unbarycentered DataScientists have the option of applying barycenter correction to data using the barycorr software. Correction to the solar system barycenter is required when absolute timing is required, when phased-connected pulse-timing solutions are required, or when comparing with other observatories.
NICER supports the task 'barycorr' which performs the barycenter correction operations. This is a standard task within HEASoft. The user must supply the relevant event file, orbit file and target coordinates. barycorr will then perform the correct calculations to render a corrected time, referred to the solar system barycenter.
After barycenter correction, the time system of the science file will change.
Before barycenter correction, the keywords will refer to TT in the local
satellite time system:
The task barycorr also updates the other time-related keywords and extensions in a science file, such as TSTART, TSTOP, and GTI extensions.
barycorr supports several different planetary ephemerides, which are delivered with HEASoft as standard. As of this writing, the most recent ephemeris available is JPL's DE430, which can be chosen by using barycorr's refframe=ICRS ephem=430 parameters. These settings are recommended for standard analysis.
After barycenter correction, the relative accuracy of NICER timestamps remains the same (~80 ns). The absolute accuracy will depend on other factors. For example, an error in target position (R.A. and Dec.) used for barycentering of even a few arcseconds can introduce microseconds of barycentering error in the final output. Also, there are relativistic clock corrections applied when transforming to the TDB system; these corrections have approximately ~100 ns of uncertainty. For most applications, these errors will be negligible.
For barycentered data, to compute MJD, use the following formula:
When Should Barycentered Event Files Be Used or Not Used? (Gotchas)
It is tempting to use barycentered event files for all downstream analysis, but it actually should be avoided in many cases.
For precision timing analysis (pulsation searches, FFTs, absolute timing, comparison with other observatories), it is often necessary (or best) to work with barycentered files.
For spectral analysis and response generation the analyst should generally use the un-barycentered event file. This is because these tasks (cleaning, filtering, response generation) need to consider many time-indexed quantities, which are best kept in the original un-barycentered time system. Using barycentered event files for ARF generation may lead to error messages, but even worse, may lead to silent incorrect results. Therefore, for spectral analysis, stick with un-barycentered files.
For light curves, it is the scientist's choice whether to use barycentered or unbarycentered products.
Time in Light Curves and Event Files Made by xselect or extractorThe NICER team currently recommends the use of the tool xselect to make binned light curves and spectra, but not extraction of filtered event lists. xselect uses the task extractor behind the scenes to make a binned output product. In the process, the task alters the time-related keywords and columns.
Please see below for important warnings about extractor and event files.
For binned light curves, extractor will set TIMEZERO to the time of the first bin, and the TIME column will contain an offset from TIMEZERO.
The general advice above for using NICER times still stands. If you always add the value of TIMEZERO keyword to the TIME column values, you will get correct NICER time.
Bug in Extractor Tool May Create Absolute Timing Errors
IMPORTANT WARNING ABOUT ABSOLUTE TIMING AND EXTRACTOR /
Relative timestamps in the affected event files are accurate. Extracted spectra and light curves also have accurate time calculations. For many users who just want to extract spectra, or who want to display basic light curves, an absolute timing error of 1 second may not be important.
Using the task 'barycorr' to barycenter the original event data also fixes the TIMEZERO keyword. Running extractor or xselect on barycentered event files will not experience this bug. Since many scientists who demand absolute timing will first barycenter their data, they will not encounter this extractor bug. However, it should be noted if the scientist uses extractor first to extract a filtered event list, and then runs barycorr on that extracted event list, the absolute timing error will still be present.
Currently, the NICER team does not recommend using xselect or extractor to produce filtered event lists if absolute timing better than 1 second is required. Instead, scientists are recommended to use the niextract-events tool, which has the advantage of preserving FPM Selection information.
Time in Light Curves Made by Xronos / lcurveAnother software package within HEASoft is Xronos, which is used for light curves, power spectra, and variability analysis.
The Xronos tool lcurve can generate light curve plots and output files. The output files are formatted differently than most other NICER files.
All time values within lcurve outputs are expressed in units of days rather than seconds. The time system will be Truncated Julian Days, TJD, which is computed as (JD-2440000.5).
The TIMEZERO value is split into separate integer and fraction
components, like this:
Thus, to compute MJD, use the following formula