Source Position for Grating Data with a Piled or Blocked Zero Order
![[CXC Logo]](../../imgs/cxc-logo.gif){kind=logo}
CIAO 4.16 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:
- About the Instrument: ACIS, HETG, & LETG
-
The Chandra ABC Guide to Pileup (PDF, 26 pages)
-
Analysis Guide for Chandra High Resolution Spectroscopy: an in-depth discussion of grating analysis.
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
- Get Started
- Examine the tgdetect results
- Determine the Correct Source Location
- Run tg_create_mask with New Source List
- Creating a New Spectrum
- Parameter files:
- History
- Images
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: ]](piled.png)
[Version: full-size]
Figure 1: Piled grating observation
Figure 2: Grating observation with blocked zero order
![[Thumbnail image: ]](blocked.png)
[Version: full-size]
Figure 2: Grating observation with blocked zero order
Examine the tgdetect results
tgdetectunix% 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: ]](tgdetect.png)
[Version: full-size]
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: ]](tgfzo.png)
[Version: full-size]
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.]](regions.png)
[Version: full-size]
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 |