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