NAME

barycorr -- Generalized multi-mission barycenter correction tool

USAGE

bayrcorr infile=<filename> outfile=<filename> orbitfiles=<filename>

DESCRIPTION

This script calls the standalone executable "hdaxbary", which is the CIAO routine "axbary" extended to handle Swift in addition to Chandra, RXTE, and the Geocenter. This wrapper simply adds additional flexibility related to the input/output FITS files to the core barycentering algorithms.

PARAMETERS

infile [filename]
Input FITS filename. All extentions with TIMESYS and TSTART will be corrected.

outfile [filename]
Output FITS filename. If barytime=no (default), a copy of the input file with the Time column overwritten and all time-related keywords modified appropriately. If barytime=yes, a copy of the input file with no changes other than a BARYTIME column appended.

orbitfiles [filename]
File(s) containing orbit ephemeris information. If a list of orbit files is input (or specified via the @filename convention) any files outside the time range of the input file will be ignored and any gaps (beyond the specified tolerance) in orbit file coverage within the time range of the input file will result in an error.

(clockfile = CALDB) [string]
*SWIFT ONLY* For Swift files this parameter will control which clock correction file is used. It is ignored for other missions. The default is to automatically locate the clock file in the CALDB. The ascii version of the file ($LHEA_DATA/swco.dat) can also be used if the CALDB is unavailable.

(ra = -) [string]
Right Ascension. If not provided the routine will search the input file for RA, RA_OBJ, RA_PNT, or RA_NOM. Must be expressed in decimal degrees.

(dec = -) [string]
Declination. If not provided the routine will search the input file for DEC, DEC_OBJ, DEC_PNT, or DEC_NOM. Must be expressed in decimal degrees.

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

(barytime = no) [boolean]
If yes, a separate BARYTIME column will be written in the output file? Otherwise the routine will overwrite the TIME column with corrected times and all time-related keywords will be updated.

(tolerance = 3.0) [real]
Tolerance (in seconds) for orbit file 'glitches'. Ignored for Swift.

(chatter = 3) [enumerated integer]
Standard HEAdas chatter parameter (1-5) controlling the verbosity of the task.

(clobber = no) [boolean]
Standard HEAdas clobber parameter; controls whether an existing output file may be overwritten.

(history = yes) [boolean]
Standard HEAdas history parameter; controls whether the runtime parameter values should be written in block of HISTORY keywords in the output file.

EXAMPLES

The following examples illustrate running barycorr

1. run barycorr prompting for all required parameters: 

      barycorr
3. run barycorr specifying the RA/DEC (with required parameters prompted for): 

      barycorr ra=272.4338 dec=-19.7495

NOTES

barycorr is a Perl wrapper to a standalone utility program (hdaxbary) which is an extended version of the CIAO function "axbary", a multi-mission function that applies barycenter corrections to HFWG-compliant FITS files. hdaxbary currently recognizes missions "Swift", "XTE", "AXAF/Chandra", 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 "barytime = no" option (default) 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 tools that expect evenly spaced time intervals to the modified datafile.

The "barytime = yes" option will simply append a new column, "BARYTIME", to a copy of the original file. No changes will be made to the time-related keywords or GTI table(s) in this case. 

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.

SEE ALSO

FTOOLS: faxbary, CIAO: axbary

Swift Timing Guide

NOTES

Swift: The barycorr tool will attempt to apply the measured clock offset to all times based on the clock offset log, "swco.dat". If the swco.dat file does not cover the times in question then the tool will apply a correction based on the value of the UTCFINIT keyword plus an estimated clock-drift term. In this case a warning message will be generated and the TIERABSO value will be set to indicate the lower precision of this correction compared to using the measured clock offset.

LAST MODIFIED

December 2008