Last modified: 8 Feb 2022

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

Grating Spectra for Multiple Sources - HRC

CIAO 4.16 Science Threads


Overview

Synopsis:

Generate a PHA2 spectrum file for an HRC grating observation with multiple sources in the field of view.

Run this thread if:

you are working with an HRC-I or HRC-S LETG dataset and wish to create spectra for each of the sources in the field of view. Since multiple-source analysis is not done in standard processing, all users interested in more than one source in the field need to complete this thread.

Related Links:

Last Update: 8 Feb 2022 - Review for CIAO 4.14. No changes.


Contents


Data Preparation

This analysis thread starts with the level 1 event file. Before beginning, users may wish to reprocess the data to create a new event file with the most recent calibration applied. Instructions on how to reprocess your data are available in the HRC Data Preparation Analysis Guide.


Get Started

Download the sample data: 29 (LETG/HRC-S, Alpha Cen)

unix% download_chandra_obsid 29 evt1,flt,asol
[NOTE]
Early dataset

The data used in this thread was taken very early in the Chandra mission. It was not included in the bulk reprocessing metioned in the Watchout page. The keywords required for analysis with CIAO need to be added by running chandra_repro or r4_header_update.

In this thread, we assume that all relevant files are in the same working directory.


Generate a New Level=1.5 Event File

1. Get position of zero-order image (tgdetect)

To find the zero-order locations, the tool tgdetect is run. The tgdetect2 tool identifies only the single brightest source and therefore is not useful for this particular thread. When processing multiple sources, the number of sources detected is determined by the tgdetect snr_thresh and snr_ratio_limit parameters. We also use a small fixedcell value to prevent multiple sources in close proximity from being grouped together.

unix% punlearn tgdetect
unix% pset tgdetect infile=hrcf00029_000N005_evt1.fits
unix% pset tgdetect outfile=hrc_29_src1a.fits
unix% pset tgdetect fixedcell=6
unix% pset tgdetect snr_thresh=20
unix% pset tgdetect snr_ratio_limit=0.25
unix% tgdetect
Input L1 event file (hrcf00029_000N005_evt1.fits): 
Input source position(s) file from previous OBI or NONE (NONE): 
Output source position(s) file name (hrc_29_src1a.fits): 

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

Values for snr_thresh and snr_ratio_limit may be modified depending on how many sources you would like to detect. snr_thresh is the minimum signal to noise ratio that will be considered as a source. snr_ratio_limit is the ratio of the signal to noise ratio of the primary source to that of any other potential source that will be accepted as a source. If unsure of the proper values to use for these keywords it may be a good idea to run tgdetect first with excessively low values (snr_thresh=5, snr_ratio_limit=0.01). Inspect the SNR column file of the output file. Choose a snr_thresh just under the value for the faintest source you would like detected. Choose a sufficiently low snr_ratio_limit to include this source.

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

unix% ds9 hrcf00029_000N005_evt1.fits &

Overlay the source list: Region → Load Regions → hrc_29_src1a.fits. Figure 1 shows the source list on the event file.

Figure 1: Event file with source list overlaid

[Thumbnail image: The sources are displayed in red on the event data in ds9.]

[Version: full-size]

[Print media version: The sources are displayed in red on the event data in ds9.]

Figure 1: Event file with source list overlaid

If the zero order of the source is outside of the default search area (e.g. far from the aimpoint), tgdetect will not find it. If this problem affects your data, it will be obvious when the source list is displayed on the event file. In this case, run the Correcting a Misplaced Zero-order Source Position thread to identify the correct source position.


2. Get region mask (tg_create_mask)

The location of the spectrum needs to be found next, via the tool tg_create_mask.

unix% punlearn tg_create_mask
unix% pset tg_create_mask infile=hrcf00029_000N005_evt1.fits
unix% pset tg_create_mask outfile=hrc_29_L1a.fits
unix% pset tg_create_mask input_pos_tab=hrc_29_src1a.fits
unix% tg_create_mask
Input event file or stack (hrcf00029_000N005_evt1.fits): 
Output region file or stack (hrc_29_L1a.fits): 
Input table with zero order positions or stack (hrc_29_src1a.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 region file, hrc_29_L1a.fits, will be used to mask the event file. The regions may be viewed over the event file using ds9:

unix% ds9 hrcf00029_000N005_evt1.fits &

Overlay the region file: Region → Load Regions → hrc_29_L1a.fits, as shown in Figure 2.

Figure 2: 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 2: Event file with region file overlaid

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

dmlist shows that there are 2 rows in the file, which corresponds to 2 regions - one for each source and the corresponding diffracted part (LEG):

unix% dmlist hrc_29_L1a.fits blocks
  
--------------------------------------------------------------------------------
Dataset: hrc_29_L1a.fits
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: REGION                         Table         8 cols x 4        rows

tg_create_mask will only create a mask for the first ten sources. If there are more than ten sources of interest tg_create_mask must be run multiple times with a filter on the input_pos_tab filename:

unix% pset tg_create_mask input_pos_tab=hrc_29_src1a.fits"[SRCLIST][tg_srcid=11:20]"

Alternatively, user source parameters may be explicitly set. This is somewhat tedious, but gives manual control over the resulting regions (see plist tg_create_mask for detailed comments and an example). radius_factor_zero is the size of the circle around the source and width_factor_letg is the width of the grating arms in the mask created. If the default mask is too large with respect to nearby sources, then counts could be easily associated with the wrong source. The default values are for isolated sources and are wide enough to provide source and background regions later when binning with tgextract.


3. Run tg_resolve_events

The tool tg_resolve_events is now used to assign grating events to spectral orders:

unix% punlearn tg_resolve_events
unix% pset tg_resolve_events infile=hrcf00029_000N005_evt1.fits
unix% pset tg_resolve_events outfile=hrc_29_evt1a.fits
unix% pset tg_resolve_events regionfile=hrc_29_L1a.fits
unix% pset tg_resolve_events acaofffile=@pcad_asol1.lis
unix% pset tg_resolve_events eventdef=")stdlev1_HRC"
unix% pset tg_resolve_events osipfile=none
unix% tg_resolve_events
Input event file or stack (hrcf00029_000N005_evt1.fits): 
Input region file or stack (hrc_29_L1a.fits): 
Output event file or stack (hrc_29_evt1a.fits): 
Input aspect offset file (@pcad_asol1.lis): 

If you get a warning that says "Event chip position is outside of valid range.", it is explained in the tg_resolve_events bug page.

It is important to note several things here:

  • In many cases, there will be more than one aspect solution file (pcad_asol1.fits) for an observation. All the files must be input to the acaofffile parameter in chronological order (the time is in the filename, so "ls" lists them in order), either as a comma-separated list or as a stack. Here we use:

    unix% cat pcad_asol1.lis 
    pcadf062419415N004_asol1.fits
    
  • The unusual syntax of the eventdef parameter; the tool will not access the predefined string if the leading ")" is missing.

  • Due to the proximity of the two sources in ObsID 29, the extraction regions created with the default tg_create_mask parameters overlap, so tg_resolve_events will not be able to unambiguously resolve the dispersed events and the dispersion properties will be set to 0. The extraction regions can be narrowed by changing the tg_create_mask width_factor_letg parameter; the default is quite wide because HRC LETG data has a high background. The multi-source capability was intended for mostly disjoint regions. ObsID 29 was used for this example because it was an early HRC observation with multiple sources, but in an actual analysis of this or a similar observation, it might be best to run two extractions, one on each source, with the caveat that one side of the background will contain the other source.

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


Generate a New Level=2 Event File

At this point, the thread splits to provide the correct filtering steps for HRC-S and HRC-I observations. The HRC-S section continues to use ObsID 29, while the HRC-I section is generalized for any observation.

1. For HRC-S Observations

  1. Apply background filter (dmcopy)

    A new pulse-height filter for use with LETG data was released in CALDB 4.9.4 (15 December 2020). Over half of Level=2 background events can be removed at most wavelengths with a loss of ~1.25% of X-ray events. This is the recommended filter for use with all HRC-S/LETG data.

    The LETG/HRC-S Background Filter page has detailed information on how this filter was developed.

    First we use calquiz to look up the correct background filter file in the calibration database (CALDB).

    unix% calquiz infile=hrc_460_evt1a.fits product=TGPIMASK2 calfile=CALDB echo+
    /soft/ciao/CALDB/data/chandra/hrc/tgpimask2/letgD1999-07-22pireg_tgmap_N0002.fits[2]
    

    and then we use that file name (without the block number) as a filter on the event file.

    unix% punlearn dmcopy
    unix% dmcopy \
          "hrc_29_evt1a.fits[EVENTS][(tg_mlam,pi)=region(/soft/ciao/CALDB/data/chandra/hrc/tgpimask2/letgD1999-07-22pireg_tgmap_N0002.fits)]" \
          hrc_29_back_evt1a.fits
    
    unix% dmappend hrc_29_evt1a.fits"[region][subspace -time]" hrc_29_back_evt1a.fits
    
  2. Filter on status (dmcopy)

    We need to apply the status filter that is specific to HRC-S observations; a value of 0 demands that the bit be flagged as "good", a value of x indicates that either status (0/1) is acceptable:

    unix% punlearn dmcopy
    unix% dmcopy "hrc_29_back_evt1a.fits[status=xxxxxx00xxxx0xxx0000x000x00000xx]" \
          hrc_29_flt1_evt1a.fits
    
    unix% dmappend hrc_29_back_evt1a.fits"[region][subspace -time]" hrc_29_flt1_evt1a.fits
    
  3. Apply GTI filter (dmcopy)

    The Good Time Intervals (GTIs) supplied by the pipeline now need to be applied:

    unix% punlearn dmcopy
    unix% dmcopy \
          "hrc_29_flt1_evt1a.fits[EVENTS][@hrcf00029_000N005_std_flt1.fits]" \
          hrc_29_evt2.fits opt="" 
    
    unix% dmappend "hrc_29_flt1_evt1a.fits[region][subspace -time]" hrc_29_evt2.fits
    

    Be sure to include the @ symbol in the filter expression; the command will not be executed properly if it is omitted.

    The opt="" parameter in dmcopy and the dmappend command are a workaround for the bug in time-filtering grating data.


2. For HRC-I Observations

  1. Filter on status (dmcopy)

    Next we apply the status filter that is specific to HRC-I observations; a value of 0 demands that the bit be flagged as "good", a value of x indicates that either status (0/1) is acceptable:

    unix% punlearn dmcopy
    unix% dmcopy "hrc_evt1a.fits[status=xxxxxx00xxxx0xxx0000x000x0000000]" \
          hrc_flt1_evt1a.fits
    
    unix% dmappend hrc_evt1a.fits"[region][subspace -time]" hrc_flt1_evt1a.fits
    
  2. Apply GTI filter (dmcopy)

    Finally, the Good Time Intervals (GTIs) supplied by the pipeline are applied:

    unix% punlearn dmcopy
    unix% dmcopy \
          "hrc_flt1_evt1a.fits[EVENTS][@hrc_std_flt1.fits]" \
          hrc_evt2.fits opt="" 
    
    unix% dmappend \
          "hrc_flt1_evt1a.fits[region][subspace -time]" \
          hrc_evt2.fits
    

    Be sure to include the @ symbol in the filter expression; the command will not be executed properly if it is omitted.

    The opt="" parameter in dmcopy and the dmappend command are a workaround for the bug in time-filtering grating data.


Extract a Grating Spectrum (tgextract)

The CIAO tool tgextract produces a PHA2 spectrum file from the level=2 data file:

unix% punlearn tgextract
unix% pset tgextract infile=hrc_29_evt2.fits
unix% pset tgextract outfile=hrc_29_pha2.fits
unix% tgextract
Input event file (output event file from L1.5 processing) (hrc_29_evt2.fits): 
If typeII, enter full output file name or '.'; if typeI, enter output rootname (hrc_29_pha2.fits): 
Input ancillary response file name (none): 
Input redistribution file name (none): 
Source ID's to process: 'all', comma list, @file (all): 
Grating parts to process: HETG, HEG, MEG, LETG, header_value (HETG|HEG|MEG|LETG|header_value) (header_value): 
Grating diffraction orders to process: 'default', comma list, range list, @file (default): 
Ouput file type: typeI (single spectrum) or typeII (multiple spectra) (pha_typeI|pha_typeII) (pha_typeII): 

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

Using dmlist, we can examine the output file:

unix% dmlist hrc_29_pha2.fits blocks
--------------------------------------------------------------------------------
Dataset: hrc_29_pha2.fits
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: SPECTRUM                       Table        13 cols x 4        rows
Block    3: REGION                         Table        10 cols x 12       rows

There are 2 rows for each of the 2 identified sources, making a total of 4 rows in the file. Since there are three regions associated with each order (source, upper background, and lower background), the REGION block contains 12 rows. For more examples of viewing PHA2 files, see the Examining Grating Spectra thread.


Caveat: using the background in analysis

It is important to include backgrounds in the analysis since the HRC-S instrumental background is significant. For this observation, the sources are close enough that one background region (background up or background down) for each source will be contaminated by the neighboring source. When analysing the data, only the uncontaminated half of the background should be used.

The Applying Customized Background Regions to LETG/HRC-S Observations thread show how to edit the background region before extracting the spectra to avoid this problem.


Summary

This thread is now complete; the PHA2 grating spectrum file is named hrc_29_pha2.fits. You should next:

  1. read the Computing Average HRC Dead Time Corrections thread to see if you need to recompute the deadtime statistics for your dataset
  2. create HRC Grating RMFs

In order to use Gaussian statistics to fit a model to a dataset, it is often necessary to "group" the data - i.e. combine channels until you have enough counts. Before fitting the data in Sherpa, read the Grouping a Grating Spectrum thread for more information.

[NOTE]
Detector edges

Electrical field-fringing effects on the ends of the three HRC-S segments create incorrect event positions and distorted pulse height distributions. Data processed prior to the May 2017 release of CALDB 4.7.4 (using HRC-S BADPIX map version 3) do not remove all the affected events; spectral features near the plate gaps should therefore be treated with suspicion.



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 = hrcf00029_000N005_evt1.fits    Input L1 event file
OBI_srclist_file = NONE             Input source position(s) file from previous OBI or NONE
       outfile = hrc_29_src1a.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 = 20)              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 -> /soft/ciao/data/psfsize20010416.fits) table of PSF size data, for celldetect
    (fixedcell = 6)               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 = 0.25)            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_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 = hrcf00029_000N005_evt1.fits    Input event file or stack
       outfile = hrc_29_L1a.fits     Output region file or stack
 input_pos_tab = hrc_29_src1a.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
(width_factor_hetg = 35)              A scale factor which multiplies the one-sigma width of the heg/meg mask
(width_factor_letg = 40)              A scale factor which multiplies the one-sigma width of the letg mask 
(r_astig_max_hetg = 0.5600000000000001) Max grating r coord (deg, along the dispersion) for HETG astigmatism
(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
# --------------------------------------------------------------------------
..(through Source J)..
      (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)              




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


#--------------------------------------------------------------------------
#
#   tg_resolve_events.par: Parameter file for the tg_resolve_events program
#
#--------------------------------------------------------------------------
        infile = hrcf00029_000N005_evt1.fits    Input event file or stack
       outfile = hrc_29_evt1a.fits   Output event file or stack
    regionfile = hrc_29_L1a.fits     Input region file or stack
    acaofffile = @pcad_asol1.lis  Input aspect offset file
(alignmentfile = )acaofffile -> @pcad_asol1.lis) Input sim offset file
      (logfile = stdout)          Output log (NONE|<filename>|stdout)
# The osipfile contains position dependent energy limits based on
# the CCD resolution, used for order-sorting.
# A value of "NONE" means that the file will not be used, and
# that the parameters, osort_hi and osort_lo will be used.
     (osipfile = none)            Lookup table for order resolving (for acis data only)
#sort_hi, osort_lo specify fractional deviations from the integer
#order which will be included in order-sorting via CCD ENERGY values (PHA).
#eg. osort_lo-0.3, osort_hi=0.2 means that photons with real-valued
#orders between 0.7 < order <= 1.2 will be included in first order,
#1.7 < order <= 2.2 will be second order, etc.
     (osort_lo = 0.3)             Order-sorting lower bound fraction; order > m - osort_lo
     (osort_hi = 0.3)             Order-sorting high bound fraction; order <= m + osort_hi
  (grating_obs = header_value)    Observed grating type (header_value|HETG|HEG|MEG|LETG)
     (detector = header_value)    Detector type: ACIS | HRC-I | HRC-S | header_value
(energy_lo_adj = 1.0)             Lower Energy limit factor
(energy_hi_adj = 1.0)             Upper Energy limit factor
  (time_offset = 0)               Offset to add to event time to synch w/ alignment data
    (rand_seed = 1)               Random seed (for pixlib), 0 = use time dependent seed
(rand_pix_size = 0.0)             pixel randomization width (-size..+size), 0.0 = no randomization
     (eventdef = )stdlev1_HRC ->{d:time,f:rd,s:chip,l:tdet,f:det,f:sky,s:chip_id,s:pha,s:pi,
s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}) Output format definition
      (stdlev1 = )eventdef ->{d:time,f:rd,s:chip,l:tdet,f:det,f:sky,s:chip_id,s:pha,s:pi,
s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}) 
 (stdlev1_ACIS ={d:time,i:expno,f:rd,s:chip,s:tdet,f:det,f:sky,s:ccd_id,l:pha,s:pi,
f:energy,s:grade,s:fltgrade,s:node_id,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status})
ACIS event format definition string
  (stdlev1_HRC = {d:time,f:rd,s:chip,l:tdet,f:det,f:sky,s:chip_id,s:pha,s:pi,s:tg_m,
f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}) HRC event format definition string
# --------------------------------------------------------------------------
      (geompar = geom)            Parameter file for Pixlib Geometry files
      (verbose = 0)               Verbosity level of detail (0=none, 5=most)
      (clobber = no)              Clobber outfile if it already exists?
         (mode = ql)              




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


##
## TGEXTRACT -- create 1D spectrum(a) table file(s) from the
##              L1.5 output event list
##
        infile = hrc_29_evt2.fits    Input event file (output event file from L1.5 processing)
       outfile = hrc_29_pha2.fits    If typeII, enter full output file name or '.'; if typeI, enter output rootname
#
# tg_srcid_list parameter explanation...
#  - "all" will process all the sources id's found in the event list
#  - a comma list is a comma separated string list of all the 
#    sources to process, ie:
#       "1,2,5,7"
#  - @file is a pointer to an ascii file which contains a comma
#    separated list of the id's to process
#
 tg_srcid_list = all              Source ID's to process: 'all', comma list, @file
  tg_part_list = header_value     Grating parts to process: HETG, HEG, MEG, LETG, header_value
#
# tg_order_list parameter explanation...
#  - "default" is set to process the following:
#       if ACIS:  1, 2, 3, -1, -2, -3
#       if HRC:   -1, 1
#  - a comma list is a comma separated string list of the orders
#    the user wants to process, ie:
#       "-5, -1, 1, 3"
#  - a range list sets the min and max of the orders to process;
#    all the orders in between, will be processed, ie:
#       "-1..5"  will do orders from -1 to +5th order
#    a range list can be mixed with comma separated list
#  - @file is a pointer to an ascii file which contains a comma
#    separated list and/or range list of the orders to process
#
 tg_order_list = default          Grating diffraction orders to process: 'default', comma list, range list, @file
      ancrfile = none             Input ancillary response file name
      respfile = none             Input redistribution file name
  outfile_type = pha_typeII       Ouput file type: typeI (single spectrum) or typeII (multiple spectra)
(inregion_file = none)            Input region file.
     (backfile = none)            Input background file name
        (rowid = )                If rowid column is to be filled in, enter name here
    (bin_units = angstrom)        Bin units (for bin parameters below): angstrom, eV, keV
  (min_bin_leg = compute)         Minimum dispersion coordinate for LEG, or 'compute'
  (max_bin_leg = compute)         Maximum dispersion coordinate for LEG, or 'compute' 
 (bin_size_leg = compute)         Bin size for binning LEG spectra, or 'compute'
 (num_bins_leg = compute)         Number of bins for the output LEG spectra, 'compute'
  (min_bin_meg = compute)         Minimum dispersion coordinate for MEG, or 'compute'
  (max_bin_meg = compute)         Maximum dispersion coordinate for MEG, or 'compute'
 (bin_size_meg = compute)         Bin size for binning MEG spectra, or 'compute'
 (num_bins_meg = compute)         Number of bins for the output MEG spectra, or 'compute'
  (min_bin_heg = compute)         Minimum dispersion coordinate for HEG, or 'compute'
  (max_bin_heg = compute)         Maximum dispersion coordinate for HEG, or 'compute'
 (bin_size_heg = compute)         Bin size for binning HEG spectra, or 'compute'
 (num_bins_heg = compute)         Number of bins for the output HEG spectra, 'compute'
     (min_tg_d = default)         Minimum tg_d range to include in histogram, or use 'default'
     (max_tg_d = default)         Maximum tg_d range to include in histogram, or use 'default'
(extract_background = yes)             Extract the local background spectrum?
(min_upbkg_tg_d = default)         Minimum value of tg_d for the background up spectrum.
(max_upbkg_tg_d = default)         Maximum value of tg_d for the background up spectrum.
(min_downbkg_tg_d = default)         Minimum value of tg_d for the background down spectrum.
(max_downbkg_tg_d = default)         Maximum value of tg_d for the background down spectrum.
      (geompar = geom)            Parameter file for Pixlib Geometry files
      (clobber = no)              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: minor changes to parameter files
15 Feb 2005 new filtering bug discovered, follow workaround in Apply the background filter section
05 Dec 2005 updated for CIAO 3.3: bug fixes to the Data Model make the workaround previously given in the Apply the background filter section unnecessary (i.e. the modpireg script); output filenames include ObsID; parameter file change (kernel parameter removed from all "tg" tools)
05 Jan 2006 created Data Preparation section
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 "[REGION]" or "[SRCLIST]" extension in the region file, so it doesn't have to be specified
12 Feb 2009 updated for CIAO 4.1: images are inline; path to calibration files updated for CALDB 4
19 Feb 2009 added grouping information to the Summary
22 May 2009 new section: Caveat: using the background in analysis
09 Feb 2010 updated for CIAO 4.2: new HRC-S TGAIN and LETG PI filter released in CALDB 4.2.0; HRC-S "pha=0:254" filter is obsolete; the background filter is applied to "(tg_mlam,pi)" [prior to CIAO 4.2, was "(tg_lam,pi)"]; added an optional spatial filtering section
15 Mar 2010 added link to the Computing Average HRC Dead Time Corrections thread in the Summary
12 Jan 2011 reviewed for CIAO 4.3: no changes
25 Mar 2011 added workaround for GTI filtering bug to the Apply GTI filter sections
06 Jan 2012 reviewed for CIAO 4.4: no changes
27 Feb 2012 added link to HRC-S Event Position Errors Near the Aim Point webpage in the Overview.
03 Dec 2012 Review for CIAO 4.5; dmcopy warning removed;
11 Dec 2013 Review for CIAO 4.6; added note why tgdetect2 should not be run here.
22 Dec 2014 Review for CIAO 4.7; no changes.
24 Feb 2015 Removed optional RAWY filter. Replaced with a note about enhanced background at the detector edges.
29 Jun 2017 Revised the note about detector edges.
02 Dec 2020 Use calquiz to determine the name of the background PI filter file. Use dmappend to copy region block.
08 Feb 2022 Review for CIAO 4.14. No changes.