Search https://cxc.harvard.edu/ciao/
Contact the CXC HelpDesk
Last modified: 15 Feb 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/tgdetect/
/ ciao / threads / tgdetect /
Return to Threads Page: Top | All | Grating

Correcting a Misplaced Zero-order Source Position

CIAO 4.17 Science Threads

Overview

Synopsis:

When tgdetect is run as a stand-alone tool with the zero order filter position set to the default value as in the "Obtain Grating Spectra" threads, the tool uses hard-wired numbers to locate the center of the box for searching zero-order sources; see Get Started for the values. If the source is outside of the default search area, the tool will not locate it, regardless of how prominent it is.

The tgdetect2 tool will automatically use the target location, RA_TARG,DEC_TARG when it runs tgdetect.

Purpose:

To run tgdetect with a specific zero order filter position to identify the correct zero-order source position.

Related Links:

Last Update: 15 Feb 2022 - Review for CIAO 4.14. Updated for Repro5 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: 1703 (LETG/ACIS-S, PKS 2155-304)

unix% download_chandra_obsid 1703 evt1

When tgdetect is run in the grating level 1.5 pipeline, it uses the observer-specified target coordinates from the file header to locate the center of box for searching zero-order sources.

However, if tgdetect is run as a stand-alone tool with zo_pos_x and zo_pos_y set to the default value (e.g. in the "Obtain Grating Spectra" threads), the tool uses hard-wired numbers to locate the center of the box for searching zero-order sources. For ACIS, the hard-wired center is (4096.5, 4096.5); for HRC-S it is (32768.5, 32768.5); for HRC-I it is (16384.5,16384.5). If the source is outside of the default search area (400 square pixels for ACIS, 1800 square pixels for HRC),the tool will not locate it, regardless of how prominent it is.

It is assumed that tgdetect has been run once already and therefore a source list called acis_src1a.fits exists.

This source list was not obtained from the Archive. The parameter file of the tgdetect run used to create it is available here, and the file may be downloaded.

Display the Source List

The source list may be viewed over the event file using ds9: 

unix% ds9 acisf01703_000N005_evt1.fits &

Overlay the region file that was created by the first run of tgdetect (Region → Load Regions → acis_src1a.fits), as shown in Figure 1. Clearly the tool has not identified the prominent zero-order source.

Figure 1: Incorrect source list overlaid on event data

[Thumbnail image: The source list contains four elliptical regions far from the physical source.]

[Version: full-size]

[Print media version: The source list contains four elliptical regions far from the physical source.]

Figure 1: Incorrect source list overlaid on event data

Get Target Coordinates (dmkeypar)

The next step is to determine where the observer specified the source to be. This information is contained in the RA_TARG and DEC_TARG header keywords of the event file: 

unix% dmkeypar acisf01703_000N005_evt1.fits RA_TARG echo+
329.716667

unix% dmkeypar acisf01703_000N005_evt1.fits DEC_TARG echo+
-30.225556

These are the celestial coordinates of the object in degrees; this is important to note for the next step.

Convert Position to Sky Coordinates (dmcoords)

Since tgdetect requires the search values to be in sky coordinates, we need to use dmcoords to convert the values. Here it is run in interactive mode after setting the celestial coordinate format to degrees: 

unix% punlearn dmcoords
unix% pset dmcoords celfmt=deg
unix% dmcoords acisf01703_000N005_evt1.fits celfmt=deg op=cel ra=329.716667 dec=-30.225556 verb=1
----------------------------------------
Spacecraft Configuration:
----------------------------------------
Dataset:           acisf01703_000N005_evt1.fits
Observatory:         
Telescope:        CHANDRA
Grating:          LEG
Instrument:       ACIS
Detector:         ACIS
Chip:             ACIS-S3
SIM position:         -0.683     0.000  -182.134    
SIM offset:            0.000     0.000     0.000   
SIM rotation:          0.000     0.000     0.000   
Grating order: 0
Focal length:     10070.000000
Chip pixel scale: 0.023987 x 0.023987 mm/pixel
Chip size:        1024 x 1024 pixels

----------------------------------------
Sky Coordinate Configuration:
----------------------------------------
Sky coordinate pixel system: FP-1.1
Center pixel of sky plane:  (4096.500000,4096.500000)
Size of sky plane:          8192 x 8192
Sky pixel scale:            0.492000 arcsec/pixel
Nominal:          RA 329.722436 Dec -30.195914 Roll   0.000000
Aspect:           RA 329.722436 Dec -30.195914 Roll  97.765932


  --------  

(RA,Dec):    21:58:52.000     -30:13:32.00   
(RA,Dec):       329.71667     -30.22556 deg
THETA,PHI          1.803'         17.31 deg
(Logical):        4132.97       3879.61
SKY(X,Y):         4132.97       3879.61
DETX,DETY         4306.48       4161.94
CHIP ACIS-S3       430.78        132.70
TDET              4347.78       1834.70
GDPX,GDPY        32768.50      16384.50
GAC R,D                 0             0 deg
ENERGY           1.000000 keV
ZO(RA,Dec):  21:58:52.000     -30:13:32.00   
ZO(RA,Dec):     329.71667     -30.22556 deg
ZO SKY(X,Y):      4132.97       3879.61
ZO DETX,DETY      4306.48       4161.94

The position in sky pixels is (4132.97, 3879.61).

Run tgdetect Again

Now we can tell tgdetect to center the search filter at these coordinates and run the tool again: 

unix% pset tgdetect infile=acisf01703_000N005_evt1.fits
unix% pset tgdetect zo_pos_x=4132.97
unix% pset tgdetect zo_pos_y=3879.61
unix% pset tgdetect outfile=acis_target_src1a.fits
unix% tgdetect
Input L1 event file (root_evt1.fits or .lis) (acisf01703_000N005_evt1.fits): 
Input source position(s) file from previous OBI or NONE (NONE): 
Output source position(s) file name (acis_target_src1a.fits):

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

Displaying the new source list (Region → Load Regions → acis_target_src1a.fits) shows that tgdetect now picks up the correct zero-order source (Figure 2).

Figure 2: Correct source list overlaid on event data

[Thumbnail image: The source region is a green circle located at the physical source.]

[Version: full-size]

[Print media version: The source region is a green circle located at the physical source.]

Figure 2: Correct source list overlaid on event data

The data is displayed at zoom=4.

Summary

This thread is now complete. You can continue with the grating analysis from the "Get region mask (tg_create_mask)" step of the HETG/ACIS-S, LETG/ACIS-S, LETG/HRC-S, or LETG/HRC-I 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 = acisf01703_000N005_evt1.fits   Input L1 event file (root_evt1.fits or .lis)
OBI_srclist_file = NONE             Input source position(s) file from previous OBI or NONE
       outfile = acis_src1a.fits  Output source position(s) file name (root_src1a.fits)
#
#   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 =  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 =  no)            make a celldetect log file?
     (psftable = /soft/ciao/data/psfsize_20000830.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 =  0)              background count/pixel, for celldetect
  (bkgerrvalue =  0)              background error, for celldetect
        (eband =  1.4967)         energy band, for celldetect
      (eenergy =  0.8)            encircled energy of PSF, for celldetect
      (snrfile = none)            celldetect snr output file (for convolution only)
     (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 =  1)            Value of SNR ratio to use as lower limit
     (setsrcid =  yes)            Set src ids in output file?
#
#   tgmatchsrc parameters
#
(max_separation =  3)             Maximum allowed separation (arcsec) for sources to match
#
#
      (clobber = yes)             OK to overwrite existing output file(s)?
      (verbose = 0)               Verbosity level (0 = no display)
         (mode = ql)
    

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 = acisf01703_000N005_evt1.fits   Input L1 event file (root_evt1.fits or .lis)
OBI_srclist_file = NONE             Input source position(s) file from previous OBI or NONE
       outfile = acis_target_src1a.fits Output source position(s) file name (root_src1a.fits)
#
#   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 = 4132.97)         Center GZO filter sky X position (default=pixel(ra_nom))
     (zo_pos_y = 3879.61)         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 =  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 =  no) make a celldetect log file?
     (psftable = /soft/ciao/data/psfsize_20000830.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 = 0)              background count/pixel, for celldetect
  (bkgerrvalue = 0)              background error, for celldetect
        (eband = 1.4967)         energy band, for celldetect
      (eenergy = 0.8)            encircled energy of PSF, for celldetect
      (snrfile = none)            celldetect snr output file (for convolution only)
     (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 = 1)             Value of SNR ratio to use as lower limit
     (setsrcid = yes)             Set src ids in output file?
#
#   tgmatchsrc parameters
#
(max_separation = 3)              Maximum allowed separation (arcsec) for sources to match
#
#
      (clobber = yes)             OK to overwrite existing output file(s)?
      (verbose = 0)               Verbosity level (0 = no display)
         (mode = ql)

History

16 Dec 2004 updated for CIAO 3.2: new parameters for temporary and diagnostic files; include dmcoords asolfile parameter
05 Dec 2005 updated for CIAO 3.3: parameter file change (kernel parameter removed from tgdetect)
29 Mar 2006 renamed thread from "Correct Zero-order Source Position"
01 Dec 2006 updated for CIAO 3.4: change to wording of tgdetect/dmcopy warning
11 Jan 2008 updated for CIAO 4.0: ds9 now automatically looks for the "[SRCLIST]" 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: acis_src1a.fits has four source regions; images are inline
16 Jun 2009 added About the Chandra Grating Data Archive and Catalog section
22 Dec 2010 reviewed for CIAO 4.2: no changes
12 Jan 2011 reviewed for CIAO 4.3: no changes
06 Jan 2012 reviewed for CIAO 4.4: no changes
03 Dec 2012 Review for CIAO 4.5; file version name changes
11 Dec 2013 Review for CIAO 4.6
23 Dec 2014 Review for CIAO 4.7; updated tgdetect default parameters (no redirects).
15 Feb 2022 Review for CIAO 4.14. Updated for Repro5 and CALDB 4.9.6
Return to Threads Page: Top | All | Grating
/ ciao / threads / tgdetect /