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. An updated clock correction file is produced every two weeks on Fridays as the mission continues 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.


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.

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 for clock v.106 and earlier.

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
2017-10-26 to
2020-10-30		2017:299 to 2017:303 80302304004GX_339m4Ground station issues
90301322001MAXI_J1621m501
90301322002
90301325001IGR_J16597m3704_SADA_17299
90301324001IGR_J16597m3704
60301031003NGC_3718
60301031004
60362029001ESO_018mG009
60362029002
60301031005NGC_3718
60301031006
90302319003Swift_J0243d6p6124
90302319004
90301326001NGC7793_P13
90301326001
2018-05-28 to
2018-06-02 		2018:148 to 2018:15360301010001 GRS_1734m292 ACS contingency
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
2019-04-15 to
2019-04-21		2019:105 to 2019:11190501314002MAXI_J1535m571Ground station issues
60160384001ESO374mG025
60160384002
60401012003SDSSJ0825p3002
60401012004
30402035003LMC_X3
30402035004
60160508001ESO381mG007
60160508002
60469004001ESO_374mG044
60469004002
60401017001APM_08279p5255
60401017002
304020260014U_1909p07
30402026002
60401017003APM_08279p5255
60401017004
2019-08-30 to
2019-09-06		2019:242 to 2019:249 80502303004EXO_1846m031ACS contingency
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-02-23 to
2020-02-25		2020:054 to 2020:056 30502017003HESS_J0632p057Ground station issues
30502017004
60561041001LEDA_478026
60561041002
600612190012MASXJ12024767m5350082
60061219002
10602001001Her_X1
10602001002
30502024009Cen_X4
30502024010

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