.help fxbary 4.0 April 97 ftools.xte
.ih
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.)  
.ih
USAGE
fxbary in_file out_file eph_file orbit_file ra_str dec_str timecol
start_time end_time barytime sensecase clobber mode
.ih
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.  

.ih
PARAMETERS
.ls 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. 
.le
.ls 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. 
.le
.ls (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. 
.le
.ls 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. 
.le
.ls (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.
.le
.ls (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.
.le
.ls 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. 
.le
.ls (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. 
.le
.ls (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. 
.le
.ls (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!

.le
.ls (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.
.le
.ls (clobber = yes) [boolean]
Tells if existing output files are to be overwritten. 
.le
.ls (mode = ql) [string]
This option allows the PAR file to be updated with each successful
completed run so that the defaults are changed. 
.le
.ih
EXAMPLES
1.  Process an XTE light-curve file, "infile," using the defaults
to calculate the barycentric correction. 
.nf
fxbary in_file out_file orbit_file timecol
.fi
.ih    
NOTES:
This is the beta version of FXBARY, but is fully functional. 
.ih
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. 

.ih
BUGS
.ls 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
.le
.ls 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. 
.le
.ls Please report problems to xtehelp@athena.gsfc.nasa.gov.
.le
.ih
SEE ALSO
.endhelp

