NAME

USAGE

DESCRIPTION

'barycen' is a mission-independent tool to calculate barycenter corrections to X-ray timing data. The 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. The corrected columns are overwritten in the output file.

'barycen' also needs the observatory orbit ephemeris file (defined in the 'orbfile' parameter), the target position (ra, dec), 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 TBD) 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 Solar System Barycenter), and relativistic corrections such as Shapiro time delay and correction of clocks from the geocenter frame to the SSB frame.

The tool is suitable for any mission with an already corrected clock time; 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: 'TIME', uncorrected time; 'BARYTIME', barycenter-corrected time; 'VEARTH', total barycentric Earth velocity; 'VEARTHX', 'VEARTHY', and 'VEARTHZ', X, Y and Z components of the barycentric Earth velocity; 'ERADVEL', projection of Earth velocity onto unit vector toward the observed target; 'TOTCORR', total barycenter time correction; the four terms that sum to 'TOTCORR': 'TTtoTDB', the difference between Terrestrial Time (TT) and Barycentric Dynamic Time (TDB), 'S/C_SSBC', light travel time from spacecraft to solar system barycenter, 'S/C_EARTH', correction due to Earth velocity, and 'GRAV', correction due to the gravitational field of the Sun. 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 unit is km/s.

PARAMETERS

infile [filename]

Name of the input file.

outfile [string]

Name of the 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 under the infile 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 used in calculating the barycenter correction. The orbit format in the orbfile must match the value of the orbform parameter.

ra [real]

Right Ascension in decimal degrees of the nominal pointing. This must be in the range 0 <= ra <= 360 degrees.

dec [real]

Declination in decimal 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]

Format in which the orbital velocity is provided in the orbit file. Three formats are supported. 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) [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, in order, of the FITS columns containing the position values and the velocity values: e.g. 'orbcol=POSITION,VELOCITY'. If 'orbform=COMPONENTS', 'orbcol' must be a string containing six comma-separated column names, specifying in order the X, Y and Z components of the orbital position and then the VX, VY, VZ components of the orbital velocity, e.g. 'orbcol=X,Y,Z,VX,VY,VZ'. If 'orbform=KEPLERIAN', 'orbcol' must be a string containing six comma-separated column names, specifying in order the Keplerian orbital elements semi-major axis, eccentricity, inclination, longitude of the ascending node, argument of periapsis, and mean anomaly at epoch, e.g. 'orbcol=A,E,I,AN,AP,MA'.

(refframe = FILE) [string]

Coordinate reference frame. Allowed values are the string 'FILE', or the specific values 'FK5' (DE200) or 'ICRS' (DE405). If refframe='FILE' (default), then the tool reads the value of the 'RADECSYS' keyword in the input file.

(orbinterp = WEIGHTED) [string]

Method used to interpolate the position values in the orbit file. If 'orbinterp=WEIGHTED' (default), the tool calculates a weighted average of either the Keplerian elements ('orbform=KEPLERIAN') or the position values ('orbform=VECTOR' or 'orbform=COMPONENTS'). If 'orbinterp=TAYLOR', the tool uses a second-order Taylor expansion involving the position, velocity and time-derivative of the velocity to interpolate the orbital position. Note that the 'TAYLOR' interpolation method is not compatible with 'orbform=KEPLERIAN', and 'orbinterp' defaults to the 'WEIGHTED' interpolation method in such cases. If 'orbinterp=NEAREST', the tool 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]

Determines whether the code uses the values in a 'WEIGHTS' column of the orbit file when combining multiple orbit rows with the same time values. If 'useweights=yes', the tool 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 tool uses only the values in the first of the two rows with the same time.

(clobber = no) [boolean]

Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]

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]

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

(debug = no) [boolean]

Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]

Records tool parameters in HISTORY ([yes]/no).

(mode = ql) [string]

Mode to query the parameter file. Acceptable values include: 'ql' (query and learn/remember), 'hl' (hidden and learn/remember), 'q' (query but don't remember), 'h' (hidden).

EXAMPLES

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

  barycen infile=events.fits outfile=corrected_events.fits orbfile=orbitfile.fits 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=events.fits outfile=corrected_events.fits orbfile=orbitfile.fits  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=events.fits outfile=corrected_events.fits orbfile=orbitfile.fits  ra=83.63303 dec=22.01447 \
  orbinterp="TAYLOR" orbext="ORBIT" orbform="COMPONENTS" orbcol="X,Y,Z,VX,VY,VZ" clobber= yes

SEE ALSO

barycorr aebarycen

LAST MODIFIED

February 2016