Last modified: 13 Jan 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/axbary/

Apply Barycenter Correction

CIAO 4.15 Science Threads


Overview

Synopsis:

The axbary tool applies a barycenter correction to the times in an observation. This is necessary in order to account for the difference in photon arrival times as the Earth and Chandra move around the Sun.

Purpose:

To barycenter-correct the photon arrival times in an event file (imaging or grating data) for use in absolute timing analysis.

Last Update: 13 Jan 2022 - Reviewed for CIAO 4.14. No changes.


Contents


Background Information

Simply put, axbary operates by copying the input event file and applying a barycenter correction to all the times. In all tables, the values in the TIME column will be corrected, as will the START and STOP columns in the GTI blocks. Time-related header keywords, such as TSTART and DATE-OBS, are also corrected. The time system (time scale) is set to TDB and the time reference position is set to the barycenter; they are changed from TT and the Chandra position.

The correction is calculated using the orbit ephemeris file (orbitfile), position (ra & dec), and a reference frame (refframe). If these parameters are not specified, default values are pulled from the event file header; see ahelp axbary for which keywords are used. The correction is based on either of the JPL solar system ephemerides -- DE200 and DE405; the default for Chandra files is the DE405 solar system ephemeris. 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 by the refframe parameter.


Get Started

Download the sample data: 133 (ACIS-I, PSR B0540-69)

unix% download_chandra_obsid 133 evt2,eph1,asol

Before running this thread on continuous-clocking mode data, check the accuracy of the source coordinates and reprocess the event file, if necessary. It is important to verify that the coordinates of the source are precise to less than 0.5 arcsec (i.e. one pixel).

Run this thread after you've finished any GTI/time filtering you wish to do. If you correct the times and then use a GTI filter from the pipeline, you would be filtering out the wrong intervals since those times are not barycentered.


Run axbary

Choosing the orbit ephemeris file

The most common error made in running this tool is inputting an incorrect file to the orbitfile parameter. Use the orbit ephemeris file(s) - there may be more than one for the observation - which is of the form orbitf051004864N002_eph1.fits. In the standard data distribution, these files are located in the primary directory.

A complete collection of orbit ephemeris files are also available at https://cxc.cfa.harvard.edu/cdaftp/arcftp/bary/ephem/.

If there is more than one orbit ephemeris for your observation, choose the file that has the highest start time less than the start time of your data for use in the orbitfile parameter. For example:

unix% ls -1 orbit*
orbitf051004864N002_eph1.fits
orbitf051580864N002_eph1.fits

unix% dmkeypar acisf00133N003_evt2.fits TSTART echo+
52019386.118647

so we would use the file orbitf051580864N002_eph1.fits. (This is the only ephemeris file in the Archive for ObsID 133.)


Set the RA and Dec coordinates

For absolute timing analysis, you will want to set the ra and dec parameters in axbary to the coordinates of the source of interest.

For continuous-clocking mode data, use the updated RA_TARG and DEC_TARG from the file header:

unix% dmlist acisf00133N003_evt2.fits header | egrep '(RA|DEC)_TARG'
048 RA_TARG                     85.04650                Real8        Observer's specified target RA
0049 DEC_TARG                   -69.33164                Real8        Observer's specified target Dec

Be sure you read the information on source coordinate accuracy in the Get Started section before proceeding.

For timed-mode data, set the RA and DEC to specify the most accurate source position possible. Note that since the RA_TARG and DEC_TARG coordinates are specified in the proposal for the observation, they will not necessarily coincide with any detectable source in the field.


Run the tool

Now run the tool:

unix% punlearn axbary
unix% pset axbary infile=acisf00133N003_evt2.fits
unix% pset axbary orbitfile=orbitf051580864N002_eph1.fits
unix% pset axbary outfile=acis_133_bary_evt2.fits 
unix% pset axbary ra=85.04650 dec=-69.33164  
unix% axbary
input event file (acisf00133N003_evt2.fits): 
input orbit ephemeris file (orbitf051580864N002_eph1.fits): 
output file (acis_133_bary_evt2.fits): 
 
axbary_ar -i orbitf051580864N002_eph1.fits -f acisf00133N003_evt2.fits -o acis_133_
t2.fits -ra 85.04649999999999 -dec -69.33163999999999 -debug
 
axBary: Principal HDU  -  TIERRELA = 0.000000, TIERABSO = 0.000050
axBary: Clock correction 0.000000 -  TIERABSO = -1.000000
axBary: Using JPL Planetary Ephemeris DE-405
axBary: bary stuff initialized in HDU 0
axBary: HDU 0 TSTART = 52019386.118931, TSTOP = 52031409.369364
axBary: HDU 0 TSTART = 52019410.802209, TSTOP = 52031434.040297 (corrected)
axBary: Using JPL Planetary Ephemeris DE-405
axBary: bary stuff initialized in HDU 1
axBary: HDU 1 TSTART = 52019386.118931, TSTOP = 52031409.369364
axBary: HDU 1 TSTART = 52019410.802209, TSTOP = 52031434.040297 (corrected)
axBary: Using JPL Planetary Ephemeris DE-405
axBary: bary stuff initialized in HDU 2
axBary: HDU 2 TSTART = 52019386.118931, TSTOP = 52031409.369364
axBary: HDU 2 TSTART = 52019410.802209, TSTOP = 52031434.040297 (corrected)
axBary: Using JPL Planetary Ephemeris DE-405
axBary: bary stuff initialized in HDU 3
axBary: HDU 3 TSTART = 52019386.118931, TSTOP = 52031409.369364
axBary: HDU 3 TSTART = 52019410.802209, TSTOP = 52031434.040297 (corrected)
axBary: Using JPL Planetary Ephemeris DE-405
axBary: bary stuff initialized in HDU 4
axBary: HDU 4 TSTART = 52019386.118931, TSTOP = 52031409.369364
axBary: HDU 4 TSTART = 52019410.802209, TSTOP = 52031434.040297 (corrected)
axBary: Using JPL Planetary Ephemeris DE-405
axBary: bary stuff initialized in HDU 5
axBary: HDU 5 TSTART = 52019386.118931, TSTOP = 52031409.369364
axBary: HDU 5 TSTART = 52019410.802209, TSTOP = 52031434.040297 (corrected)
axBary: Using JPL Planetary Ephemeris DE-405
axBary: bary stuff initialized in HDU 6
axBary: HDU 6 TSTART = 52019386.118931, TSTOP = 52031409.369364
axBary: HDU 6 TSTART = 52019410.802209, TSTOP = 52031434.040297 (corrected)
axBary: Using JPL Planetary Ephemeris DE-405
axBary: bary stuff initialized in HDU 7
axBary: HDU 7 TSTART = 52019386.118931, TSTOP = 52031409.369364
axBary: HDU 7 TSTART = 52019410.802209, TSTOP = 52031434.040297 (corrected)

The contents of the parameter file may be checked with plist axbary.


Update aspect solution file

The aspect solution file(s) must also be barycenter corrected in order to create response files (exposure maps, ARFs, and PSFs) that match the barycenter corrected event file. Failure to do so can result in the wrong aspect records being used when, for example, creating aspect histogram bins.

unix% punlearn axbary
unix% pset axbary infile=pcadf052020859N003_asol1.fits
unix% pset axbary orbitfile=orbitf051580864N002_eph1.fits
unix% pset axbary outfile=pcad_133_bary_asol1.fits 
unix% pset axbary ra=85.04650 dec=-69.33164  
unix% axbary mode=h
...
[IMPORTANT]
Important

Make sure to use the same ra and dec values and other parameters as were used to create the barycenter corrected event file.

Finally, the ASOLFILE keyword in the barycenter corrected event file is updated with the filename of the barycetner corrected aspect solution file

unix% dmhedit acis_133_bary_evt2.fits file= op=add key=ASOLFILE value="pcad_133_bary_asol1.fits" 

This will allow various scripts to locate the file automatically when extracting spectra or creating fluxed images.

[TIP]
Multiple asol files

Some observations have multiple aspect solution files (pcad*_asol1.fits). This step should be repeated separately for each file separately. The ASOLFILE keyword should then be a comma separated list of file names.


Examine the Results

dmlist can be used to compare the arrival times in the two event files:

unix% dmlist acisf00133N003_evt2.fits"[cols time]" data rows=1:5
 
--------------------------------------------------------------------------------
Data for Table Block EVENTS
--------------------------------------------------------------------------------
 
ROW    time                
 
     1  52021120.5921510682
     2  52021120.7078707442
     3  52021120.7221207470
     4  52021120.7563207448
     5  52021120.7896967009

unix% dmlist acis_133_bary_evt2.fits"[cols time]" data rows=1:5
 
--------------------------------------------------------------------------------
Data for Table Block EVENTS
--------------------------------------------------------------------------------
 
ROW    time                
 
     1  52021145.2732127234
     2  52021145.3889322504
     3  52021145.4031822383
     4  52021145.4373821914
     5  52021145.4707581103

In this case, the time transformation results in a 25 second difference between the events in the two files. Barycenter corrections can be anywhere between -500 and +500 seconds, depending on source position and time of year.


Summary

This thread is now complete; all the events in the file have been barycenter corrected. Note that although is does not hurt to run this thread more than once on the same dataset, nothing will be changed after the first run.



Parameters for /home/username/cxcds_param/axbary.par


        infile = acisf00133N003_evt2.fits input event file
     orbitfile = orbitf051580864N002_eph1.fits input orbit ephemeris file
       outfile = acis_133_bary_evt2.fits output file
           (ra = 85.04649999999999) RA to be used for barycenter corrections
          (dec = -69.33163999999999) Dec to be used for barycenter corrections
     (refframe = INDEF)           Reference frame to be used
      (clobber = no)              Clobber existing file
         (mode = ql)              
    

History

16 Dec 2004 reviewed for CIAO 3.2: no changes
08 Dec 2005 updated for CIAO 3.3: the case of two parameter names has been changed: "orbitFile" is now "orbitfile" and "refFrame" is "refframe".
01 Dec 2006 reviewed for CIAO 3.4: no changes
09 Jan 2008 updated for CIAO 4.0: axbary prompting matches order in parameter file
31 Dec 2008 reviewed for CIAO 4.1: no changes
05 Feb 2010 reviewed for CIAO 4.2: no changes
13 Jan 2011 updated for CIAO 4.3: event file version to N003
04 Mar 2011 added information on checking the accuracy of source coordinates for continuous-clocking mode data; set ra and dec parameters when running axbary
06 Jan 2012 reviewed for CIAO 4.4: no changes
03 Dec 2012 Review for CIAO 4.5; updated version info
25 Nov 2013 Review for CIAO 4.6. No changes.
16 Dec 2014 Reviewed for CIAO 4.7; no changes.
26 Jan 2015 Updated for _NOM values bug and to include processing of the aspect solution file.
23 Nov 2015 Updated for CIAO 4.8; the _NOM keywords no longer need to be restored to their original values.
29 Dec 2016 Reviewed for CIAO 4.9; updated file version info.
13 Jan 2022 Reviewed for CIAO 4.14. No changes.