AXAF Grating Level 1.5, Level 2 Processing

AXAF Transmission Grating Data Processing How-To Guide
(Level 1.5, Level 2)



Processing Overview

This guide is intended to give a brief tutorial on processing MARX output with the ASCDS components which transform coordinates into wavelengths and orders (if ACIS is used with a grating), and then into binned 1D spectra. I will give brief descriptions of the steps, and refer to detailed documentation for further information.

This is NOT a reference manual or a user manual! It is intended for the motivated (or desperate) user who has grating data files to analyze - in particular, marx simulations.

The steps are these:

  1. marx: create simulated data.

  2. marx2fits: convert the MARX output vector files into a FITS bintable, which is nearly an AXAF Level 1 event-list.

  3. acis_process_events: convert detector coordinates to sky coordinates, and -- if ACIS -- convert PHA to PI and linearized energy. The new quantities are added as columns in the output event-list, which is now really Level 1.
    (Level 1)

  4. tgdetect: detect the zero-orders and create a table holding the zero-order centroids.
    (Level 1.5)

  5. tg_create_mask: Use the zero-order centroids (in sky coordinates) to define spatial regions for each part of the spectrum (zero-order, diffracted orders, background) and each source (if multiple), and write a region file. The region file (or mask) is used in the next step for filtering events and applying coordinate transformations.
    (Level 1.5)

  6. tg_resolve_events: filter events, using the mask, and convert to wavelength coordinates. The aspect solution is inverted to determine the instantaneous zero-order centroid in detector coordinates. Coordinate columns are added to the event-file. If ACIS, orders are resolved using an energy-limit table constructed from the CCD response.
    (Level 1.5)

  7. tgextract: bin the events into 1D spectra, writing to a Type II PHA file.
    (Level 2)

  8. specdetect: automatic detection of strong, isolated features.
    (Level 2)

  9. specmeasure: automatic measurement of detected strong, isolated features
    (Level 2)

  10. specidentify: automatic tentatitive identification of features.
    (Level 2)

Steps 1 and 2 may be done almost anywhere. MARX and marx2fits are fully documented in the MARX User Guide. They will not be discussed further here.

Step 3 is under development. For now, source detection will have to be done manually. This is not difficult. The required quantity is a real-valued zero-order centroid in sky tangent-plane pixel coordinates. This can be measured from the product of step 3, and then entered into FITS table by using the ftool, fcalc (or any other FITS file editor), on a default table (see below).

Steps 5-10 exist in the released system (as per "ASC Data System, version: R4C2.0 Monday, September 28, 1998").

Nota bene: The inverse aspect solution has not been tested with gratings! In principle, one may run marx with an input aspect "truth file" (the a priori known aspect), then run tg_resolve_events with the corresponding aspect offsets file, and obtain properly de-aspected diffraction coordinates. (The aspect solution has been tested without gratings.)



Environment and Configuration

Currently (98 Nov 13), the ASCDS tools will only run on the CfA ASC HEAD network (certain hosts within the domain ".harvard.edu"; try "ceili"). You will need to configure your environment to access the ASCDS released version of the software. Try the following links for information (moving from the bottom of the tree upwards):

Briefly, copy the .ascrc and .ascrcuser files from ~ascds/DS.release/config/system to your home directory (or location of your choice). Then "source" the former (which sources the latter from the same directory), and your environment will be properly configured. Any local changes get made in .ascrcuser.

Once configured, help may be obtained via the command, "ahelp command", for the ASCDS tools (e.g., ahelp tg_create_mask). Most tools are controlled by parameter files. These may be seen by using the "plist" command (e.g., plist tg_resolve_events).

To report problems with the configuraton, please email ascdshelp@head-cfa.harvard.edu.





Wrapping it Up

I have written some shell-scripts to facilitate running the tools required to go from marx output to Level 1.5 and Level 2, since there is header-patchwork required, and a number of parameters to be set. Eventually, these operations will be handled by ASCDS infrastructure, which will populate headers and parameter files properly with a description of the observational configuration.

The script, hetgs, is a Bourne shell script which runs three other scripts: acis_L1 for Level 1 processing, hetgs_L15, which does the Level 1.5 processing, and hetgs_L2, which bins the spectrum.

Legalistic weasel-words: These are not robust scripts --- they do little error-checking, and much of their function is expected to become obsolete as ASCDS infrastructure grows. They may work as is, but should generally be considered as a guide to running the Level 1, Level 1.5, and Level 2 tools. So consider yourself warned! (And look at the scripts to see how their parameters are set.)

These scripts are also only appropriate for HETGS (ACIS-S/HETG) simulations (The analogous LETGS scripts are currently under development.)

The Level 2 script (hetgs_L2, which runs tgextract) has only been configured to process a single source. It is not hard to run explicitly to specify multiple sources, if present.

Usage

Level 1.5 Event Processing and Binning

Assume that your input file (output by marx2fits) is called AS_004.fits, and that it resides in a directory named ./Test. Copy the scripts to this directory. Make a subdirectory called RefData and put the required reference data files in it (see below). Then you can run the scripts as follows:

All-in-one command:
hetgs AS_004.fits
Or, explicitly do all that the hetgs script does:
acis_L1 AS_004.fits
hetgs_L15 AS_004.fits
hetgs_L2 AS_004.fits

Automatic Line-Detection, Identification, and Measurement

The released versions of these tools use ASCII table input. The binned spectrum will have to be dumped into an appropriately formatted table. The next release will directly read the Type II PHA file as output from tgextract.
specdetect TBD
specmeasure TBD
specidentify TBD

Reference Data and Input Files Required

  • acis_L1
    • Input events; e.g., AS_004.fits, which must be the marx2fits output file (the marx.par extension is required).
    • CCD Gain Table: ACIS CCD gain FITS bintable. This must be consistent with the MARX CCD model. For MARX 2.tbs, use ACIS_gain_marx.fits.
    • Header-modification tables: These files are required in order to add information to the event-file header as expected by the tools. (Future versions of marx2fits may provide these automatically.)

  • hetgs_L15
    • The marx2fits output, which is used to read the marx.par file from a FITS extension. E.g. AS_004.fits.
    • Input events file, whose name is generated from the command argument by appending "_L1" to the rootname. E.g, AS_004_L1.fits.
    • mh_aciss_sim.tbl: A header-modificaton template. This puts the proper SIM position in the table. (It should come from the MARX parameter file.)
    • Src_Onaxis.fits: The zero-order source centroid table for tg_create_mask. The sample table contains one source, for the on-axis aim-point for ACIS-S. Other source positions may be realized by using fcalc (for example) to edit the FITS table. This will eventually be produced by the tgdetect tool.
    • psf_fwhm.fits: This is Analysis Reference Data for Level 1.5. It is a table which contains the approximate zero-order size (FWHM) versus off-axis angle. This is used for region-mask sizing, via error-budget style calculations.
    • ccd_sigma.fits: This is Analysis Reference Data for Level 1.5. It is a table which contains the energy differences from the peak versus energy for some fractional enclosed probability of the CCD redistribution function. It is used for ACIS-S order-sorting in tg_resolve_events. This table defines the PI (in energy units) region which clips the orders. The version in the released system is for a single redistribution function. The next release will have the full 24-nodes of ACIS-S and accomodate both FI and BI devices. The current table is for 95% probability in a Gaussian redistribution.

  • hetgs_L2
    • A Level 1.5 event is the primary input (e.g., AS_004_L1a.fits).

    No other reference data are currently needed for single-source Level 1.5 files. For multiple sources, a source table will be needed. To produce fluxed binned spectra, we need an Auxiliary Response Function (ARF, or effective area). We don't have these at the moment, so we will only bin into counts.

  • specdetect: TBS
  • specmeasure: TBS
  • specidentify: TBS

Files Created

  • acis_L1:
    • A Level 1 event file is produced by acis_process_events, and is named by appending "_L1.fits" to the root-name. E.g, AS_004.fits will generate AS_004_L1.fits.


  • hetgs_L15
    • A Level 1.5 event file is written by tg_resolve_events. The name is derived from the root-name by appending "_L1a.fits."
    • A Level 1.5 region file is written by tg_create_mask. This file is named by taking the root and appending ".reg" (e.g., AS_004_L1.reg).

  • hetgs_L2
    • The primary output is a "Type II PHA" file, in which each row holds a spectral order and other attributes. The file is named by appending "pha2.fits" to the root-name (e.g., AS_004_pha2.fits).


  • specdetect: TBS
  • specmeasure: TBS
  • specidentify: TBS

Sample Input and Output





Help and Parameter Files

Help files may be displayed via the command, ahelp. The files reside in the directory, /home/ascds/DS.release/doc.

The plist command formats parameter files for viewing. The system parameter library is in /home/ascds/DS.release/param.

Help and parameter files needed for HETG/ACIS-S Level 1, 1.5 and Level 2 tools processing are tabulated below. Help files accessed by ahelp are given by the "Help" link. Output from plist on the HETG/ACIS-S are given by the "plist" links. The "param" links will show you the parameter file itself. Note that there are some parameter files without associated tools. These have no "Help" link in the table.
acis - param plist
acis_process_events Help param plist
grating - param plist
hetg - param plist
pix_grating - param plist
tg_create_mask Help param plist
tg_resolve_events Help param plist
tgextract Help param plist
specdetect Help param plist
specmeasure Help param plist
specidentify Help param plist




File Format References

Detailed descriptions of the input, output, and calibration files' formats may be found in the Interface Control Documents for





Credits

Tg_create_mask, tgextract, and the spec-tools were written by Anastasia Alexov. Acis_process_events and tg_resolve_events were written by Warren McLaughlin.



Known problems

  • tgextract only bins upwards, hence wavelength binning works, and tg_r positive orders works, but binning tg_r from -0.5 to 0.0, for example, fails. This has been fixed, but isn't yet in the release.
  • There is a cfitsio bug which causes some problems if there is a keyword value in scientific notation without a decimal point (e.g., "TIERRELA= 1e-09"). This causes dmmakepar to fail. A solution is to use fparkey to edit the offending keyword (in all extensions).




For further information, contact
David Huenemoerder
(617) 253-4283

Last update: 30 November 1998
4 March 98:
updated scripts for DS.release
updated refdata files for DS.release.

This page is: http://space.mit.edu/ASC/analysis/TG_HowTo.html