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

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.

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:

     http://nustarsoc.caltech.edu/NuSTAR_Public/NuSTAROperationSite/clockfile_summary.html

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-08-06		2012:218 to 2012:21930001002002SgrAstarJust before instrument safehold test
30001002003
10002013002SMC_X1
10002013003
02012219001NEP_safehold_test
10060001001Deep_background_NEP
10060001002
2018-05-28 to
2018-06-02 		2018:148 to 2018:15360301010001 GRS_1734m292 Instrument Reboot
60301010002
10402008001Crab_SLPA335
10402008002
80410201001Sol_18149_AR2712_POS1
80410202001Sol_18149_AR2712_POS2
80410203001Sol_18149_AR2712_POS3
80410204001Sol_18149_AR2712_POS4
80410206001Sol_18149_AR2710_POS6
80410205001Sol_18149_AR2712_POS5
00401001001ACS_contingency_20180529
104020200013C273
10402020002
60468003001SDSS_J103315d71p5252
60468003002
90401326001 GX304m1
90401326002
2018-06-10 to
2018-06-15 		2018:161 to 2018:16580401312002 GRS_1915p105 Instrument Reboot
60401031001Ark_564
60401031002
00401005001ACS_contingency_20180610
104020200033C273
10402020004
30301001005Elias_29
30301001006
2019-08-30 to
2019-09-06		2019:242 to 2019:249 80502303004EXO_1846m031Instrument Reboot
90501336001GRO_J2058p42
90501336002
10502001012Crab
10502001013
10502010002Crab_sl_PA150
10502010003
10502001014Crab
10502001015
10502009002Crab_bkgd_PA150
10502009003
80502630001Mrk_590
80502630002
80501001001Sol_19245_SADA
00501001001ACS_contingency_19244
00501005002Cen_A_FPMB
2020-05-16 to
2020-05-17		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:   nustar.caltech.edu