Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/gti_align.html
AHELP for CIAO 4.15

gti_align

Context: Tools::Timing

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