NAME

baryconv - perform BARYcentric time CONVersion of photon arrival times

SYNOPSIS

baryconv [infiles=] <file_names> [parameter=value ...]

DESCRIPTION

The baryconv task converts photon arrival times from the local satellite frame to Barycentric Dynamical Time (TDB) whose spatial origin lies at the solar system barycenter. In more detail, the program expects a list of names of linearized SAX/LECS event list files (type _lev) on the command line, and, for each valid file in this list, the following actions are carried out:


1. Check whether the barycentric conversion has been performed already (based on value of header keyword TIMEREF) and, if found true, exit
2. Move to event list extension and correct all event time tags stored in the TIME Bintable column
3. If a GTI extension exists, convert all interval start and stop times to TDB as well
4. Update the values of the keywords TIMEREF, TSTART, TSTOP, and TELAPSE in all FITS headers

In accordance with NASA/OGIP recommendations, the value of the TIMEREF keyword is either LOCAL or SOLARSYSTEM depending on whether the times are expressed in local satellite time or TDB. Note that the conversion to TDB does not affect the actual time system in use, i.e., all times keep being referred to the fixed mission reference time 01/01/1994 00:00:00 UTC.

The conversion of an event's arrival time to TDB requires the knowledge of the satellite's position at that time. Therefore, the program attempts to open the HK file of type _hkg corresponding to the event list file currently being processed and to get the satellite position data from the ephemeris extension. Per default, the name of the HK file is derived from the event list file name by simply substituting _lev with _hkg. However, there is also the possibility to specify an alternative HK file name via a command line parameter hkfile.

In addition to the satellite position data, the time conversion algorithm in use by baryconv requires the barycentric vectors for the time period in question to be known a priori. This information is comprised in an ASCII file named earth.dat which is part of the standard FTOOLS reference data set (see command line parameter earthfile).

PARAMETERS

The following command line parameters are recognized by the program:

infiles = "" [string: list of event file names]

This is a blank or colon separated list of event files of type "_lev" to be processed. Note that if blank is used as file name separator, the entire list has to be enclosed by double-quotes in order to be recognized as a single command line argument.



indirpath = "" [string: list of directory names]

A colon separated list of directories to seek for the specified input files. For each file given in infiles this is performed by first attempting to open the file as specified in infiles. If this fails, each directory component in indirpath is inspected for the location of the desired input file.



hkfile = "=" [string: name of SAX/LECS HK file (type _hkg)]

The name of the HK file of type _hkg corresponding to the current event list file that is being processed. This HK file is supposed to contain ephemeris data for the time period covered by the event arrival times to be converted to TDB. If hkfile is given no value or is set to "=", the actual name is derived from the event list file name by simply substituting _lev with _hkg.



earthfile = "" [string: full path name to file earth.dat]

The path and name of the file earth.dat containing the barycentric vectors for various Julian days. This file is part of the standard FTOOLS reference data set. If earthfile is assigned no value, the file will be accessed by baryconv as <FTOOLS_DIR>/../refdata/earth.dat where <FTOOLS_DIR> stands for the root of the FTOOLS tree which has an installation dependant default value.



ra = 0.0 [real: 0 <= ra <= 360]

dec = 0.0 [real: -90 <= dec <= 90]

The Right Ascension and Declination in decimal degrees of the point in the celestial sky which shall be taken as origin of the photons whose arrival times are to be converted to TDB. If both ra and dec are specified as 0, the actual values are taken from the FITS header keywords RA_OBJ and DEC_OBJ respectively. These keywords contain the celestial coordinates of the object the satellite is currently pointing at.



verbosity = 2 [integer: 0|1|2|3]

Specifies the program verbosity level, i.e. the amount of screen output that will be issued during program execution. Level 0 means "mute", only fatal error messages will be printed. Verbosity level 3 results into detailed diagnostic messages. Default is level 2.



help = no [boolean: yes|no]

Display a brief on-screen description of all available command line parameters with default values and the current program version number.

EXAMPLES

1. Process the file kv618_lev.fits assuming a source position of R.A. = 23.4 deg, Dec. = 88.9 deg. The file earth.dat is contained in the current directory; the name of the HK file corresponding to the event file will be implicitly taken as kv618_hkg.fits:

       baryconv kv618_lev.fits ra=23.4 dec=88.9 earthfile=./earth.dat   
   

2. Process the two files a_lev.fits and b_lev.fits - the source positions shall be obtained from the respective FITS headers and the earth.dat file is found in a non-standard location:

       baryconv "a_lev.fits b_lev.fits" earthfile=/usr/local/data/earth.dat
   

FURTHER DOCUMENTATION

1. The SAX LECS Data Analysis System - Software User Manual,
   U. Lammers, Doc. SAX/LEDA/0010

BUGS

None known.

SEE ALSO