NAME

USAGE

DESCRIPTION

The barycen task is a mission-independent task to calculate barycenter corrections to X-ray timing data. The task can take a single input FITS events file, or it can take multiple input FITS files listed in a plain text file (using "@" preceeding the list file name for the input parameter 'infile'). If more than one input FITS file is specified, each input file requires an orbit file (the orbit files can be similarly listed in a plain text file), and there will be an output file for each input file. An input FITS file must contain a column specified by the parameter 'timecol' (by default set to TIME), assumed by barycen to be the column to be corrected. Other time-related keywords in the initial FITS file header are also corrected. In all GTI extensions, any column name specified by the parameters 'startcol' (TSTART by default) and 'stopcol' (TSTOP by default), are also corrected. If the same names are specified for the input and output files, the corrected output columns are overwritten in the input file.

The barycen task also needs the observatory orbit ephemeris file (defined in the 'orbfile' parameter), the target position ('ra' and 'dec' parameters), and the reference frame ('refframe' parameter). If 'ra' and 'dec' are not provided or are out of range, the task extracts this information from the input FITS file header.

The task computes the time expressed by clocks at the Solar System Barycenter (SSB) (i.e. in Barycentric Dynamical Time, or TDB) and writes the corrected 'timecol' column in the output file specified by the parameter 'outfile'. This correction requires both geometric corrections (the projected light travel time to the SSB), and relativistic corrections, such as the Shapiro time delay and correction of clocks from the geocenter frame, to the SSB frame.

This task is unsuitable for any mission with a clock time that has already been corrected; thus it should not be used for data from Swift or NuStar.

If the parameter 'debug' is set to yes, the following quantities are printed for each row of the input table:

The four terms that sum to TOTCOTT are

The (X,Y,Z) system is a right-handed Equatorial system where X points toward the Vernal Equinox and Z toward the North Celestial Pole. Velocity is in units of km s^{-1}.

PARAMETERS

infile [filename]

Name of input file.

outfile [filename]

Name of output file. The output file can be the same as the input file as long as the parameter 'clobber' is set to yes. In addition to the corrected columns and keywords listed in the task description, the following keywords are added or modified: RA_TDB, DEC_TDB, TIMEREF, and TIMESYS.

orbfile [filename]

Name of a FITS satellite orbit file. This file provides the satellite orbital position and velocity as a function of time that are used in calculating the barycenter correction. The orbit format of 'orbfile' must match the value of the 'orbform' parameter.

ra = 0.0 [double]

Right ascension [degrees] of the nominal pointing. This must be in the range 0 <= ra <= 360 degrees.

dec = 0.0 [double]

Declination [degrees] of the nominal pointing, This must be in the range -90 <= dec <= +90 degrees.

(orbext = PAR_ORBIT) [string]

Name of the FITS orbit file extension containing satellite orbit data.

(orbform = KEPLERIAN) [string VECTOR|COMPONENTS|KEPLERIAN]

Format in which the orbital velocity is provided in the orbit file. For the VECTOR format, the position and velocity in the Earth-Centered Inertial (ECI) system are provided as two vector columns with three elements each. For the COMPONENT format, the position and velocity in the ECI system are provided in three separate position columns and three separate velocity columns. For the KEPLERIAN format, six separate columns contain the six Keplerian elements for the orbit solution.

(orbcol = "A,E,I,AN,AP,MA"|"X,Y,Z,VX,VY,VZ") [string]

Names of the FITS columns containing orbit values in the 'orbext' extension of the orbit file. If 'orbform=VECTOR', 'orbcol' is a string containing the names of the FITS columns containing the position and velocity vectors, respectively (e.g., 'orbcol=POSITION,VELOCITY'). If 'orbform=COMPONENTS', 'orbcol' is a string containing six comma-separated column names, specifying the x, y, and z components of the orbital position and the vx, vy, vz components of the orbital velocity, respectively (e.g., 'orbcol=X,Y,Z,VX,VY,VZ'). If 'orbform=KEPLERIAN', 'orbcol' is a string containing six comma-separated column names, specifying the Keplerian orbital elements semi-major axis, eccentricity, inclination, longitude of the ascending node, argument of periapsis, and mean anomaly, respectively (e.g., 'orbcol=A,E,I,AN,AP,MA').

(refframe) [string FILE|FK5|ICRS]

Coordinate reference frame. If 'refframe=FILE', the task uses the value of the RADECSYS keyword in the input file.

(orbinterp = WEIGHTED) [string NEAREST|WEIGHTED|TAYLOR]

Method used to interpolate the position values in the orbit file. If 'orbinterp=WEIGHTED', the task calculates a weighted average of either the Keplerian elements (for 'orbform=KEPLERIAN') or the position values (for 'orbform=VECTOR' or 'orbform=COMPONENTS'). If 'orbinterp=TAYLOR', the task uses a second-order Taylor expansion involving the position, velocity, and time-derivative of the velocity to interpolate the orbital position. The value 'orbinterp=TAYLOR' is incompatible with 'orbform=KEPLERIAN'; if TAYLOR is specified in this case, the WEIGHTED method is used instead. If 'orbinterp=NEAREST', the task does not interpolate the orbital position, but instead uses the orbital position value closest in time to the event time being corrected.

(timecol = TIME) [string]

Name of the FITS column in the event table containing time values.

(startcol = START) [string]

Name of the FITS column in the GTI table containing start time values.

(stopcol = STOP) [string]

Name of the FITS column in the GTI table containing stop time values.

(useweights = yes) [boolean yes|no]

Determines whether the code uses the values in the WEIGHTS column of the orbit file when combining multiple orbit rows with the same time values. If 'useweights=yes', the task derives a weighted average of the orbital positions and velocities for two rows with the same time. If 'useweights=no', or if the orbit file does not have a WEIGHTS column, the task uses only the values in the first row found of the two rows that have the same time.

(clobber = no) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 1) [integer 0|1|2|3]

Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]

Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records tool parameters in HISTORY.

EXAMPLES

1. Run barycen using the default weighted orbit interpolation method and Keplerian orbital elements.

   barycen infile="xa100050020xtd_p0100004b0_uf.evt" outfile="xa100050020xtd_p0100004b0_uf_corrected1.evt" orbfile="xa100050020.orb" ra=185.0 dec=-42.1

2. Run barycen using the Taylor orbit interpolation method and orbital positions and velocities supplied as vector columns.

   barycen infile="xa100050020xtd_p0100004b0_uf.evt" outfile="xa100050020xtd_p0100004b0_uf_corrected2.evt" orbfile="xa100050020.orb" ra=83.63303 dec=22.01447 \
      orbinterp="TAYLOR" orbext="ORBIT" orbform="VECTOR" orbcol="POSITION,VELOCITY" clobber=yes

3. Run barycen using the Taylor orbit interpolation method and orbital positions and velocities supplied as component columns.

   barycen infile="xa100050020xtd_p0100004b0_uf.evt" outfile="xa100050020xtd_p0100004b0_uf_corrected3.evt" orbfile="xa100050020.orb"  ra=83.63303 dec=22.01447 \
      orbinterp="TAYLOR" orbext="ORBIT" orbform="COMPONENTS" orbcol="X,Y,Z,VX,VY,VZ" clobber=yes

SEE ALSO

LAST MODIFIED