Search:

[Advanced Search]



Definition of TIME in NICER Data Files

Overview

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

Introduction

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.

  • Calibrated. Calibrated event files ("ufa" and "cl") in the xti/event_cl directory have been passed through the NICER nicercal task (or equivalently nicerl2). After nicercal/nicerl2 the filter file is also considered calibrated. Time calibration may be applied at this stage. Expected timing accuracy is 80 nanoseconds. The CLOCKAPP keyword is True.
    NNNNNNNNNN/xti/event_cl/niNNNNNNNNNN_0mpuN_cl.evt
    NNNNNNNNNN/xti/event_cl/niNNNNNNNNNN_0mpuN_ufa.evt
    NNNNNNNNNN/auxil/niNNNNNNNNNN.mkf
  • Uncalibrated. Uncalibrated data are all "uf" X-ray event files, as well as housekeeping, orbit and attitude files. Expected timing accuracy is 1 second or worse. The CLOCKAPP keyword is False.
    NNNNNNNNNN/xti/event_uf/niNNNNNNNNNN_0mpuN_uf.evt
    NNNNNNNNNN/xti/hk/niNNNNNNNNNN_0mpuN.hk
    NNNNNNNNNN/auxil/niNNNNNNNNNN.att
    NNNNNNNNNN/auxil/niNNNNNNNNNN.orb
  • Barycentered. Barcyentered data have been corrected to the solar system barycenter. Expected TDB timing accuracy is limited by many factors, including knowledge of source position. The CLOCKAPP keyword is True and TIMESYS = 'TDB'.

The NICER TIME Column

All 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
  • 2014-01-01T00:00:00 (UTC)
All calibrated and unbarycentered NICER TIME columns are intended to measure the time in seconds from this civil time epoch. However, please note that there are significant caveats to this statement as described below. Uncalibrated and barycentered data must be treated differently, and the TIMEZERO keyword must be accounted for as well.

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: MJDREFI = 56658 / [d] MJD reference day (2014-01-01T00:00:00) MJDREFF = 0.000777592592592593 / [d] MJD reference (fraction of day) TIMESYS = 'TT ' / Reference time system

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: LEAPINIT= 2 / [s] Leap seconds between MJDREF and TSTART indicates the number of additional civil leap seconds that have occurred between the NICER epoch in 2014 and the start of the observation. It is useful for TT-UTC time conversions as described below. There is also a special keyword named TIMEZERO: TIMEZERO= -1.0000000000000E+00 / Time Zero This keyword indicates a time value, in seconds, to be added to each TIME value, as defined in the OGIP/93-003 standard for FITS timing keywords. In every case, TIMEZERO must be added to the TIME column to get the true time value.

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 described above. 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 Data

The 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 False: CLOCKAPP= F / UNCALIBRATED After calibration, the CLOCKAPP keyword will be set to True: CLOCKAPP= T / CALIBRATED

Barycentered versus Unbarycentered Data

Scientists 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: TIMEREF = 'LOCAL ' / Reference time location TASSIGN = 'SATELLITE' / Time assigned by clock TIMESYS = 'TT ' / Reference time system After barycenter correction, the keywords will refer to barycentric time (TDB): TIMEREF = 'SOLARSYSTEM' / Reference time location TASSIGN = 'SATELLITE' / Time assigned by clock TIMESYS = 'TDB ' / Reference 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: MJD(TDB) = MJDREFI + MJDREFF + (TIME + TIMEZERO) / 86400.0 Here MJD(TDB) is the number of Modified Julian Days expressed in the TDB time system. Note that this is the same formula as for MJD(TT) above, which works the same for barycentered data in the TDB time system.

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 extractor

The 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 / XSELECT
The NICER team has become aware of an absolute timing issue when using extractor and/or xselect to select events. extractor (version 5.37 and earlier) is meant to add the TIMEZERO keyword value to the values in the TIME column, but it does not. It also sets TIMEZERO=0 upon output. This is a bug in extractor which creates a +1 second absolute timing offset. This timing bug does not apply to light curve or spectral extractions.

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 / lcurve

Another 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: TIMEZERI= 18278 / Zero-point offset for TIME column TIMEZERF= 0.2631734259266523 / Zero-point offset for TIME column

Thus, to compute MJD, use the following formula MJD = TIMEZERI + TIMEZERF + TIME

Time System Glossary

There are several important time systems to consider for NICER analysis. These are brief definitions. For more detailed definitions and discussions, please consult the United States Naval Observatory's summary of time systems.
  • MET. Mission Elapsed Time (MET) is NICER's natural time system. It is the number of elapsed seconds since UTC 2014-01-01T00:00:00 with no leap second discontinuities.
  • UTC. Universal Coordinated Time (UTC) is a civil time system based upon atomic time. Civil timing authorities maintain synchrony with earth rotation by occassionally inserting leap seconds into UTC. This means that UTC gradually deviates from a free-running clock in one-second steps.
  • TAI. International Atomic Time (TAI) is a free-running atomic time scale that has no leap seconds. TAI is maintained by an international ensemble of terrestrial atomic clocks on the earth's surface.
  • TT. Terrestrial Time (TT), also known as Terrestrial Dynamical Time (TDT), is also an atomic timescale. TT = TAI + 32.184 seconds. TT is the formal time system of calibrated but unbarycentered NICER data.
  • TDB. Barycentric Dynamical Time (TDB), is a synthesized timescale, referring to a fictional clock at the solar system barycenter. TDB is most useful for precision pulsar timing, where time-of-flight delays and relativistic effects due to Earth motion are significant. TDB is the time system of calibrated and barycentered NICER data.
Also, there are a number of day numbering schemes which are worth mentioning. These are not time systems themselves, but a way of ordering days that are useful for astronomical purposes. You must still specify a time system (UTC, TT, TDB) in addition to using a day numbering scheme.

Modifications

  • 2020-05-06 - initial draft
  • 2021-04-16 - add navigation bar
  • 2021-08-09 - some barycentering versus non-barycentering potential gotchas
  • 2021-08-11 - add discussion of extractor bug
  • 2021-08-12 - further discussion of extractor bug in combination with barycorr