FXBARY (4.0) April FXBARY (4.0)
NAME
fxbary -- 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.)
USAGE
fxbary in_file out_file eph_file orbit_file ra_str dec_str timecol
start_time end_time barytime sensecase clobber mode
DESCRIPTION
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.
SEE ALSO