NAME

USAGE

DESCRIPTION

The task xtdmodegti is a Perl script that creates a good time interval (GTI) for each supported Xtend mode. The task reads as input the exposure FFF file ('infile') and the directory ('evtdir') where all available Xtend unfiltered event files for the observation are found, and creates GTI for all modes found. These GTI are later appended to the appropriate cleaned event lists, and used downstream for exposure map generation and to properly apply any user-specified time filtering.

The Xtend exposure file includes time-tagged configuration information that is specific to each CCD and segment combination. This information is telemetered separately from the event data to greatly reduce the downlink data rate, however this means the exposure and event data must be combined on the ground to recover the proper timing information for all events. xtdmodegti first creates a list of unfiltered event lists in the directory specified by 'evtdir', using 'steminputs' to match the event list filenames. It then reads the timing parameters from the header of each event list, indexing them by the DATACLASS header keyword, which encodes all of the instrument configuration information. The task then steps row-by-row through the exposure file; each time-tag in this file contains eight rows, one for each combination of CCD_ID and SEGMENT, and xtdmodegti reads these columns along with DATACLASS and several other columns describing the instrument configuration. Rows that specify unsupported, non-science modes are ignored. For each row in a supported mode, the task uses the DATACLASS-encoded timing parameters to generate a GTI entry for that timestamp and CCD_ID+SEGMENT combination, and it appends this entry to a corresponding output GTI extension. It keeps track of the total number of frames in each DATACLASS for proper calculation of the exposure time.

There are two output files whose names are set by the parameters 'outfile' and 'mergefile'. The first output ('outfile') contains a GTI extension for each DATACLASS and CCD_ID+SEGMENT combination. Each extension contains START, STOP, and frame number (FRAMENUM) columns. The task also checks if a CCD_ID+SEGMENT combination is missing, or appears more than once. The information is output to the 'logfile' of the task. The second output ('mergefile') contains a GTI extension per DATACLASS, where GTI for different CCD_ID+SEGMENT combinations are merged into one (using the 'AND' mode of the ftmgtime task). The number of unique DATACLASS values is also output to the parameter 'numdclass'.

Only times within the range specified by the 'tstart' and 'tstop' parameters are included in the output GTI. Normally, these are the start and stop times of pointed observations that exclude the slew data. If the parameters 'tstart' or 'tstop' are outside of the range covered by the exposure file, the file TSTART or TSTOP header keywords are used instead.

PARAMETERS

infile [filename]

Input Xtend exposure file.

outfile [filename]

Output GTI file. This file has one extension per combination of DATACLASS, CCD_ID, and SEGMENT.

mergefile [filename]

Output GTI file with merged dataclasses. This file has one extension per DATACLASS.

tstart = 0.0 [double]

Start time [s] for pointed observations. If the TSTART of 'infile' is later than this value, TSTART is used instead.

tstop = 0.0 [double]

Stop time [s] for pointed observations. If the TSTOP of 'infile' is earlier than this value, TSTOP is used instead.

(numdclass = 0) [integer]

Output: Total number of dataclasses found.

evtdir [string]

Path to the directory which holds the Xtend unfiltered event files. If using data from the archive (HEASARC), this would be the observation ID (or sequence) + xtend + event_uf, for example, if 100050020 was the observation number, 'evtdir=100050020/xtend/event_uf/'.

steminputs [string]

Base (stem) for Xtend unfiltered event files (e.g., xa100050020). This string is used as the base file name for finding the Xtend unfiltered event files. For example, if 'steminputs=xa100050020', then to find the Xtend event files, xtdmodegti matches the regular expression /xa100050020\/(xtd_p[0-9][0-9a-f]{8}_uf\.evt)$zpatt$/ (where zpatt is a pattern that includes possible suffixes for a zipped file) against all files found in the 'evtdir' directory.

(cleanup = yes) [boolean yes|no]

Delete temporary files if 'cleanup=yes'.

(clobber = no) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 2) [integer 0|1|2|3]

Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]

Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records task parameters in HISTORY.

EXAMPLES

1. Run xtdmodegti with default parameters for XRISM OBSID 100050020.

      xtdmodegti infile=xa100050020xtd_a0exp.fits outfile=xa100050020xtd_a0exp_out.fits mergefile=xa100050020xtd_seg.gti \
         tstart=47390384. tstop=47430516. evtdir="100050020/xtend/event_uf/" steminputs="xa100050020"
   

SEE ALSO

xtdphas, xtdflagpix, xtdpi, ftmgtime

LAST MODIFIED

November 1, 2023