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

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

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.

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.

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

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.

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.

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.

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

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.

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

December 2022