Jump to: Description · Examples · Parameters · Changes in CIAO 4.15 · Changes in CIAO 4.15 · Bugs · See Also

AHELP for CIAO 4.15

axbary

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.

The script now writes proper history records

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.