NAME

     grosstimefilt -- 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.
    
    
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

    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