Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/tg_findzo.html
AHELP for CIAO 4.16

tg_findzo

Context: Tools::Gratings

Synopsis

Find the zeroth order sky X,Y centroid for bright sources observed using HETG or LETG gratings with the ACIS-S detector.

Syntax

tg_findzo  infile outfile [zo_pos_x] [zo_pos_y] [clobber] [verbose]

Description

The zeroth order of a Chandra grating observation defines the origin of the dispersed spectrum's wavelength scale. Hence, accurate determination of the zeroth order centroid is a fundamental step of the pipeline processing.

The ACIS detector, however, can become saturated by bright sources. The brighter the source, the greater the distortion of the zeroth order due to rejection of core events, eventually leading to a "cratered" central region with few or no events.

To mitigate telemetry saturation for observations of extremely bright sources, ACIS itself is sometimes configured to exclude the zeroth order from telemetry.

The current CIAO program for determining the zeroth order centroid, tgdetect (based on the celldetect program), will fail to give an accurate result for such distorted or blocked zeroth orders.

In these cases, we use the CIAO tool tg_findzo to determine the intersection of a grating order with the ACIS CCD frame shift streak.

The new tool applies to Chandra Level 1 or 2 event files obtained with a grating instrument (HETG or LETG) in conjunction with the ACIS-S detector.

The algoritm works by finding the intersection of one of the grating arms with the detector readout streak. The details can be found in here


Examples

Example 1

tg_findzo acis_letg_evt1.fits outfile.fits zo_pos_x=4096.0
zo_pos_y=4095.0 clob+ verb=0

Take the user specified values (4096.0,4095.0) as the initial guess for the target position (in sky X,Y) and find the zero order centroid sky X,Y.

Example 2

tg_findzo acis_hetg_evt2.fits outfile.fits zo_pos_x=default
zo_pos_y=default clob+ verb=0

Take the header keys RA_TARG and DEC_TARG in the input file as the initial guess for the target position and find the zero order centroid sky X,Y.


Parameters

name type ftype def min max reqd
infile file input       yes
outfile file output       yes
zo_pos_x string   default      
zo_pos_y string   default      
clobber boolean   no      
verbose integer   0 0 5  

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Name of Input event file.

e.g. acisf00001_N0001_evt1.fits, or acisf00001_N0001_evt2.fits

The input file must contain an EVENTS extension which contains the sky coordinate columns X,Y and the following header keys :

Parameter=outfile (file required filetype=output)

Output file name.

The output is a table file which contains the following columns :

The header keys are same as the input except two new ones are added :

Parameter=zo_pos_x (string default=default)

The initial guess for target sky coordinate X. It can be "default" or a positive number. For 'default', the tool takes RA_TARG, DEC_TARG in the input header and convert to the sky coordinates.

Parameter=zo_pos_y (string default=default)

The initial guess for target sky coordinate Y. It can be "default" or a positive number. For 'default', the tool takes RA_TARG, DEC_TARG in the input header and convert to the sky coordinates.

Parameter=clobber (boolean default=no)

If "yes", then any existing output files will be over-written.

Parameter=verbose (integer default=0 min=0 max=5)

Program verbosity, 0 (least) to 5 (most).


Changes in CIAO 4.15

The header of the new file (the outfile parameter) will now contain the parameter settings for this tool. It can be retrieved with the dmhistory tool or the get_history_records method of the pycrates python library.


Bugs

RuntimeWarning: invalid value

Some level 1 event files may contain energy and/or sky values set to NaN. This leads to warninings from tg_findzo like the following:

    /soft/ciao-4.9/binexe/tg_findzo:692: RuntimeWarning: invalid value
    encountered in greater
       & ( p.E_v < p.energy_filter_high ))
    /soft/ciao-4.9/binexe/tg_findzo:692: RuntimeWarning: invalid value
    encountered in less
       & ( p.E_v < p.energy_filter_high ))
    /soft/ciao-4.9/binexe/tg_findzo:752: RuntimeWarning: invalid value
    encountered in greater
       & ( p.E_v < p.energy_filter_high ))
    /soft/ciao-4.9/binexe/tg_findzo:752: RuntimeWarning: invalid value
    encountered in less
       & ( p.E_v < p.energy_filter_high ))
    /soft/ciao-4.9/binexe/tg_findzo:813: RuntimeWarning: invalid value
    encountered in greater
       & ( p.E_v < p.energy_m ) ) # 8000.
    /soft/ciao-4.9/binexe/tg_findzo:813: RuntimeWarning: invalid value
    encountered in less
       & ( p.E_v < p.energy_m ) ) # 8000.
    /soft/ciao-4.9/binexe/tg_findzo:891: RuntimeWarning: invalid value
    encountered in greater
       & ( p.E_v< p.energy_m ) ) # 8000.
    /soft/ciao-4.9/binexe/tg_findzo:891: RuntimeWarning: invalid value
    encountered in less
       & ( p.E_v< p.energy_m ) ) # 8000.
    /soft/ciao-4.9/binexe/tg_findzo:926: RuntimeWarning: invalid value
    encountered in less
       wsi = np.where( np.hypot( p.X_v - p.x_zo, p.Y_v - p.y_zo ) < p.radius_zo ) 

The events with NaN values are filtered out anyway, so the above warnings are OK.

See Also

chandra
eventdef
tools::composite
combine_grating_spectra
tools::gratings
detilt, dewiggle, symmetrize, tg_bkg, tg_choose_method, tg_create_mask, tg_resolve_events, tgdetect, tgdetect2, tgextract, tgextract2, tgidselectsrc, tgmask2reg, tgmatchsrc, tgsplit
tools::response
mktgresp
tools::table
dmtype2split