fxbary HEADAS help file

NAME

fxbary -- apply barycenter correction to XTE light-curve, science array or science event data files.

USAGE

        fxbary in_file out_file eph_file orbit_file ra_str dec_str timecol
          start_time end_time barytime sensecase clobber mode

DESCRIPTION

fxbary applies barycenter correction to XTE light-curve, science array or science event data files. The task reads XTE light-curve, science array, or science event data files and either adds a new column BARYTIME (as the last column) which gives the barycentric time for this data, or overwrites the TIME column (this is a very dangerous option and has ramifications in data analysis that can destroy the accuracy of science array data). All original columns are unaffected (unless the TIME column has been specified to be overwritten). (The TIMEZERO keyword will also apply to the new BARYTIME column that is added so the difference between TIME and BARYTIME is the barycentric correction value.)

The task will make the barycentric correction to the TIME column or write the results into the separate column BARYTIME.

The user can input a start_time and end_time and only the original times that fall into that time range will be in the output file and will have the barycentric correction applied. The user can also over-ride the right ascension and declination given in the file through usage of the hidden parameters ra_str and dec_str.

PARAMETERS

in_file = file name [string]

The name of the XTE light-curve FITS file that will be processed. If you add a value, e.g. file_name+2 then the second extension will be the only one to have the barycentric correction applied.

out_file = file name [string]

The name of the output FITS file to be created. This file will contain the barycenter corrected TIME or BARYTIME column based upon the selection of the "barytime" parameter. All other parameters will be unaffected.

(eph_file = ephemeris-file) [string]

The JPL 2000 ephemeris file which is distributed with the FTOOLS. Usually found in the directory /ftools/release/refdata/ and the file de200_new.fits. If this file isn't found the user will have to look through that refdata directory to see if he can find an ephemeris file. In general the file should be automatically handled during FTOOLS installation.

orbit_file = orbit-file (or @files) [string]

The orbit file (or file containing a list of files input via the use of the "at", @, sign) to use in calculating the barycentric correction. If a list of files is input the list will be sorted by time and only those with times that overlap with the input file will be processed. At the moment 1000 such orbit files can be input, but this will take a long time to process, if the user knows the approximate time of the observation only those orbit files that overlap with the observation should be input. XDF will usually do this for you, but the code can do limited file selecting of its own.

(ra_str = right-ascension) [string]

Rather than use the RA found in the file, use this value. This can be given either as degrees.decimal or as HOURS minutes sec.decimal, i.e., 1 HOUR is converted into 15 DEGREES.

(dec_str = declination) [string]

Rather than use the dec found in the file, use this value. This can be given either as degrees.decimal or as DEGREES minutes sec.decimal.

timecol = "TIME" [string]

The name of the column in the input file containing the original timing information. This value can be case sensitive by using the "sensecase" option described below. The value for time is assumed to be a double precision scalar.

(start_time = INDEF) [real]

This is the start of the time range to actually process. This acts as a crude filtering parameter on the output file. This time must be given in ABSOLUTE TIMES. Use TIMETRANS to convert relative times to absolute times.

(end_time = INDEF) [real]

This is the end of the time range to actually process. This acts as a crude filtering parameter on the output file. This time must be given in ABSOLUTE TIMES. Use TIMETRANS to convert relative times to absolute times.

(barytime = yes) [boolean]

If the option is set to "yes" it tells the code if should create/overwrite the BARYTIME column. If the column does not exist it will be created, it is does exist it will be overwritten. If the option is set to "no" it tells the code that it should overwrite the "timecol" with the barycenter corrected time. This is a very dangerous thing to do since it cannot be undone and if the input file was a science array file, data analysis of this file will be hindered since the CDLT keyword cannot be accurately applied to a TIME column that has been barycenter corrected since this transformation is not a linear one, so each row will no be separated by the amount of time given by TIMEDEL or DELTAT. In general RAW XTE data files should NEVER have the TIME column overwritten since the file cannot be accurately analyzed afterward. The extractors will issue warnings and some non-XTE specific FTOOLS may yield unexpected results. If barytime is set to "NO" then all references to the TIME column will be modified as well, so that TSTART, TSTOP, and all GTI's will be modified as well to reflect the barycenter time.

Be very careful if you tell the code to overwrite the TIME column on RAW XTE data. This causes the time-frame to change from the MET which is linear and all values such as CDLT, and TIMEDEL, etc. are related to, to the barycenter time. This will cause CDLT to be wrong, and thus SAEXTRCT will not be able to accurately process this data (nor will it be possible for ANY TOOL to accurately process your data after this one-way transformation). Also, science event data files contain time-markers as well as time-stamps so if the TIME column is overwritten the time-stamps will be changed but the time-markers will still be treated as if they applied to the ORIGINAL time-stamps. This is a VERY DANGEROUS option for the uninitiated to use, and should be utilized only with GREAT CARE. A USER WHO IS NOT AWARE OF ALL OF THESE RAMIFICATIONS SHOULD NEVER CHANGE THIS PARAMETER!

(sensecase = no) [boolean]

Tells if the code should be case sensitive in searching for the TIME column. The default is "no" so that any case will match, if any difficulties arise or the code cannot find that column then sensecase should be set to "yes" and the "timecol" specified EXACTLY as it is given in the input file.

(clobber = yes) [boolean]

Tells if existing output files are to be overwritten.

(mode = ql) [string]

This option allows the PAR file to be updated with each successful completed run so that the defaults are changed.

EXAMPLES

1. Process an XTE light-curve file, "infile," using the defaults to calculate the barycentric correction.

     fxbary in_file out_file orbit_file timecol

NOTES:

This is the beta version of FXBARY, but is fully functional.

MODIFICATIONS:

3.5:: Version 3.4 made assumptions about the form of the input orbital files which turned out to be incorrect. These were fixed in version 3.5. But if you use version 3.4 you will get incorrect barycentric correction values in your light curves.
3.5.2:: Version 3.5.2 has been exhaustively checked and a bug was found in one of the inherited subroutines. This error would show up in the third decimal place, also a change was made as to which day is used from the ephemeris file, we have moved from the previous day to the coming day for various reasons with regard to how the ephemeris file was created. Work is being done to check the results against know pulsar data. You can now overwrite the "TIME" column by setting barytime=no. Be very careful in its usages as this is a one way transformation which will modify ALL time related keywords as well as the GTI's in the file.
Version 3.6:: 1) A problem was found if the user input a series of orbit files that were not directly applicable to the data in the file being processed but fell within the TSTART+TIMEZERO and TSTOP+TIMEZERO of that file. This was most problematic when a user created a light-curve with SA(SE)EXTRCT with a large gap in it (longer than a day) but input into FXBARY an orbit file for the day that was not present in the data. The code would extrapolate. This is no longer the case, additional checking is performed to remove this from happening.

BUGS

Version FXBARY_V3.5.2: 1) This version is the first that is fully capable of over-writing the TIME column with the barycenter corrected time. This can be very dangerous and only the most experienced of users should use this option! It is quite easy through the use of this to render all of your data files to completely meaningless bits, i.e., it will look correct but in reality be garbage. Also use of this option should NEVER be used if the data is going to be processed by SAEXTRCT, unless the user
Version FXBARY_V4.0: A small change was made to fix a problem introduced in 3.6.2 - a subroutine call needed to be updated since the subroutine had changed.
Please report problems to xtehelp@athena.gsfc.nasa.gov.