Clock Correction page for NuSTAR SOC

What Is The Clock Correction File?

The clock correction file keeps the NuSTAR relative time (after barycentric corrections) accurate to better than 100 μs and accounts for drifts in the NuSTAR clock caused by temperature variations in the instrument. An updated clock correction file is produced every two weeks and is available from the link below as well from the NuSTAR CALDB at HEASARC.

How Is It Used?

The clockfile is used by the barycorr FTOOL to apply timing corrections to the event files and to apply barycentric corrections to the event timestamps. barycorr requires some knowledge of NuSTAR's location to correctly apply the barycentric timing correction. For NuSTAR this information is contained in the attorb file produced by the Stage 1 of nupipeline, which can be found in the output directory (commonly event_cl) with a file naming convention of nuXXXXXXXXXXXA.attorb where the X's are the sequence ID.

In addition, barycorr requires the R.A. and Dec of the target location. An example of the barycorr syntax for an observation of 3C 273 with sequenceID 10502620002 would be (for FPMA):

barycorr infile=nu10502620002A01_cl.evt outfile=bary.evt orbitfiles=nu10502620002A.attorb clockfile=nuCclock20100101v100.fits ra=187.2779 dec=2.9525

There is more extensive documentation in the barycorr fhelp file or at the HEASARC NuSTAR FAQ page

For timing analysis, we also note that the NuSTAR Clock correction file is most accurate after long-term trends have been removed. This means that the clock solution will tend to get better over time, especially for observations taken during the ~two weeks prior to the generation of the clockfile. For rapid analysis of ToO's we urge that caution should be taken when interpreting timing analysis on timescales shorter than 10's of ms.

A full archive of all of the NuSTAR clockfiles is available via NuSTAR CALDB at HEASARC. Here we maintain a list of the five most recent clock correction files.

Instrumental timing signatures

All NuSTAR observations are executed in charge pump mode (CPMODE; Miyasaka et al. 2009). NuSTAR's detectors accumulate charges continuously due to internal (leakage) currents and other sources of electronic noise as well as the charge deposited by incident X-rays. To prevent the saturation of the readout electronics, a clock-synchronized feedback circuit removes this additional charge every 1.123 ms (spacecraft time) in a "CPMODE reset". The instrument experiences 30-40 microseconds of deadtime every time this happens.

A high-frequency pulsation search of the event times in NuSTAR observations can often "detect" these resets as a strong oscillation close to 1.123 ms = 890.5 Hz and/or possible harmonics and aliases of this frequency. The actual frequency can change slightly based on instrument temperature; also, being in spacecraft time, it sometimes goes undetected after barycentering. It is easy to single out the harmonics, as they are exact multiples of the fundamental. Detecting the aliases is slightly more tricky, as they can represent non-obvious reections of any harmonics about the Nyquist frequency. They can be ruled out by changing the Nyquist frequency itself by using a light curve sampled at a different rate: if the feature does not change frequency, one can safely rule out that the feature is an alias of the 890.5 Hz frequency.

In the first observations after launch (those prior to August 2012), there was an additional source of periodic dead time from housekeeping operations being run every 1, 4, and 8 seconds. A PDS of these early observations will typically show strong features at 0.125, 0.25, and all integer frequencies up to 30 Hz.

Miyasaka, H. et al. (2009) Proc SPIE 7435, DOI 10.1117/12.825711

Clock Files:

2020 update to the clock correction file

The time reference used by NuSTAR for event time tagging is a temperature-corrected quartz oscillator on the spacecraft. This oscillator frequency is known to have a weak residual dependency on temperature, which makes the recorded NuSTAR event times "drift" during the mission with respect to UT time.

This delay is corrected using a quadratic model of temperature variations plus an aging curve. This is then compared with the clock offset history measured by the Malindi ground station, including adjustments of residual trends with phenomenological models.

The clock correction file contains a spline representation of this total delay, with about 3 control points per orbit. Users can expect a precision of better than 100 μs at any time, with some short pathological intervals where it jumps above 500 μs and other time intervals where the precision is better than 50 μs.

In addition, from 2012:355 through 2013:040 (2012-12-20 through 2013-02-09) the Malindi ground station was unavailable. During this period of time we expect the NuSTAR clock to be accurate to be slightly degraded, with an accuracy of a few ms rather than a few 100μs.

Comparison to pre-2020 clock correction files

Clock correction performance comparison
The former version of the clock file used a spline representation of the clock offsets measured by the ground station with no temperature corrections. There were two problems with this approach:
  • 1) the temperature-driven drift was evolving fast in the ~6 hour time span between ground station measurements, making the spline representation only precise to the ~3 millisecond level.
  • 2) a considerable number of clock offset measurements are slightly off due to instrumental delays, and these measurements were not easy to flag a priori.
The temperature model used in the new clock file allows the bad clock offset measurements to be marked more easily, and to follow the delays on shorter time scales, improving the timing precision.

    Recovery of pulse profile in NuSTAR observation of PSR B1821-24
    Left - Pre-2020 version left long-term secular trends in the data. Right - The new version uses additional engineering data to remove the thermal clock drift

August, 2020 absolute shift

Crab absolute timing correction
Clock files v.108 and later contain a further improvement of the clock offset model that builds on the fine clock correction introduced in v.095 and described above. However, with clock files prior to v.108, the absolute alignment to UTC time was systematically off by ~5ms*.

Additionally, the model used to produce the clock file suffered from time intervals with no temperature measurements (such as reboots of the system, shown here in the top purple box in the figure), which are captured in the pathological intervals below. Clock file v.108 includes a systematic shift of 4.9 ms (best fit value) and improves the treatment of "bad" intervals. This leads to an even more reliable barycentric correction of NuSTAR data.

For more information see:
Bachetti, M., and Markwardt, C. et al.
ApJ 2020 (submitted) arXiv:2009.10347

The figure to the right shows the pulse profile for all NuSTAR observations of the Crab pulsar between 2012 and 2020, in the 3-10 keV energy range, folded using the Jodrell Bank monthly ephemeris. These are compared to the NICER pulse profile in the same band (in black). The shift was calculated using the FFTFIT method (Taylor 1992). The panel on the left shows that pulse profile obtained using clock file v.106. The purple boxes indicate observations happening close to known issues (Malindi ground station unavailable, ACS contingency). Note that the NuSTAR profile is trailing by ~5ms the NICER profile, which can bee seen looking at the difference in the vertical dashed lines, which show the peaks of the NuSTAR and NICER pulse profiles. The panel on the right shows the pulse profile obtained using clock file v.108. This shows the improvement after a careful treatment of "bad" intervals and the introduction of a systematic shift of 4.9ms in the clock file.

*Many thanks to Lucien Kuiper for finding the issue in the first place, a and for measuring precisely this misalignment using many observations of multiple pulsars.

October, 2020 Reprocessing

During production of the NuSTAR clock file, a number of gaps were identified in the engineering files. These files were filled when possible and the relevant sequence IDs reprocessed and delivered to the MOC. Clockfiles v111 and later are based on this new set of engineering files and may give improved performance. For details of which observations were affected, please see the DLOG Update Page.

New clock correction file performance

Clock correction performance comparison
    Characterizing the temperature-driven clock drift between ground station contacts allows for a more accurate clock correction.

    This plot shows the residuals of the clock offsets with respect to the thermal model for the mission from July 2012 up to March 2020.

    The black lines indicate the local scatter, calculated over a time span of approximately 5 days.
    Residuals are typically less than 100 μs, with some pathological exceptions indicated by large spikes in the black lines.

    Scatter points are Clock offsets measured at ground station passes throughout the mission.
    Ground stations are: MLD = ASI Malindi (blue), SNG = KSAT Singapore (orange), UHI = USN Hawaii (yellow)

Interactive Clock Correction performance plots

Interactive clock correction residual plots are available on the SOC webpage:

This includes tools to zoom into and expand the clock correction thermal model and residual plots showing specific time ranges.

Dates and observations with poor clock correction residuals

The table below lists the dates and targets where the clock correction residuals are significantly larger than 500 μs or where there are non-recoverable gaps in the temperature data.

Date rangeDOY rangeSequenceIDTarget NameLikely issue
2012-08-05 to
2012:218 to 2012:21930001002002SgrAstarJust before instrument safehold test
2018-05-28 to
2018:148 to 2018:15360301010001 GRS_1734m292 Instrument Reboot
90401326001 GX304m1
2018-06-10 to
2018:161 to 2018:16580401312002 GRS_1915p105 Instrument Reboot
2019-08-30 to
2019:242 to 2019:249 80502303004EXO_1846m031Instrument Reboot
2020-05-16 to
2020:137 to 2020:138 40501004002SN1987ACOVID Groundstation Coverage

If you have any questions or comments about the NuSTAR clock correction file please use the HEASARC Help Desk, where you should select NuSTAR as the mailing list.

Pre-2020 clock correction website is available:   Old Clock Correction files

NuSTAR project website: