Also see:

Tutorials

SciTools References

Popup Navbar Windows

And

Arrival Time Correction
(gtbary Tutorial)

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

Prerequisites

Sample Files. To try the examples in this section, you can download the following fake data files:

The processed file in the example is also available to download for your comparison:

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_events_v3.fits), creates the output event file fakepulsar_events_bary.fits), and outputs the following message.

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 GTI extension usually has the same TSTOP value as EVENTS extension, gtbary will not convert any START and STOP column contents in GTI extension either. In such a case, it results in an output file identical to an input file, with an output message shown below.

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 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 covers a time range wide enough to contain everything in an event file in order to avoid being trapped in this issue.

Assumption on SC_POSITION column in spacecraft data file

gtbary reads a spacecraft data file to obtain the spacecraft position at an event time and use it to compute a light travel time between the spacecraft and the center of the Earth. In the current definition of spacecraft data file, the 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 assumes it is in meters, no matter what is set as the TUNIT# for the SC_POSITION column. In other words, the current gtbary doesn't read/parse TUNIT# for the SC_POSITION column.

As a result, even if the TUNIT# is set to 'km' (for example), gtbary reads the numbers in the SC_POSITION column and uses 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 it is causing a problem. Since the spacecraft is flying around at about 7000 km from Earth center, numbers in the SC_POSITION column are likely to be a couple of millions, unless otherwise intended. Common mistakes are to have them three orders of magnitude smaller than intended, by putting numbers in kilometers.

Algorithms

Photon arrival times are usually converted in the order shown in the table below, one step at a time. Note that each conversion step 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: In principle, everything after a geocentric conversion depends on the pulsar location since the pulsar location is needed to calculate photon travel time between the spacecraft and the geocenter.

  • 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. A more precise estimate is necessary to meet the requirement on absolute time accuracy for Fermi.
  • The solar system barycenter is located near the surface of the Sun, which is 2.3 light-seconds away from the center of the Sun.
  • For microsecond 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).
Owned by: Masaharu Hirayama hirayama@jca.umbc.edu
  James Peachey James.Peachey-1@nasa.gov
Last updated by: Masaharu Hirayama 06/05/2009