Fermi Gamma-ray Space Telescope

Arrival Time Correction (gtbary) Tutorial

The gtbary tool performs a barycentering time correction to an event file using spacecraft orbit files.

Note: running gtbary on a photon or event file corrects the time column in the file. The effect of this is that the times no longer correspond to times in the spacecraft file. Using event or photon data that have been barycentered will lead to incorrect result if used in any of the other Fermitools threads. This tool is mainly used if the data are exported to other timing analysis tools e.g. xronos.

Prerequisites

Sample Files. To try the examples in this section, you can download the following simulated data files. The simulated data is for demonstration purposes and the simulated pulsar is slightly brighter than the Vela pulsar. For more information, see the parameters used for the simulation.

The processed file in the example:

is also available for download for your comparison.

Also see:

Tutorial Fermitools References
Pulsar Analysis Tutorial: Correct Photon Arrival Times gtbary

» Fermitools References

How to Barycenter Times In LAT Data

Upon startup, the gtbary tool prompts for the:

  • Input file whose times will be corrected
  • Orbit file to use for the correction
  • Output file (which may be the same as the input file)
  • Right Ascension (R.A.) and Declination (Dec) of the source (pulsar) location for which to correct the photons

When successful, the gtbary tool reads the event file (fakepulsar_event.fits), creates the output event file (fakepulsar_event_bary.fits), and outputs the following message.

prompt> gtbary
Event data file name[] fakepulsar_event.fits
Spacecraft data file name[] simscdata_1week.fits
Output event data file name[] fakepulsar_event_bary.fits
Right Ascension to be used for barycenter corrections (degrees)[0.] 111.11
Declination to be used for barycenter corrections (degrees)[0.] 22.22
prompt>

Required time coverage of spacecraft data file

For a given event file, gtbary tries to convert every "time" in your event file, including header keywords such as TSTART and TSTOP, and the contents of START and STOP columns in GTI extensions. As a result, for gtbary to work properly on your event file, a spacecraft file (a.k.a. FT2 file) given to gtbary must cover wider range of time than your event file.

For example, gtbary will fail to convert a TSTOP keyword value in EVENTS extension of your event file if the TSTOP value is later than the last spacecraft data available in your spacecraft file, and it will not convert any TIME column values in that extension. In addition, because the GTI extension usually has the same TSTOP value as EVENTS extension, gtbary will not convert any START and STOP column contents in the GTI extension either. In such a case, it results in an output file identical to an input file, with an output message shown below.

prompt> gtbary
Event data file name[] fakepulsar_event.fits
Spacecraft data file name[] simscdata_1week.fits
Output event data file name[] fakepulsar_event_bary.fits
Right Ascension to be used for barycenter corrections (degrees)[0.] 111.11
Declination to be used for barycenter corrections (degrees)[0.] 22.22
Caught St13runtime_error at the top level: Cannot get Fermi spacecraft position for 300000000 Fermi MET (TT): the time is not covered by spacecraft file simscdata_1week.fits[SC_DATA]
prompt>

In order to avoid this problem, it is not a good idea to have any kind of time in your event file exactly on the boundary of the time coverage of your spacecraft file. This is because you never know for sure whether the time will be interpreted as being inside of the coverage or outside, because of rounding in computation. In an event file some times are written as a binary number, such as the contents of TIME column in EVENTS extension, and those of START and STOP columns in the GTI extension, while others are written as a character string, such as TSTART and TSTOP. It is not guaranteed whether those will be converted perfectly into an internal expression in a computer, so that equality of double-precision variables holds in the code.

In summary it is recommended to make a spacecraft file that convers a time range wide enough to contain everything in an event file, in order to avoid being trapped in this issue.

Assumption on the SC_POSITION column in the spacecraft data file

gtbary reads a spacecraft data file to obtain the spacecraft position at an event time and uses it to compute a light travel time between the spacecraft and the center of the Earth. In the current definition of spacecraft data file, SC_POSITION column contains the spacecraft position (X, Y, and Z in reference to the Earth center) in units of meters. The current gtbary always assume it is in meters, no matter what is set to TUNIT# for SC_POSITION column. In other words, the current gtbary doesn't read/parse TUNIT# for SC_POSITION column.

As a result, even if TUNIT# is set to 'km' for example, gtbary reads numbers in SC_POSITION column and use them as if they were in meters.

Please make sure your spacecraft data file contains the spacecraft positions expressed in meters, if you feel that is causing a problem. Since the spacecraft is flying around at about 7000 km from the Earth center, numbers in SC_POSITION column are likely to be a couple of millions, unless otherwise intended. Common mistakes are to have them three order of magnitude smaller than intended, by putting numbers in kilo-meters.

Algorithms

Photon arrival times are usually converted in the order shown in the table below, one step at a time. Note that each step of conversion also has a common name, and that additional information about arrival time conversion is included.

Conversion Convert from Convert to Light travel time Time system conversion
Geocentric correction Mission Elapsed Time Geocentric time ±23 ms at maximum From mission-dependent time system to TT
Barycentric correction Geocentric time Barycentric time ±500 s at maximum From TT to TDB
Binary demodulation Barycentric time Binary-demodulated time Depends on binary parameters None

Note: Since the pulsar location is needed to calculate photon travel time between the spacecraft and the geocenter, in principle everything after a geocentric conversion depends on the pulsar location.

  • TT = TAI (International Atomic Time) + 32.184 s
  • TAI = UTC + 32 s at January 1.0, 2001, UTC
  • Approximately, TDB = TT + 1.658 ms × sin g + 0.014 ms × sin 2g, where g is a mean anomaly of the center of gravity of the Earth-Moon system around the Sun. More precise estimate is necessary to meet the requirement on absolute time accuracy for Fermi (formerly GLAST).
  • The solar system barycenter is located near the surface of the Sun, which is 2.3 light-second away from the center of the Sun.
  • For micro-second precision timing, relativistic effects are not negligible. Such effects include: the Shapiro delay in the solar system, aberration due to the motion of the spacecraft around the Earth and the motion of the Earth around the Sun, and relativistic delay at the source (for binary pulsars only).
  • Also see Goddard Space Flight Center's "A Time Tutorial" in "The ABC of XTE" for basic information about temporal analyses.

Last updated: 11/09/2017