Clock Correction page for NuSTAR SOC    last updated 2025-03-31


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.

Please be sure to check the list of observation sequenceID's with suspect clock correction residuals.

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:

Note that clockfile v121 covers data only up to 7/28/2021

2025 update to the clock correction file


In March 2025, we re-fitted the temperature model to the clock offset history, finding that the aging curve had departed significantly from the fit performed in 2020. We re-executed the full analysis described by Bachetti et al. (2021), and updated the parameters of both the temperature model and the aging curve. The updated Table 1 from Bachetti et al. (2021) is below. We also slightly modified the algorithms used for the detrending of clock offsets after the temperature correction, using scipy’s PchipInterpolator instead of the former interp1d, which improved the behavior of the solution in time ranges with steep trends (e.g. due to missing temperature measurements).

From v.202 onwards, the released clock correction file uses this new correction. Clockfile performance continues to be nominal, with alignment to UT good to ≲100 μs. The new solution improves the correction for a number of problematic time ranges (in particular the first month of the mission), and should also improve the stability of the correction in very recent observations (i.e. within the two weeks prior to the latest clockfile generation). If you find any dubious results, please let us know via the HEASARC Help Desk.

The updated temperature model parameters:

CoefficientUnitValue
T0C13.500(15)
t0MET77509250 (fixed)
cppm13.90461(5)
a0ppm / K−0.07421(4)
a1ppm / K20.00160(2)
b0ppm0.0121(4)
b11/Year52(10)
b2ppm−0.0712(8)
b31/Year0.208(9)
eppm−0.0124(12)

For more information on the original temperature model and approach, please see the details for the 2020 update below, and the Bachetti et al. (2021) paper.

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 (2021)

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 v.111 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
2022-12-04 to
2022-12-07		2022:338 to 2022:341 60861001002WISEA_J122527p223512Uplink card reset
2022-06-05 to
2022-06-08		2022:156 to 2022:159 50760003004NGC_4490Uplink card reset
60702061003
60702061004		MRK_421
2021-07-29 to
2021-08-05		2021:210 to 2021:217 30602020003
30602020004		SgrAstarGround station clock issues
60160243001
60160243002		MCGm05m14m012
907102*Solar Observations on 2021-07-30
30701010001
30701010002		XSS_J12270m4859
90702326003
90702326004		4U_1543m475
60702044001
60702044002		NGC_1358
30702014001
30702014002		NGC_7793_P13
40702003001
40702003002		G1d9p0d3
2020-05-16 to
2020-05-17		2020:137 to 2020:138 40501004002SN1987ACOVID Groundstation Coverage
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
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
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
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

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