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