The gtbary tool performs a barycentering time correction to an event file using spacecraft orbit files.
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.
|Pulsar Analysis Tutorial: Correct Photon Arrival Times||gtbary|
Upon startup, the gtbary tool prompts for the:
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>
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.
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.
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.
Last updated: 11/09/2017