HETG/ACIS-S/CC-Mode Grating Spectra
![[CXC Logo]](../../imgs/cxc-logo.gif){kind=logo}
CIAO 4.16 Science Threads
Overview
Synopsis:
Generate a new PHA2 spectrum file for any HETG/ACIS-S/CC-mode grating observation to ensure that consistent calibration is used throughout the analysis.
Run this thread if:
You are working with an ACIS/HETG dataset taken in CONTINUOUS mode and want to create a new level=2 event file and extract a Type II PHA grating spectrum file.
For data taken with ACIS/HETG taken in TIMED mode, please follow the HETG/ACIS-S Grating Spectra thread.
Related Links:
- Description of enhancements to HETG/ACIS CC-mode processing
- About the Instrument: ACIS & HETG
- Analysis Guide for Chandra High Resolution Spectroscopy: an in-depth discussion of grating analysis.
- Continuous Clocking Mode why topic: additional information for users working with CC-mode data.
- Why topic: Destreaking ACIS Data
Last Update: 8 Feb 2022 - Review for CIAO 4.14. Updated for Repro-5/CALDB 4.9.6.
Contents
- About the Chandra Grating Data Archive and Catalog
- About the chandra_repro script
- Data Preparation
- Get Started
- Generate a New Level=1.5 Event File
- Generate a New Level=2 Event File
- Extract a Grating Spectrum (tgextract)
- Summary
- 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.
About the chandra_repro script
The chandra_repro script reprocessing script automates the recommended data processing steps presented in the CIAO analysis threads. The script reads data from the standard data distribution (e.g. primary and secondary directories) and creates a new bad pixel file, a new level=2 event file, and a new level=2 Type II PHA file.
chandra_repro also will now create the appropriate ARF and RMF for each grating order and arm in the spectrum using the mktgresp script. The response files will be stored in a tg/ subdirectory of the outdir parameter.
Refer to "ahelp chandra_repro" for more information.
![[WARNING]](../../imgs/warning.png)
If you have run chandra_repro you do not need to complete the rest of this thread unless you want to understand the individual processing steps, the options avaiable, or need to apply any non-standard calibrations.
Data Preparation
This analysis thread starts with the level 1 event file. Before beginning, users may wish to reprocess the data with chandra_repro to create a new event file with the most recent calibration applied.
It is also suggested that users set the observation-specific bad pixel file, as described in the Setting the Observation-specific Bad Pixel Files thread.
Get Started
Download the sample data: 16596 (HETG/ACIS-S/CC-mode, GRO J1744-28)
unix% download_chandra_obsid 16596 evt1,flt,asol,mtl
In this thread, we assume that all relevant files are in the same working directory.
If you do not need to run this thread, go directly to the ACIS-S Grating RMFs thread.
Generate a New Level=1.5 Event File
1. Get position of zero-order image (tgdetect2)
To find the zero-order location, the tool tgdetect2 is run. tgdetect2 will automatically select the best tool: tgdetect or tg_findzo.
unix% punlearn tgdetect2 unix% pset tgdetect2 infile=acisf16596_000N003_evt1.fits unix% pset tgdetect2 outfile=acis_16596_src1a.fits unix% tgdetect2 Input event file (acisf16596_000N003_evt1.fits): Output source table file (acis_16596_src1a.fits):
The contents of the parameter file may be checked using plist tgdetect2.
The region created by tgextract2 may produce a zero-order ellipse that has a zero (0) length minor axis. This is due to the way sky coordinates are assigned in CC mode. To display the region in ds9, users may need to adjust the minor axis as shown below.
unix% dmlist "acis_16596_src1a.fits[cols x,y,shape,r]" data,clean # POS(X,Y) SHAPE R[2] 4106.50 4223.6263134421 ellipse 4.3540382385 0 unix% dmtcalc acis_16596_src1a.fits acis_16596_modsrc1a.fits exp="r=r;r[1]=1"
The acis_16596_modsrc1a.fits file should then display properly in ds9.
unix% ds9 acisf16596_000N003_evt1.fits &
Overlay the source list: Region → Load Regions → acis_16596_modsrc1a.fits
This modified region file is only needed for display purposes. The rest of this thread will use the unmodified tgdetect2 output.
tgdetect2 will try to find the best method possible to determine the correct zeroth order location. However, there may be exceptional cases where the results are incorrect. Displaying the region in ds9 will identify such exceptional cases.
Users working in crowded fields or with extended objects may find tgdetect2 has strayed from the intended source. These users should manually set the tg_create_mask source parameters as described in the Correcting a Misplaced Zero-order Source Position thread.
2. Get region mask (tg_create_mask)
The location of the HEG and MEG "arms" needs to be found next, via the tool tg_create_mask.
unix% punlearn tg_create_mask unix% pset tg_create_mask infile=acisf16596_000N003_evt1.fits unix% pset tg_create_mask outfile=acis_16596_msk1a.fits unix% pset tg_create_mask input_pos_tab=acis_16596_src1a.fits unix% tg_create_mask Input event file or stack (acisf16596_000N003_evt1.fits): Output region file or stack (acis_16596_msk1a.fits): Input table with zero order positions or stack ($root;_src1a.fits): Observed grating type (header_value|HETG|HEG|MEG|LETG) (HETG|HEG|MEG|LETG|header_value|HEADER_VALUE) (header_value):
The region file, acis_16596_msk1a.fits, will be used to mask the event file. The regions may be viewed over the event file using ds9:
unix% ds9 acisf16596_000N003_evt1.fits &
Overlay the region file: Region → Load Regions → acis_16596_msk1a.fits Figure 1 shows the regions on the event file.
The contents of the parameter file may be checked using plist tg_create_mask.
Figure 1: Event file with region file overlaid
![[Thumbnail image: The region mask outlines the photons from the source and the grating arms.]](ds9.png)
[Version: full-size]
Figure 1: Event file with region file overlaid
The regions are loaded from the acis_16596_msk1a.fits file, which was made by tg_create_mask.
In CC mode the mask is simply a box that encloses the entire detector with the zeroth order location identified as a circle. Unliked TIME mode data, in CC mode the HEG and MEG arms are not differentiated in the mask.
3. Run tg_resolve_events : First Pass
The tool tg_resolve_events is now used to assign grating events to spectral orders, using the detector energy resolution for order separation.
With ACIS continuous clocking mode data, the data will be run through tg_resolve_events twice. The first run is used to estimate the true CHIPY coordinates of events based on the location of the grating zero order location and the known dispersion pattern (grating angle) of the HETG. After the CHIPY coordinates are assigned, the events energies are re-calibrated and then re-run through tg_resolve_events for the final grating order/energy determination.
unix% punlearn tg_resolve_events unix% pset tg_resolve_events infile=acisf16596_000N003_evt1.fits unix% pset tg_resolve_events outfile=acis_16596_tmp_evt1a.fits unix% pset tg_resolve_events regionfile=acis_16596_msk1a.fits unix% pset tg_resolve_events acaofffile=@pcad_asol1.lis
![[NOTE]](../../imgs/note.png)
The default "event definition", eventdef, parameter is set for ACIS with data taken in TIMED mode. This is not appropriate for this datasets.
unix% pget tg_resolve_events eventdef.p_value )stdlev1_ACIS
For data taken in Continuous Clocking (CC) mode users should select the correct event definition to match the DATAMODE of the observation
unix% dmkeypar acisf16596_000N003_evt1.fits readmode echo+ CONTINUOUS unix% dmkeypar acisf16596_000N003_evt1.fits datamode echo+ CC33_GRADED
| DATAMODE | eventdef |
|---|---|
| CC33_GRADED | unix% pset tg_resolve_events eventdef=")ccgrdlev1a" |
| CC33_FAINT | unix% pset tg_resolve_events eventdef=")cclev1a" |
These CC mode specific event definitions include additonal columns related to the location of the zero order and estimated chipy location.
For the first pass of separating orders, users should also forgo the normal order sorting calibration file and instead use the osort_lo and osort_hi parameters. This allows for more events to be assigned grating coordinates, which after re-calibration may then become valid.
These parameters are now pset and the tool is executed:
unix% pset tg_resolve_events eventdef=")ccgrdlev1a" unix% pset tg_resolve_events osipfile="none" unix% pset tg_resolve_events osort_lo=0.3 unix% pset tg_resolve_events osort_hi=0.3 unix% tg_resolve_events Input event file or stack (acisf16596_000N003_evt1.fits): Input region file or stack (acis_16596_msk1a.fits): Output event file or stack (acis_16596_tmp_evt1a.fits): Input aspect offset file (@pcad_asol1.lis):
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 pcadf16596_000N001_asol1.fits
The contents of the parameter file may be checked using tg_resolve_events.
4. Re-calibrate with acis_process_events
The output from the first pass of tg_resolve_events now includes an estimate of the CHIPY location based on the location of the zero order and the known grating geometry dispersion pattern (grating angles). The acis_process_events command is now used (again) to use the calibrations for these adjusted CHIPY locations
acis_process_events is run in a similar way to the Reprocessing Data to Create a New Level=2 Event File thread. Instead of using the Level 1 event file, the output from the first pass of tg_resolve_events is used. Also the eventdef parameter is changed to match the one used in tg_resolve_events.
unix% punlearn acis_process_events unix% pset acis_process_events infile=acis_16596_tmp_evt1a.fits unix% pset acis_process_events outfile=acis_16596_tmp2_evt1a.fits unix% pset acis_process_events mtlfile=acisf16596_000N003_mtl1.fits unix% pset acis_process_events badpixfile=none unix% pset acis_process_events acaofffile=@pcad_asol1.lis unix% pset acis_process_events eventdef=")ccgrdlev1a" unix% acis_process_events Input event file or stack (acis_16596_tmp_evt1a.fits): Output event file name (acis_16596_tmp2_evt1a.fits): aspect offset file ( NONE | none | <filename>) (@pcad_asol1.lis):
The contents of the parameter file may be checked using plist acis_process_events.
We can check that the badpixel and streak events are still identified by checking the status bits in the output file
unix% summarize_status_bits acis_16596_tmp2_evt1a.fits BitName Bit NumEvt %Evt BitDesc ------- --- ------ ---- ------- BADPIX 4 108953 5.6 Center of event island falls on bad pixel BADPIXE 5 105107 5.4 Surrounding event island falls on bad pixel DESTREAK 15 28954 1.5 Horizontal streak identified by destreak tool
5. Run tg_resolve_events: Final Pass
For the second and final pass, the re-calibrated event file is used with tg_resolve_events. The same eventdef is used as before, but now the default, CALDB, order sorting table is used.
unix% punlearn tg_resolve_events unix% pset tg_resolve_events infile=acis_16596_tmp2_evt1a.fits unix% pset tg_resolve_events outfile=acis_16596_evt1a.fits unix% pset tg_resolve_events regionfile=acis_16596_msk1a.fits unix% pset tg_resolve_events acaofffile=@pcad_asol1.lis unix% pset tg_resolve_events eventdef=")ccgrdlev1a" unix% pset tg_resolve_events osipfile="CALDB" unix% tg_resolve_events Input event file (acis_16596_tmp2_evt1a.fits): Input region file (acis_16596_msk1a.fits): Output event file (acis_16596_evt1a.fits): Input aspect offset file (@pcad_asol1.lis):
The contents of the parameter file may be checked using tg_resolve_events.
Generate a New Level=2 Event File
1. Apply grade/status filters (dmcopy)
Filter for bad grades and for a "clean" status column (i.e. all bits set to 0):
unix% punlearn dmcopy unix% dmcopy "acis_16596_evt1a.fits[EVENTS][grade=0,2,3,4,6,status=0]" \ acis_16596_flt1_evt1a.fits unix% dmappend "acis_16596_evt1a.fits[region][subspace -time]" acis_16596_flt1_evt1a.fits
2. Apply GTI filters (dmcopy)
The Good Time Intervals (GTIs) supplied by the pipeline now need to be applied. We simultaneously eliminate an unnecessary column from the output:
unix% punlearn dmcopy
unix% dmcopy \
"acis_16596_flt1_evt1a.fits[EVENTS][@acisf16596_000N003_flt1.fits][cols -phas]" \
acis_16596_evt2.fits opt=""
unix% dmappend \
"acis_16596_flt1_evt1a.fits[region][subspace -time]" \
acis_16596_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.
There are a few observations where ACIS begins to collect event data before the aspect solution is available. Under some rare circumstances these events are not removed by the GTI filter which results in the first few events in the Level 2 event file to contain invalid sky coords (beyond the 1 to 8192 range). These events can be removed with the following dmcopy command:
unix% dmcopy "acis_repro_evt2.fits[EVENTS][x=:,y=:]" acis_filter_xy_repro_evt2.fits
Users do not generally need to worry about these invalid event unless they are merging observations.
Users at this stage may wish to apply other filters via additional dmcopy calls. For example, this would be the appropriate point to apply a time filter to the data.
Extract a Grating Spectrum (tgextract)
The CIAO tool tgextract produces a PHA2 spectrum file from the level=2 event file:
unix% punlearn tgextract unix% pset tgextract infile=acis_16596_evt2.fits unix% pset tgextract outfile=acis_16596_pha2.fits unix% tgextract Input event file (output event file from L1.5 processing) (acis_16596_evt2.fits): If typeII, enter full output file name or '.'; if typeI, enter output rootname (acis_16596_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): Output 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.
Summary
This thread is complete; the PHA2 grating spectrum file is named acis_16596_pha2.fits. You should now proceed to the ACIS-S Grating RMFs thread.
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.
Parameters for /home/username/cxcds_param/tgdetect2.par
infile = acisf16596_000N002_evt1.fits Input event file
outfile = acis_16596_src1a.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))
(unlearn_tgdetect = yes) yes = punlearn tgdetect to set all its parameters to defaults
(unlearn_tg_findzo = yes) yes = punlearn tg_findzo to set all its parameters to defaults
(temproot = ) Path and root file name to be given to temporary files
(keepexit = no) Keep exit status file?
(clobber = no) OK to overwrite existing output file?
(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 = acisf16596_000N002_evt1.fits Input event file or stack
outfile = acis_16596_msk1a.fits Output region file or stack
input_pos_tab = acis_16596_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 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)
Parameters for /home/username/cxcds_param/tg_resolve_events_firstpass.par
#--------------------------------------------------------------------------
#
# tg_resolve_events.par: Parameter file for the tg_resolve_events program
#
#--------------------------------------------------------------------------
#
infile = acisf16596_000N002_evt1.fits Input event file
outfile = acis_16596_tmp_evt1a.fits Output event file
regionfile = acis_16596_msk1a.fits Input region file
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)
#
# osort_hi and 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) pixel randomization width (-size..+size), 0.0 = no randomization
# --------------------------------------------------------------------------
(eventdef = )ccgrdlev1a -> {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,f:rd,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,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,f:rd,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
#
(cclev1a = {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,s:phas,l:pha,l:pha_ro,f:energy,l:pi,s:fltgrade,s:grade,f:rd,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}) Lev1.5 CC faint event format definition string
#
(ccgrdlev1a = {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,f:rd,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}) lev1.5 cc graded 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/acis_process_events.par
#--------------------------------------------------------------------------
#
# acis_process_events.par- Parameter file for acis_process_events program
#
#--------------------------------------------------------------------------
infile = acis_16596_tmp_evt1a.fits Input event file or stack
outfile = acis_16596_tmp2_evt1a.fits Output event file name
acaofffile = @pcad_asol1.lis aspect offset file ( NONE | none | <filename>)
(apply_cti = yes) Apply CTI adjustment?
(apply_tgain = yes) Apply time-dependent gain adjustment?
(alignmentfile = )acaofffile -> @pcad_asol1.lis) sim/fam alignment file ( NONE | none | <filename>)
(obsfile = NONE) obs.par file for output file keywords ( NONE | none | <filename>)
(geompar = geom) Parameter file for Pixlib Geometry files
(logfile = stdout) debug log file ( STDOUT | stdout | <filename>)
(gradefile = CALDB) grade mapping file ( NONE | none | CALDB | <filename>)
(grade_image_file = CALDB) grade image file for cti correcting graded mode ( NONE | none | CALDB | <filename>)
(gainfile = CALDB) acis gain file ( NONE | none | CALDB | <filename>)
(badpixfile = none) acis bad pixel file ( NONE | none | <filename>)
(threshfile = CALDB) split threshold file ( NONE | none | CALDB | <filename>)
(ctifile = CALDB) acis CTI file ( NONE | none | CALDB | <filename>)
(tgainfile = CALDB) gain adjustment file ( NONE | none | CALDB | <filename>)
(mtlfile = acisf16596_000N002_mtl1.fits) Mission time line file with FP_TEMP data
(eventdef = )ccgrdlev1a -> {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,f:rd,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}) output format definition
(doevtgrade = yes) Determine event flight grade?
(check_vf_pha = no) Check very faint pixels?
(trail = 0.027) Trail fraction
(time_offset = 0) Offset to add to event time field to synch w/ fam data
(calculate_pi = yes) perform pha->pi conversion? (requires gain file)
(pi_bin_width = 14.6) Width of Pi bin in eV
(pi_num_bins = 1024) Number of values to bin energy into
(max_cti_iter = 15) Maximum iterations for the CTI adjustment of each event
(cti_converge = 0.1) The convergence criterion for each CTI-adjusted pixel in adu
(tstart = TSTART) header key containing start/default time value
(tstop = TSTOP) header key containing time of last event
(clobber = no) Overwrite output event file if it already exists?
(verbose = 0) level of debug detail (0=none, 5=most)
(stop = sky) where to end transformations
(instrume = acis) axaf instrument- used for instrument parameter file
(rand_seed = 1) random seed (for pixlib), 0 = use time dependent seed
(rand_pha = yes) Randomize the pha value used in gain calculations
(pix_adj = EDSER) Sub-pixel adjustment algorithm
(subpixfile = CALDB) Name of input sub-pixel calibration file
(stdlev1 = {d:time,l:expno,s:ccd_id,s:node_id,s:chip,s:tdet,f:det,f:sky,s:phas,l:pha,l:pha_ro,f:energy,l:pi,s:fltgrade,s:grade,x:status}) TE faint modes event definition string
(grdlev1 = {d:time,l:expno,s:ccd_id,s:node_id,s:chip,s:tdet,f:det,f:sky,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,x:status}) TE graded event format definition string
(cclev1 = {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,s:tdet,f:det,f:sky,f:sky_1d,s:phas,l:pha,l:pha_ro,f:energy,l:pi,s:fltgrade,s:grade,x:status}) CC faint event format definition string
(ccgrdlev1 = {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,s:tdet,f:det,f:sky,f:sky_1d,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,x:status}) cc graded event format definition string
(cclev1a = {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,s:phas,l:pha,l:pha_ro,f:energy,l:pi,s:fltgrade,s:grade,f:rd,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}) Lev1.5 CC faint event format definition string
(ccgrdlev1a = {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,f:rd,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}) lev1.5 cc graded event format definition string
(mode = ql)
Parameters for /home/username/cxcds_param/tg_resolve_events_secondpass.par
#--------------------------------------------------------------------------
#
# tg_resolve_events.par: Parameter file for the tg_resolve_events program
#
#--------------------------------------------------------------------------
#
infile = acis_16596_tmp2_evt1a.fits Input event file
outfile = acis_16596_evt1a.fits Output event file
regionfile = acis_16596_msk1a.fits Input region file
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 = CALDB) Lookup table for order resolving (for acis data only)
#
# osort_hi and 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) pixel randomization width (-size..+size), 0.0 = no randomization
# --------------------------------------------------------------------------
(eventdef = )ccgrdlev1a -> {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,f:rd,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,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,f:rd,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
#
(cclev1a = {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,s:phas,l:pha,l:pha_ro,f:energy,l:pi,s:fltgrade,s:grade,f:rd,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}) Lev1.5 CC faint event format definition string
#
(ccgrdlev1a = {d:time,d:time_ro,l:expno,s:ccd_id,s:node_id,s:chip,f:chipy_tg,f:chipy_zo,s:tdet,f:det,f:sky,f:sky_1d,l:pha,l:pha_ro,s:corn_pha,f:energy,l:pi,s:fltgrade,s:grade,f:rd,s:tg_m,f:tg_lam,f:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap,x:status}) lev1.5 cc graded 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 = acis_16596_evt2.fits Input event file (output event file from L1.5 processing)
outfile = acis_16596_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 Output 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
| 10 Dec 2015 | The ACIS/HETG thread has been split into separate threads: one for TIMED exposure mode data, and this one for data taken in Continuous clocking mode. In CIAO 4.8 the tools can now use the estimated CHIPY location determined by zeroth order location together with the known grating dispersion geometry to better calibrate the events energies. This leads to an iterative approach where users run tg_resolve_events once to get the chipy location, followed by acis_process_events to update the energy calibrations, followed by a final run of tg_resolve_events for the final energy/order determination. |
| 02 Dec 2020 | Replace dmcopy opt=all with dmappend to copy the [REGION] block. |
| 08 Feb 2022 | Review for CIAO 4.14. Updated for Repro-5/CALDB 4.9.6. |