NAME

faxbary -- Barycenter correction routine for XTE light-curve, science array/event data files.


DESCRIPTION

faxbary is a simple Perl wrapper to a (non-FTOOLS) standalone program (axBary) which is a multi-mission function that applies barycenter corrections to HFWG-compliant FITS files. axBary currently recognizes missions "XTE", "AXAF", and "Geocenter" and applies barycenter corrections to all times, using orbit ephemeris file orbitFile, ra, dec, and refFrame "FK5" (DE200) or "ICRS" (DE405). When RA and Dec are not provided, an effort is made to retrieve the information from the FITS file.

The behavior of faxbary has been designed to match fxbary (the original RXTE barycenter correcting ftool) though some parameter names have changed slightly. As with fxbary, the value of the TIMEZERO keyword applies to the BARYTIME column; thus the barycentric correction can be derived by simply taking the difference between the TIME and BARYTIME columns. Note also that because axBary applies the fine clock corrections (derived from the file tdc.dat located in the $LHEASOFT/refdata directory) and also accounts for instrumental delay (both of these effects are ignored by fxbary) the more precise barycentric corrections computed by faxbary/axBary may differ from fxbary by as much as +/- 50 microseconds.

If the tdc.dat file is not up-to-date enough to be applied to the input data a warning message which begins as follows will result:

         ===>  Please note that phaseHist could not locate an applicable
               entry in the XTE fine clock correction file.

In such cases the fine clock correction will not be applied to the final barytimes; the instrumental delay correction (16 microsecs for the PCA) will still be included however. The RXTE-GOF maintains the most current version of the file at

        ftp://legacy.gsfc.nasa.gov/xte/calib_data/clock/tdc.dat

INPUT PARAMETERS

infile
Input file (must contain a (case-insensitive) "TIME" column )

outfile
Name of the output file (if same as infile the original file will be modified)

orbitfiles
Orbit ephemeris file(s) (or @filename). If a list of orbit files is input any files outside the time range of the input file will be ignored and any gaps in orbit file coverage within the time range of the input file will result in an error.

(ra = -360.9)
Right Ascension (epoch 2000). If not specified (ie, when set to the default value of -360.9) the RA keyword value will be read from input file. Must be expressed in decimal degrees.

(dec = -99.9)
Declination (epoch 2000). If not specified (ie, when set to the default value of -99.9) the DEC keyword value will be read from input file. Must be expressed in decimal degrees.

(refframe = FK5)
Coordinate reference frame. Allowed values are "FK5" (default; DE200) or "ICRS" (DE405)

(barytime = yes)
Create/overwrite BARYTIME column in output file? (default: yes)

(tolerance = 3)
Tolerance (in seconds) for orbit file glitches

(clobber = yes)
Overwrite existing output file? (default: yes)


EXAMPLES


NOTES

The "barytime = no" option will replace the values in the original TIME (case-insensitive) column from the input file with the barycenter-corrected times and update all time-related keywords and GTI values appropriately. Use of this option on binned (ie, XTE science array) data files is discouraged as it will preclude subsequent application of saextrct to the modified datafile.

Warning: this script allows one to specify identical input and output filenames. In this case the original file will be modified. If, and only if one has also specified the "barytime=no" option and an error occurs in the external axBary program the input file may be deleted! If this is a concern then do not use faxbary in this mode or else make sure a copy of the original data file is available.

Do not ever use DE405 on a FITS file that has: TIMESYS="TDB" but not: RADECSYS="ICRS" or PLEPHEM="JPL-DE405"

        TIMESYS="TDB" _with_    RADECSYS="ICRS" and/or PLEPHEM="JPL-DE405"
                                   should use denum=405.
        TIMESYS="TDB" _without_ RADECSYS="ICRS" or     PLEPHEM="JPL-DE405"
                                   should use denum=200.

DE405 may be used in conjunction with FK5 spacecraft orbit ephemeris. The maximum error is 2 ns for each earth radius that the spacecraft is removed from the geocenter. All positions provided by Tempo are on the DE200 reference frame, however - closer to FK5. This could introduce errors of up to 0.02 ms. A function, c200to405, is provided to convert DE200 positions to ICRS. Even so, it is recommended that DE200 is used for Tempo solutions that are based on DE200; apparently, efforts are underway to make Tempo support DE405.

A single, merged mission-long orbit file has been generated and is now available alongside the individual orbit files in the RXTE data archive. (The file is named FPorbit_NNNN_MMMM.fits, where NNNN and MMMM indicate the first and last mission day covered). This file will be updated periodically. In cases where a large number of orbit files is needed to span the data, using the merged orbit file will allow faxbary to run considerably faster than waiting for it to do the merging on-the-fly.

CATEGORY

Feb01 ftools.xte