Last modified: 15 Feb 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/tg_piled_zero/

Source Position for Grating Data with a Piled or Blocked Zero Order

CIAO 4.15 Science Threads


Overview

Synopsis:

The tgdetect tool is usually used to find the centroid of the zero-order image in a grating event list. If the zero-order source is piled, there is the potential for the centroid to be incorrect due to the "hole" created in the data.

When observing a bright source (e.g. Cygnus X-2, ObsID 1102), the proposer may choose to have the zero-order region blocked via on-board software to avoid telemetry problems.

tgdetect2 can now be used to automate the selection of the best detect method.

Either of these situations may result in a misplaced zero order, which affects event order sorting and will lead to incorrect wavelength scales.

Purpose:

To determine the correct source position for a grating observation with a piled or blocked zero order. New spectral data is extracted with the updated source position.

Related Links:

Last Update: 15 Feb 2022 - Review for CIAO 4.14. Updated for Repro-5 and CALDB 4.9.6


Contents


About the Chandra Grating Data Archive and Catalog

The Chandra Grating Data Archive and Catalog (TGCat) is a browsable interface to analysis-quality spectral products (binned spectra and corresponding response files). TGCat makes it easy to find observations of a particular object, type of object, or type of observation, to quickly assess the quality and potential usefulness of the spectra with pre-computed graphics or custom-generated plots of binned and combined counts or fluxe spectra. Spectra, responses, event files, and summary products may be downloaded as a package.

TGCat runs standard CIAO tools, but also includes customized extractions for non-standard cases to refine the zeroth order position or to use regions appropriate for extended sources. Non-standard extractions details are provided in "verification and validation" comments for users.

Most public grating observations are available and new ones are added soon after they are released. See the list of of observations not included for exceptions. Many of the observations currently in this list will be included when we add enhanced processing for more difficult cases (multiple sources, very extended sources).

Please consider using the spectrum and responses (PHA, ARF, and RMF files) from TGCat in your analysis.


Get Started

Download the sample data: 1927 (HETG/ACIS-S, Vela X-1)

unix% download_chandra_obsid 1927 evt1

This is a grating observation which suffers from pileup, as as evident in the "hole" in the source, seen in Figure 1. The same approach may be applied to an observation in which the zero order was blocked (Figure 2).

Figure 1: Piled grating observation

[Thumbnail image: ]

[Version: full-size]

[Print media version: ]

Figure 1: Piled grating observation

The source has a hole in it due to piled events being lost on-orbit.

Figure 2: Grating observation with blocked zero order

[Thumbnail image: ]

[Version: full-size]

[Print media version: ]

Figure 2: Grating observation with blocked zero order

A mask was used to exclude the 0th order events from being telemetered. This is often done to keep telemetry from saturating and loosing events along the dispersed spectra.

Examine the tgdetect results

tgdetect
unix% pset tgdetect infile=acisf01927_000N004_evt1.fits
unix% pset tgdetect outfile=tgd.fits
unix% tgdetect
Input L1 event file (acisf01927_000N004_evt1.fits): 
Input source position(s) file from previous OBI or NONE (NONE): 
Output source position(s) file name (tgd.fits): 
unix%
unix% ds9 acisf01927_000N004_evt1.fits -region tgd.fits

If we zoom in the image and reduce the region radii as in Figure 3 we can clearly see that tgdetect was not able to correctly locate the 0th order location; rather it picked up a high-point on the edge of the crater caused by the detector pileup.

Figure 3: 0th order location of piled up source using tgdetect

[Thumbnail image: ]

[Version: full-size]

[Print media version: ]

Figure 3: 0th order location of piled up source using tgdetect

The zeroth order location determined by tgdetect. The image has been zoomed in and the region radii reduced to show that the zeroth order location is offset from the center of the source which will cause wavelength shifts in the extracted spectrum.

Using this zeroth order location will cause systematic errors in the wavelengths and may lead to invalid results.


Determine the Correct Source Location

tg_findzo, is a CIAO tool that can be used to locate the zeroth order location for bright sources that are either heavily piled or have been masked out.

tg_findzo works by computing the intersection of the data dispered along one of the grating arms and the readout streak that is associated with bright sources.

unix% pset tg_findzo infile=acisf01927_000N004_evt1.fits 
unix% pset tg_findzo outfile=fzo.fits 
unix% tg_findzo
unix% 
unix% ds9 acisf01927_000N004_evt1.fits -region fzo.fits 

The results of running tg_findzo are shown in Figure 4. The new location (solid green circle) now correctly locates the 0th order location. The tgdetect (dashed yellow circle) is shown for comparison.

Figure 4: 0th order location of piled up source using tg_findzo

[Thumbnail image: ]

[Version: full-size]

[Print media version: ]

Figure 4: 0th order location of piled up source using tg_findzo

The zeroth order location determined by tg_findzo. The image has been zoomed in and the region radii reduced to show that the zeroth order. The solid green cirlce is the new tg_findzo result compared to the incorrect tgdetect location (yellow, dashed).


Run tg_create_mask with New Source List

The next step is to use the new 0th order location to create the grating masks to identify which events belong to the dispersed spectrum. We use the tg_create_mask tool to do this.

unix% pset tg_create_mask infile= acisf01927_000N004_evt1.fits
unix% pset tg_create_mask outfile=tg_mask.fits
unix% pset tg_create_mask input_pos_tab= fzo.fits
unix% tg_create_mask
Input event file or stack (acisf01927_000N004_evt1.fits): 
Output region file or stack (tg_mask.fits): 
Input table with zero order positions or stack (fzo.fits): 
Observed grating type (header_value|HETG|HEG|MEG|LETG) (HETG|HEG|MEG|LETG|header_value|HEADER_VALUE) (header_value): 

The contents of the parameter file may be checked using plist tg_create_mask.

The mask file contains a circle for the source and two rotated boxes that define the grating arms.

unix% dmlist tg_mask.fits"[cols shape,sky]" data
 --------------------------------------------------------------------------------
Data for Table Block REGION
--------------------------------------------------------------------------------
 
ERROR: regCreateCircle() requires an input radius.ERROR: regCreateBox() requires two (2) radii.ERROR: regCreateBox() requires two (2) radii.Region Block: Empty region
ROW    SHAPE              SKY(X,Y)
 
     1 circle             (     4158.3676757812,     4128.8017578125)
     2 rotbox             (     4099.9145507812,     4115.2641601562)
     3 rotbox             (     4098.4541015625,     4125.5781250)

The ERROR here can be ignored. The mask region can also be overlaid on the event file:

unix% ds9 acisf01927_000N004_evt1.fits -region tg_mask.fits

to display the regions, as shown in Figure 5.

Figure 5: Event file with region file overlaid

[Thumbnail image: The region mask outlines the photons from the source and the grating arms.]

[Version: full-size]

[Print media version: The region mask outlines the photons from the source and the grating arms.]

Figure 5: Event file with region file overlaid

The regions are loaded from the mask file, which was made by tg_create_mask.


Creating a New Spectrum

Now that an accurate mask file exists, there will not be any issue with the source location in the rest of the spectral extraction process. From this point, continue with the grating analysis from the "Run tg_resolve_events" step of the HETG/ACIS-S or LETG/ACIS-S grating spectra thread.



Parameters for /home/username/cxcds_param/tgdetect.par



##
## TGDETECT -- Create filter; run celldetect; narrow down detected
##             'zero order' source list; set source id's; match 
##             sources to previous OBI source list.
##
## Note: if either "infile" or "OBI_srclist_file" are @lists, only
## the first item on the list is read in;  this tool only works on
## one set of input files;  if more than one file is listed, 
## everything but the first are ignored.
##
        infile = acisf01927_000N003_evt1.fits Input L1 event file
OBI_srclist_file = NONE             Input source position(s) file from previous OBI or NONE
       outfile = tgd.fits         Output source position(s) file name
#
#   output file naming
#
     (temproot = )                Path and root file name to be given to temporary files
     (keeptemp = no)              Keep temporary files?
     (keepexit = no)              Keep exit status file?
#
#
#
     (zo_pos_x = default)         Center GZO filter sky X position (default=pixel(ra_nom))
     (zo_pos_y = default)         Center GZO filter sky Y position (default=pixel(dec_nom))
 (zo_sz_filt_x = default)         Size of GZO filter in X pixels (ACIS=400; HRC=1800)
 (zo_sz_filt_y = default)         Size of GZO filter in Y pixels (ACIS=400; HRC=1800)
   (snr_thresh = 40)              SNR threshold to select the detected sources
# 
#   celldetect parameters
#
       (expstk = none)            list of exposure map files
       (thresh = )celldetect.thresh -> 3) celldetect source threshold
     (ellsigma = 3.0)             Size of output source ellipses (in sigmas)
     (expratio = 0)               cutoff ratio for source cell exposure variation
    (findpeaks = yes)             find local peaks for celldetect
(celldetect_log = )celldetect.log -> no) make a celldetect log file?
     (psftable = )celldetect.psftable -> /proj/xena/ciaot_install/Linux64.121105/ciao-4.5/data/psfsize20010416.fits) table of PSF size data, for celldetect
    (fixedcell = 15)              celldetect fixed cell size to use
(fixedcell_cc_mode = 15)              celldetect fixed cell size to use for CC mode ACIS data
      (bkgfile = none)            background file, for celldetect
     (bkgvalue = )celldetect.bkgvalue -> 0) background count/pixel, for celldetect
  (bkgerrvalue = )celldetect.bkgerrvalue -> 0) background error, for celldetect
        (eband = )celldetect.eband -> 1.4967) energy band, for celldetect
      (eenergy = )celldetect.eenergy -> 0.8) encircled energy of PSF, for celldetect
      (snrfile = none)            celldetect snr output file (for convolution only)
     (convolve = )celldetect.convolve -> no) use convolutions for celldetect
      (xoffset = INDEF)           celldetect offset of x axis from optical axis
      (yoffset = INDEF)           celldetect offset of y axis from optical axis
     (cellfile = none)            output cell size image file
     (centroid = yes)             compute source centroids in celldetection?
#
#   tgidselectsrc parameters
#
(snr_ratio_limit = )tgidselectsrc.snr_ratio_limit -> 1) Value of SNR ratio to use as lower limit
     (setsrcid = )tgidselectsrc.setsrcid -> yes) Set src ids in output file?
#
#   tgmatchsrc parameters
#
(max_separation = )tgmatchsrc.max_separation -> 3) Maximum allowed separation (arcsec) for sources to match
#
#
      (clobber = no)              OK to overwrite existing output file(s)?
      (verbose = 0)               Verbosity level (0 = no display)
         (mode = ql)              




Parameters for /home/username/cxcds_param/tg_findzo.par



Parameters for /home/kjg/cxcds_param4/tg_findzo.par

        infile = acisf01927_000N003_evt1.fits Input event file
       outfile = fzo.fits         Output source table file
     (zo_pos_x = default)         Initial guess for sky-x position (default=pixel(ra_targ))
     (zo_pos_y = default)         Initial guess for sky-y position (default=pixel(dec_targ))
      (clobber = no)              OK to overwrite existing output file?
      (verbose = 0)               Verbosity level (0 = no display)
         (mode = h)               




Parameters for /home/username/cxcds_param/tg_create_mask.par


##
## TG_CREATE_MASK -- Calculates the mask regions of the grating arms
##    for AXAF flight L1 grating data files.  The output is a region
##    file(s) in sky coordinates.
##
        infile = acisf01927_000N003_evt1.fits Input event file or stack
       outfile = tg_mask.fits     Output region file or stack
 input_pos_tab = fzo.fits         Input table with zero order positions or stack
   grating_obs = header_value     Observed grating type (header_value|HETG|HEG|MEG|LETG)
     sA_zero_x = 1                Source A - x position of zero order
     sA_zero_y = 1                Source A - y position of zero order
     sB_zero_x = 1                Source B - x position of zero order
     sB_zero_y = 1                Source B - y position of zero order
     sC_zero_x = 1                Source C - x position of zero order
     sC_zero_y = 1                Source C - y position of zero order
     sD_zero_x = 1                Source D - x position of zero order
     sD_zero_y = 1                Source D - y position of zero order
     sE_zero_x = 1                Source E - x position of zero order
     sE_zero_y = 1                Source E - y position of zero order
     sF_zero_x = 1                Source F - x position of zero order
     sF_zero_y = 1                Source F - y position of zero order
     sG_zero_x = 1                Source G - x position of zero order
     sG_zero_y = 1                Source G - y position of zero order
     sH_zero_x = 1                Source H - x position of zero order
     sH_zero_y = 1                Source H - y position of zero order
     sI_zero_x = 1                Source I - x position of zero order
     sI_zero_y = 1                Source I - y position of zero order
     sJ_zero_x = 1                Source J - x position of zero order
     sJ_zero_y = 1                Source J - y position of zero order
(input_psf_tab = CALDB)           Calibration file with mirror psf vs off-axis angle
     (detector = header_value)    Detector type: ACIS | HRC-I | HRC-S | header_value
(radius_factor_zero = 50)              A scale factor which multiplies the app. calculation of the one-sigma zero order radius
(width_factor_hetg = 35)              A scale factor which multiplies the one-sigma width of the heg/meg mask in the cross-dispersion direction
(width_factor_letg = 40)              A scale factor which multiplies the one-sigma width of the letg mask in the cross-dispersion direction
(r_astig_max_hetg = 0.5600000000000001) Max grating r coord (deg, along the dispersion) for HETG astigmatism calc
(r_astig_max_letg = 1.1)             Max grating r coord (deg, along the dispersion) for LETG astigmatism calc
(r_mask_max_hetg = 0.992)           Max grating r coord (deg) for HETG mask (to support offset pointing)
(r_mask_max_letg = 2.1)             Max grating r coordinate (deg) for LETG mask (to support offset pointing)
# --------------------------------------------------------------------------
# The parameters below are to be set ONLY if the user wants to use their
# own grating mask sizes instead of having the masks automatically generated.
# Only ONE input file, with up to 10 soures, can be processed using the user 
# params.  @ lists of multiple files can only be done with automated mask
# processing, or by running each file individually with hand set mask sizes.
# To start, you MUST set the following parameters:
#
# > pset tg_create_mask use_user_pars=yes last_source_toread=[letter A -> J]
#
# The parameter last_source_toread should be set to the last source letter
# for which you will enter parameters.  If you want to input 2 sources 
# (regardless of their source id's), the last_source_toread=B. Sections
# A -> J are for (upto) 10 user specified sources.  In each sections, 
# each source must have an ID, a zero order center position specified, 
# as well as the grating mask width(s).  An example with 2 HETG sources, 
# with src_id's 6 and 3:
#
# > pset tg_create_mask use_user_pars=yes last_source_toread=B
# > pset tg_create_mask sA_id=6 sA_zero_x=4762.34 sA_zero_y=2344.29 
# > pset tg_create_mask sA_zero_rad=35 sA_width_heg=25 sA_width_meg=28
# > pset tg_create_mask sB_id=3 sB_zero_x=4063.54 sB_zero_y=6346.62 
# > pset tg_create_mask sB_zero_rad=45 sB_width_heg=50 sB_width_meg=75
#              (units are all in sky pixels)
#
# NOTE: for Continuous Clocking data (CC mode), the HETG mask does not
# require the s#_width_heg, since the meg mask will encompase the entire
# data set.  HEG event processing in CC mode is done using the next 
# tool tg_resolve_events.
# --------------------------------------------------------------------------
(use_user_pars = no)              Use the user defined mask parameters below: yes or no?
(last_source_toread = A)               Last source name to be read; character A->J.
# --------------------------------------------------------------------------
# 			Source A parameters
# --------------------------------------------------------------------------
        (sA_id = 1)               Source A - source id number
  (sA_zero_rad = )                Source A - radius of zero order mask
 (sA_width_heg = )                Source A - width of heg mask in sky pixels
 (sA_width_meg = )                Source A - width of meg mask in sky pixels
 (sA_width_leg = )                Source A - width of leg mask in sky pixels
# --------------------------------------------------------------------------
# 			Source B parameters
# --------------------------------------------------------------------------
        (sB_id = 2)               Source B - source id number
  (sB_zero_rad = )                Source B - radius of zero order mask
 (sB_width_heg = )                Source B - width of heg mask in sky pixels
 (sB_width_meg = )                Source B - width of meg mask in sky pixels
 (sB_width_leg = )                Source B - width of leg mask in sky pixels
# --------------------------------------------------------------------------
# 			Source C parameters
# --------------------------------------------------------------------------
        (sC_id = 3)               Source C - source id number
  (sC_zero_rad = )                Source C - radius of zero order mask
 (sC_width_heg = )                Source C - width of heg mask in sky pixels
 (sC_width_meg = )                Source C - width of meg mask in sky pixels
 (sC_width_leg = )                Source C - width of leg mask in sky pixels
# --------------------------------------------------------------------------
# 			Source D parameters
# --------------------------------------------------------------------------
        (sD_id = 4)               Source D - source id number
  (sD_zero_rad = )                Source D - radius of zero order mask
 (sD_width_heg = )                Source D - width of heg mask in sky pixels
 (sD_width_meg = )                Source D - width of meg mask in sky pixels
 (sD_width_leg = )                Source D - width of leg mask in sky pixels
# --------------------------------------------------------------------------
# 			Source E parameters
# --------------------------------------------------------------------------
        (sE_id = 5)               Source E - source id number
  (sE_zero_rad = )                Source E - radius of zero order mask
 (sE_width_heg = )                Source E - width of heg mask in sky pixels
 (sE_width_meg = )                Source E - width of meg mask in sky pixels
 (sE_width_leg = )                Source E - width of leg mask in sky pixels
# --------------------------------------------------------------------------
# 			Source F parameters
# --------------------------------------------------------------------------
        (sF_id = 6)               Source F - source id number
  (sF_zero_rad = )                Source F - radius of zero order mask
 (sF_width_heg = )                Source F - width of heg mask in sky pixels
 (sF_width_meg = )                Source F - width of meg mask in sky pixels
 (sF_width_leg = )                Source F - width of leg mask in sky pixels
# --------------------------------------------------------------------------
# 			Source G parameters
# --------------------------------------------------------------------------
        (sG_id = 7)               Source G - source id number
  (sG_zero_rad = )                Source G - radius of zero order mask
 (sG_width_heg = )                Source G - width of heg mask in sky pixels
 (sG_width_meg = )                Source G - width of meg mask in sky pixels
 (sG_width_leg = )                Source G - width of leg mask in sky pixels
# --------------------------------------------------------------------------
# 			Source H parameters
# --------------------------------------------------------------------------
        (sH_id = 8)               Source H - source id number
  (sH_zero_rad = )                Source H - radius of zero order mask
 (sH_width_heg = )                Source H - width of heg mask in sky pixels
 (sH_width_meg = )                Source H - width of meg mask in sky pixels
 (sH_width_leg = )                Source H - width of leg mask in sky pixels
# --------------------------------------------------------------------------
# 			Source I parameters
# --------------------------------------------------------------------------
        (sI_id = 9)               Source I - source id number
  (sI_zero_rad = )                Source I - radius of zero order mask
 (sI_width_heg = )                Source I - width of heg mask in sky pixels
 (sI_width_meg = )                Source I - width of meg mask in sky pixels
 (sI_width_leg = )                Source I - width of leg mask in sky pixels
# --------------------------------------------------------------------------
# 			Source J parameters
# --------------------------------------------------------------------------
        (sJ_id = 10)              Source J - source id number
  (sJ_zero_rad = )                Source J - radius of zero order mask
 (sJ_width_heg = )                Source J - width of heg mask in sky pixels
 (sJ_width_meg = )                Source J - width of meg mask in sky pixels
 (sJ_width_leg = )                Source J - width of leg mask in sky pixels
# --------------------------------------------------------------------------
      (geompar = geom)            Parameter file for Pixlib Geometry files
      (verbose = 0)               Verbose level: 0 - no output, 5 - max verbosity
      (clobber = no)              Clobber existing outfile?
         (mode = ql)              



History

04 Apr 2006 new for CIAO 3.3: original version
01 Dec 2006 reviewed for CIAO 3.4: no changes
11 Jan 2008 updated for CIAO 4.0: ds9 now automatically looks for the "[REGION]" extension in the region file, so it doesn't have to be specified; filenames and screen output updated for reprocessed data (version N004 files)
12 Feb 2009 updated for CIAO 4.1: images are inline; added more information about findzo.sl
13 Mar 2009 findzo.sl script actually named tg_findzo
16 Jun 2009 added About the Chandra Grating Data Archive and Catalog section
27 Jan 2010 reviewed for CIAO 4.2: no changes
21 Jun 2010 An updated version of the Chandra ABC Guide to Pileup is now linked to this thread.
12 Jan 2011 reviewed for CIAO 4.3: no changes
06 Jan 2012 reviewed for CIAO 4.4: no changes
28 Nov 2012 Re-written to take advantage of new tg_findzo tool in CIAO 4.5
11 Dec 2013 Review for CIAO 4.6. The new tgdetect2 automates the selection of tgdetect or tg_findzo.
23 Dec 2014 Review for CIAO 4.7; no changes.
15 Feb 2022 Review for CIAO 4.14. Updated for Repro-5 and CALDB 4.9.6