tg_findzo

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 :

GRATING = HETG or LETG
DETNAM = ACIS-nnnn where n can't be 0,1,2 or 3
READMODE = TIMED
ROLL_NOM
RA_TARG
DEC_TARG

Parameter=outfile (file required filetype=output)

Output file name.

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

RA [deg] - right ascension
DEC[deg] - declination
X [pixel] - 0th order sky x centroid
Y [pixel] - 0th order sky y centroid
SHAPE - shape of the region, usually CIRCLE
R[2] [pixel] - generalized radii (Here, [ zo radius, 0] )
NET_COUNTS [count] - counts in the 0th order region
NET_RATE [count/s] - count rate in the 0th order
ROTANG [deg] - rotate angle of source region ( 0 for a circle)
COMPONENT - serial index of region components (typically 1)
TG_SRCID - 0th order serial source count (typically 1)

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

COUNT_ST: the counts in the ACIS CCD frame-shift streak.
COUNT_TG: the counts in the grating arm.

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.