Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: December 2013

URL: http://cxc.harvard.edu/ciao/ahelp/tg_findzo.html
AHELP for CIAO 4.9

tg_findzo

Context: tools

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

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).

Bugs

RuntimeWarning: invalid value [New] (10 Apr 2017)

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
combine_grating_spectra, detilt, dewiggle, dmtype2split, mktgresp, symmetrize, tg_bkg, tg_choose_method, tg_create_mask, tg_resolve_events, tgdetect, tgdetect2, tgextract, tgextract2, tgidselectsrc, tgmask2reg, tgmatchsrc, tgsplit

Last modified: December 2013
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.