Synopsis
Align GTI to ACIS exposure times
Syntax
gti_align times statfile outfile [evtfile] [verbose] [clobber]
Description
ACIS events are collected in a series of (normally, full frame) 3.2 second exposures. This means that any event that is detected within this frame on the CCD has to be assigned a time, since there is no way to know when it occurred. The assigned time is set to be the mid-exposure time. Now, the different CCD_IDs are not read out simultaneously; there is a small difference between each CCD, so the same frame number from different CCDs covers a slightly different time range.
When users apply a time filter to an ACIS event file, the boundaries of the original exposures are not preserved. This leads to a small error in the total exposure, per good time interval (GTI). Most data sets have few GTI intervals so this partial-bin error is very small (fractions of a second over the entire observation). However, if there are many GTIs, as one may generate when doing phase binning or if trying to remove short-duration background flares, this error can accumulate.
This script determines the individual exposure times and aligns the user supplied GTIs to ensure that the total exposure time is correct.
The information needed to align the GTI is contained in the exposure statistics file, acis*_stat1.fits. This file is located in the secondary/ directory and is copied to the repro directory by chandra_repro.
Examples
Example 1
% gti_align times=my.gti statfile=acis_stat1.fits outfile=aligned.gti % dmcopy "acis_evt.fits[@aligned.gti]" acis_time_filter_evt.fits
The good time intervals are read from the times file and using the information in the stat1.fits file, are aligned to the ACIS exposure time frame boundaries. The dmcopy line shows how the GTI file is typically used in CIAO.
If the input file has multiple GTIs, one per CCD_ID, then each CCD's GTI will be corrected for each CCD's exposure times. Note: ACIS CCDs are read-out asynchronously, so the same exposure number on different CCD_IDs will have different TIMEs.
Example 2
% dmgti infile=acis_mtl1.fits outfile=fptemp.gti userlimit="(fp_temp<153.5)" % gti_align times=fptemp.gti statfile=acis_stat1.fits outfile=align_fptemp.gti evtfile=acis_evt1.fits
If the input file has a single GTI, one for all CCDs, then those times will be used for all the CCD_IDs found in the stat1.fits file. This example uses dmgti to create a set of GTIs based on the focal plane temperature (FP_TEMP). The output is a single GTI (with 62 intervals).
% dmlist fptemp.gti blocks
--------------------------------------------------------------------------------
Dataset: fptemp.gti
--------------------------------------------------------------------------------
Block Name Type Dimensions
--------------------------------------------------------------------------------
Block 1: PRIMARY Null
Block 2: FILTER Table 1 cols x 0 rows
Block 3: GTI Table 2 cols x 62 rows
gti_align creates separate per-chip GTIs for each CCD_ID found in the stat1 file.
% dmlist align_fptemp.gti blocks,subspace
--------------------------------------------------------------------------------
Dataset: align_fptemp.gti
--------------------------------------------------------------------------------
Block Name Type Dimensions
--------------------------------------------------------------------------------
Block 1: PRIMARY Null
Block 2: FILTER Table 2 cols x 0 rows
Block 3: GTI7 Table 2 cols x 62 rows
Block 4: GTI6 Table 2 cols x 62 rows
Block 5: GTI3 Table 2 cols x 62 rows
Block 6: GTI8 Table 2 cols x 62 rows
Block 7: GTI2 Table 2 cols x 62 rows
--------------------------------------------------------------------------------
Data subspace for block FILTER: Components: 5 Descriptors: 2
--------------------------------------------------------------------------------
--- Component 1 ---
1 TIME Real8 TABLE GTI7
480918496.4215623140:480918505.8445032835
480931804.8610073328:480933328.2480297089
480933343.9530405998:480933570.1053527594
2 CCD_ID Int2 7:7
--- Component 2 ---
1 TIME Real8 TABLE GTI6
480918496.4626023173:480918505.8855880499
480918534.1546446085:480918590.6927877069
...
The GTIs are output in the same order as they are found in the input eventfile. If no event file is supplied, then the GTIs will be created in numeric order.
Example 3
% gti_align times="303751671.36:303846063.26" statfile=acis_stat1.fits evtfile=acis_evt1.fits outfile=good.gti
Users can also specify a set of comma separated time ranges (minimum value colon maximum value, ie min:max). When a single time range is used the DM filter will be printed to the terminal when the verbose parameter is > 0.
gti_align
times = 303751671.36:303846063.26
statfile = acis_stat1.fits
outfile = good.gti
evtfile = acis_evt1.fits
clobber = no
verbose = 1
mode = ql
Filter: (ccd_id=7,time=303751668.256:303846064.981)||(ccd_id=5,time=303751668.297:303846065.023)||(ccd_id=6,time=303751668.338:303846065.064)||(ccd_id=3,time=303751668.379:303846065.105)||(ccd_id=8,time=303751668.42:303846065.146)
Parameters
| name | type | ftype | def | min | max | reqd |
|---|---|---|---|---|---|---|
| times | string | yes | ||||
| statfile | file | input | yes | |||
| outfile | file | output | yes | |||
| evtfile | file | input | no | |||
| verbose | integer | 1 | 0 | 5 | ||
| clobber | boolean | no |
Detailed Parameter Descriptions
Parameter=times (string required)
Input file with good time intervals (GTIs) or time ranges.
The GTI (aka "TIME subspace" in CXCDM terminology) is retrieved from the times file. If there are multiple GTIs, they must be for different CCD_IDs.
If there are multiple GTIs, the order of the GTIs is also stored so that the output file can be created using the same order.
The times parameter may also be a comma separate list of time ranges, for example "min1:max1,min2:max2".
Parameter=statfile (file required filetype=input)
ACIS Exposure statistics file
The ACIS exposure statistics file (stat1.fits) contains the information needed to match ACIS exposure number to TIMEs, for each CCD_ID in an observation.
Parameter=outfile (file required filetype=output)
Output file name
The output GTI whose start and stop times are aligned to match the ACIS exposure times. The output GTI file will have separate GTI's for each CCD_ID in either the times input file or in the stat1 file. This depends on whether the times input has multiple, per-chip GTIs or a single GTI block.
Parameter=evtfile (file not required filetype=input)
Event file name to determine correct GTI order
CIAO does rely on the order of the per-chip GTIs. Specifically, the 1st GTI is used to populate the ONTIME, LIVETIME, and EXPOSURE keywords, in addition to the per-chip ONTIMEn, LIVTIMn, and EXPOUSRn variants.
This script can then take in an event file (or image) and will use the order of the GTI blocks it finds to create the output file order.
Parameter=verbose (integer default=1 min=0 max=5)
Amount of tool chatter
If there is only 1 good time interval and verbose is set higher than 0, the DM filter syntax will be printed to the terminal.
Parameter=clobber (boolean default=no)
Overwrite the output file if it already exists?
About Contributed Software
This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions - such as how to ensure that the parameter file is available.
Bugs
There are no known bugs for this tool.
See Also
- contrib
- lc_clean, lc_sigma_clip, lightcurves
- tools
- acis_detect_afterglow, acis_streak_map, acisreadcorr, axbary, deflare, destreak, dmcopy, glvary, gti_align, monitor_photom, multi_chip_gti, pfold