NAME

grosstimefilt -- filters an RXTE input file by time


USAGE

         grosstimefilt -i "infile" -f "outfile" -r (switch to RAW time) 
                -a (switch to Absolute time) -t "Time ranges" -h (help)
                -c "yes/no"

or 

         grosstimefilt -r -a


DESCRIPTION

grosstimefilt is a script that queries the user for a series of time ranges, and filters an input file so that only data from times within those ranges will be written to the output file.

The output file will have the KEYWORDS for TSTART and TSTOP modified as well as the checksum values. It is also capable of updating keywords TSTARTI, TSTARTF, TSTOPI, and TSTOPF.

This script file allows the user to apply a gross time filter to an input file, creating an output file containing a small subset of the original data for easier subsequent manipulation. The user specifies input and output filenames, and a series of relative or absolute time ranges, and the script creates an output file containing only the data within those time ranges. Such gross time filtering might be useful when a great deal of analysis will be done on a relatively short stretch of data. Examples are the study of a 20-second burst within a 1-hr event file, or the creation of a high time resolution light curve covering a short interval.

For times relative to the start time of the input file (e.g., 0-250.0, 350.0-500.0, 750.0-1000.0), the appropriate time conversions are performed using the time keywords in the input file. Input time ranges must have a dash (-) between start and stop times, and a comma separating the ranges.

The script assumes that the input file has the data in the first extension and (optionally) a second extension for the GTI information.

Note that there are two options -r (for RAW time) and -a (for ABSOLUTE time). If neither -r or -a are specified the default is to assume that all input time-ranges are in relative time. Some examples of all three usages follow:

Assume we have a file covering 1000.00 seconds of observation time with TSTART(I/F)=78358000.00000080 and TSTOP(I/F)=78359000.000000080 and a TIMEZERO(I/F)=3.33300000 seconds. We want to select out the first 100.00 seconds of data. The three ways to do this are:

Relative Time: (the default)
Time "relative" to the file that is being processed. Specify 0.0-100.0 in this time system. Thus if the same relative time was input for 5 files, than each processed file would contain the first 100.0 seconds of the original file.

Raw Time: (the -r option)
This is the RAW time that is given by the timestamp in the Time column in the data file. Specify 

                 grosstimefilt  -r -t 78358000.00000080 - 78358100.00000080

To run the code so that it prompts for the time ranges and process that information as RAW times, call the script using 

                 grosstimefilt -r
Absolute Time: (the -a option)
This is the ABSOLUTE time that is given by the timestamp in the TIME column, plus the TIMEZERO(I/F) keyword. specified in the file. Specify 

                  grosstimefilt -a -t 78358003.33300080 - 78358103.33300080

To run the code so that it prompts for the time ranges, processing that information as ABSOLUTE times, call the script using 

                  grosstimefilt -a

PARAMETERS (SWITCHES/FLAGS)

-i {file}
provide name of the input file.

-f {file}
provide the name of an output file to contain the filtered file with data only within the specified time ranges.

-r (switch to RAW time)
this option allows the user to switch to raw time ranges, i.e., specify the times exactly as they are given in the RAW data file. (See above for more details.)

-a (switch to Absolute time)
this option allows the user to switch to absolute time ranges. Note that the user MUST take the TIMEZERO value into account since that value is added to all "timestamps" within the file, as well as the TSTART and TSTOP keywords. Failure to do so will lead to an error by the size of the TIMEZERO keyword value! (See above for more details.)

-t {Time range}
Give a (default is relative) time range in the form of "0-250.0,350.0-500.0, 750.0-1000.0" (Note that both the TIMEZERO value and the TSTART values are added to all input times to calculate the appropriate absolute time.

-c (yes/no)
determine if a user wants to save the file at the end.


EXAMPLES

         1. grosstimefilt -r -a -i "FSXX_AAAAAAAA_BBBBBBB" 
                          -f "FS_new" -t "0-250.0, 350.0-500.0, 750.0-1000.0"
                          -c yes
                 
         2. grosstimefilt -r -a

NOTES

grosstimefilt ONLY filters the data in the data extension. The TSTART(I/F) and TSTOP(I/F) values are updated, along with the CHECKSUM and DATASUM keywords, but the GTIs are left unchanged.


BUGS

Please report problems to xtehelp@athena.gsfc.nasa.gov.


SEE ALSO

SAEXTRCT, SEXTRCT, TIMETRANS, and FSELECT for more information

CATEGORY

Jan95 ftools.xte