Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/axbary.html
AHELP for CIAO 4.16

axbary

Context: Tools::Timing

Synopsis

Apply barycentric corrections to event times, GTIs, and header values.

Syntax

axbary  infile orbitfile outfile [ra] [dec] [refframe] [clobber]

Description

axbary is a multi-mission tool that applies barycenter corrections to HEASARC-compliant FITS files. It currently recognizes the missions CHANDRA (or AXAF), XTE, and Geocenter.

The script copies the infile to the outfile, applying barycenter corrections to all times in the process. In all tables, the values in the TIME (case-insensitive) column will be corrected, as will the START and STOP columns in the GTI blocks. Time-related header keywords are also corrected (see list below).

The correction is based on either of the JPL solar system ephemerides - DE200 and DE405. DE405 is consistent with the ICRS reference system (as are Chandra coordinates) and is more accurate. However, many pulsar timing ephemerides are based on DE200 (which uses FK5). If your results are to be compared with data derived with DE200, this must be specified in the refFrame parameter.

To apply a barycenter correction to Chandra data using the FK5 reference frame, one must first change the RADESYS header keyword from the default "ICRS" to "FK5" in every FITS HDU. Otherwise, axbary will exit with an error message. To edit the file header, use the CIAO tool dmhedit:

unix% dmhedit acis_evt2.fits filelist="" op=add key=RADESYS value=FK5 
unix% dmhedit acis_evt2.fits"[PRIMARY]" filelist="" op=add key=RADESYS value=FK5 
unix% dmhedit acis_evt2.fits"[GTI7]" filelist="" op=add key=RADESYS value=FK5 
...etc...

Instead users may simply use the parameter setting: refFrame=FK5.

axbary searches for the principal HDU in the input FITS file to determine the conversion parameters and then updates the following keywords in various HDUs:

Keyword Value
TIMESYS "TDB"
TIMEREF "SOLARSYSTEM"
RA_BARY Right Ascension used for barycentering
DEC_BARY Declination used for barycentering
RADESYS Reference frame used ("FK5" or "ICRS")
PLEPHEM JPL ephemeris used
TSTART barycenter-corrected
TSTOP barycenter-corrected
DATE-OBS barycenter-corrected
DATE-END barycenter-corrected
MJD_OBS barycenter-corrected
TIERRELA relative clock error
TIERABSO absolute clock error
TIMEZERO set to 0.0; previous value will be incorporated in times
CREATOR "axbary"
DATE creation date (UTC)
TREFDIR Reference direction found in RA_BARY,DEC_BARY
TREFPOS Times are pathlength-corrected to barycenter
TIMRDER Short-term clock stability (random error)
TIMSYER Systematic clock error
OBSORBIT Orbit ephemeris file used
XPOSUR# Exposure time for individual CCD_ID
XPOSURE Exposure time
TCNAM1 Barycentric Dynamical Time

If needed, axbary applies the best clock correction available, provided that it is defined for the mission. The decision is based on the value of TIERABSO (Currently, this is only the case for RXTE data). The code in axbary is the same as used in the Ftool faxbary.


Examples

Example 1

axbary event.fits orbit.fits corrected.fits

Applies barycenter correction to times in event.fits, using orbit.fits as orbit ephemeris file, and writing output in corrected.fits. RA_NOM and DEC_NOM will be used for the reference position.

Example 2

axbary event_1.fits orbit_file_1.fits barycentered.fits ra=278.132
dec=-10.586

Uses orbit_file_1.fits to apply barycenter correction to times in event_1.fits. Output is written to barycentered.fits. The RA and DEC for the correction are defined explicitly.

Example 3

axbary events.fits orbit_file.fits test_out.fits refframe=FK5

Applies barycenter correction to times in events.fits, using orbit_file.fits as the orbit ephemeris file, and writing output in test_out.fits. The FK5 (DE200) solar system ephemeris is used.


Parameters

name type ftype def reqd
infile file input   yes
orbitfile file input   yes
outfile file output   yes
ra float   INDEF  
dec float   INDEF  
refframe string   INDEF  
clobber boolean   no  

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input event file

The input event file should already have any desired GTI/time filtering completed. If you correct the times and then use a GTI filter from the pipeline, you will be filtering out the wrong intervals since those times are not barycentered.

If axbary has been used to correct the times in a file, running the tool again on the same dataset will not make any further changes to the file.

Parameter=orbitfile (file required filetype=input)

Input orbit ephemeris file

The Chandra orbit ephemeris file is of the form "orbitf051004864N002_eph1.fits." A complete collection of orbit ephemeris files are available at https://cxc.cfa.harvard.edu/cdaftp/arcftp/bary/ephem/ .

If you can't find a level=1 orbit ephemeris file on the server, the level=0 one may be used. The L1 files are the definitive orbit ephemeris files which become available about a week after the dates they cover. In addition to that information, the L0 files contain an extrapolation into the future and are thus always available when the data become available. The file with the the latest start time that is still earlier than the start time of the observation should be used.

Parameter=outfile (file required filetype=output)

Output file

The correction can be done in situ by setting the outfile to the same name as the infile and specifying clobber=yes.

Parameter=ra (float default=INDEF)

RA in decimal degrees to be used for barycenter corrections.

Values must be J2000 coordinates. If set to INDEF, axbary looks for the value in the header of infile; if the RA_NOM keyword is unavailable, RA_PNT is used. The user is strongly encouraged to provide this value explicitly.

Parameter=dec (float default=INDEF)

DEC in decimal degrees to be used for barycenter corrections.

Values must be J2000 coordinates. If set to INDEF, axbary looks for the value in the header of infile; if the DEC_NOM keyword is unavailable, DEC_PNT is used. The user is strongly encouraged to provide this value explicitly.

Parameter=refframe (string default=INDEF)

Reference frame to be used for barycenter corrections.

The allowed values for refframe are "FK5" (DE200) or "ICRS" (DE405). If set to INDEF, axbary uses the value of the RADESYS keyword in the header of infile. As Chandra files have RADESYS equal to "ICRS", the JPL DE405 solar system ephemeris would then be used. However, if the results are to be compared with data derived with the DE200 ephemeris, the user is advised to specify "FK5."

Parameter=clobber (boolean default=no)

If clobber=no, the tool exits instead of overwriting the existing file. Must be set to "yes" for in situ corrections.


Changes in CIAO 4.15

The header of the new file (the outfile parameter) will now contain the parameter settings for this tool. It can be retrieved with the dmhistory tool or the get_history_records method of the pycrates python library.


Bugs

axbary does not work on gzipped input event files

axbary does not work on gzipped input event files, even if your CIAO installation was configured with gzip support. The resulting error will look like:

axBary: Failed to re-open output file out_axbary.fits
axBary: Error exit (error 112); output file out_axbary.fits NOT deleted 

where out_axbary.fits is the value of the outfile parameter.

See Also

contrib
lc_clean, lc_sigma_clip, lightcurves
tools::acis
multi_chip_gti
tools::aspect
get_dither_parameters, monitor_photom
tools::timing
deflare, glvary, gti_align, pfold