tgextract2

Synopsis

Bin event list grating wavelengths column into a one-dimensional counts histogram, by source, grating part, and diffraction order. Optionally bin background spectrum.

tgextract2 infile outfile tg_srcid_list tg_part_list tg_order_list
[opt] [wav_grid] [wav_grid_heg] [wav_grid_meg] [wav_grid_leg]
[wav_grid_leg_acis] [evt_filter] [ignore_source_id] [error]
[region_file] [geompar] [min_tg_d] [max_tg_d] [min_upbkg_tg_d]
[max_upbkg_tg_d] [min_downbkg_tg_d] [max_downbkg_tg_d]
[extract_background] [backscale_method] [backscale_resolution]
[clobber] [verbose]

Description

"tgextract2" is similar to "tgextract" but provides more flexibility to specify complex background regions, for example when another source is found on one side of the relatively wide background region typically used in LEGT/HRC-S observations. In those rare cases, the background region may have to be manually adjusted, which requires the use of "tgextract2"; in most cases spectra can be extracted with "tgextract".

"tgextract2" filters and bins a grating event file (as output by "tg_resolve_events") into a one-dimensional counts spectrum for each grating part, order, and source, as appropriate. The grating event file contains columns labeling these attributes (tg_part, tg_srcid, tg_m) and the event diffraction coordinates (tg_lam, tg_mlam, tg_r, tg_d; see "ahelp tg_resolve_events") in a spatial region many PSFs wide. "tgextract2" bins from a narrow source region in the cross-dispersion direction (either rectangular or via a region file as specified by parameters), and also bins background arrays from wide regions adjacent to the source region.

Binning regions may be specified with parameters or with a region file which specifies polygons. If the former, only simple rectangular regions are supported. If the latter, regions can be simple polygons (not self intersecting). The background scaling values will be computed as an array, and can be optionally computed from the region, or from the events, which can be necessary if the region extends beyond the edge of the detector array. To aid the mode in using events to determine the intersection of the region and detector, unfiltered events should be input so that the counting statistics are better; an output filter parameter is then necessary in order to bin only the good events. The region-file interface can be useful for geometrically complicated fields in which there are multiple sources which add confusion to the background of the source of interest.

The background arrays should be thought of as "related to the background". Background rejection is high for a grating and ACIS. Some proportion of the pseudo-background is due to faint wings of the LSF, and for ACIS, to the frame-shift streak (aliasing of charge in chipy in an amount given by the ratio of the frame-shift-time to the frame-time, or roughly 0.041s/3.200s=0.0128, for nominal timed exposure). Background for HRC will be higher because there is no order-sorting possible via the detector intrinsic energy resolution.

Default output is a "PHA Type II" file, with some CXC addition of columns. This is a standard FITS format in which each row contains array columns. In this case, each row is a unique grating part, source (if multiple), and order. Type I PHA files are also supported via a parameter switch. Both formats are compatible with existing analysis software (in particular with xspec and ftools) while providing convenient or necessary extensions.

Note: "tgextract2" bins the real-valued diffraction coordinate lists, not detector pixels. Due to aspect dither and instrument module flexure, many detector pixel locations (roughly, a 16x16 arcsec detector region) map to one diffraction coordinate (though at different times).

The default units are Angstroms, since the grating dispersion is linear in wavelength. Default bin order is in ascending energy (decreasing wavelength) for compatibility with xspec and conformance with FITS spectral file format specifications.

The cross-dispersion coordinates are specified in "grating" angles. That is, using the Rowland spacing as the focal length. The dimensions can be found in the Calibration Database "geom" file (e.g., telD1999-07-23geomN0004.fits), as header keywords or tabulated values. For reference, the current Rowland spacings are 8632.48 mm (HETG) and 8637.0 mm (LETG); ACIS pixels are 0.023987 mm square, HRC-S are 0.0064294 mm. This yields grating angular scales of 0.5731 arcsec/pix (1.592e-04 deg/pix; HETG/ACIS-S), 0.1535 arcsec/pix (4.265e-05 deg/pix; LETG/HRC-S), and 0.5728 arcsec/pix (1.591e-04 deg/pix; LETG/ACIS-S).

RESTRICTIONS: The Type II PHA file format is limited to having spectral arrays on each row of the same length. For example, if the MEG spectrum has 8192 bins, starts at 1A, with bin size of 0.005A, then the HEG rows must have 8192 bins. If the HEG were also binned at 0.005A (2*default), then the output array would have to extend for 8192 bins to about 40A, whereas the physical detector edge occurs at about 20A.

The binning regions are appended to the output as a FITS binary table of type, REGION. If a region file is used, it's "x"-coordinates will be transformed from dispersion angle to wavelength.

USER ADVISORY: the source binning region can be adjusted arbitrarily. However, this can affect the effective area and line-spread-function (LSF) by clipping the spatial distribution. A detector pulse-height clipping of orders has already been imposed and cannot be altered by this tool (see "ahelp tg_resolve_events" and "ahelp mkgarf"). The cross-dispersion affect on effective area can be accounted for by mkgrmf IF the source region is symmetric about the centerline of the spectrum.

Examples

Example 1

tgextract2 acis_hetg_evt2.fits acis_hetg_pha2.fits tg_order_list="-1,1"

Generate a pha2 file, acis_hetg_pha2.fits, from acis_hetg_evt2.fits which contains HETG data (that is both MEG and HEG data), for orders -1 and +1. Other parameters are left to the defaults.

Example 2

tgextract2 hrcs_letg_evt2.fits hrcs_letg_pha2 opt=pha1
region_file=letgD1999-07-22regN0001.fits wav_grid=use_header
wav_grid_leg=1.0:205.80:0.1

Generate two pha1 files, from input file hrc_letg_evt2.fits for "orders" -1 and +1 (HRC-S cannot resolve orders; -1 and 1 refer to the total of negative or positive side counts, respectively). Use the LETG/HRC-S "bow-tie" region file as a spatial filter (region_file) for background reduction (this is in the Calibration Database and is the default for pipeline processing). Set the binning to be 8 times the default (0.0125 angstrom/bin, 16384 bins).

Example 3

tgextract2 infile=Evt/acisfnnnn_N001_evt2.fits.gz outfile=tst_any
opt=pha1 tg_srcid_list=1 tg_part_list="HETG" tg_order_list="-1,1"
wav_grid=1.0:41.96:0.04 extract_background=no

Extract pha1 files from a compressed Level 2 event list, only orders -1 and +1. Bin MEG and HEG to the same coarse grid (defaults are 0.005 for MEG and 0.0025 for HEG). Four files are written, with root name "tst_any", and full names:

• tst_any01Hm1_pha2.fits
• tst_any01Hp1_pha2.fits
• tst_any01Mm1_pha2.fits
• tst_any01Mp1_pha2.fits

(In the output file name, "01" refers to source id number; "H" and "M" refer to HEG or MEG, and "m" and "p" refer to minus or plus side orders; "pha" refers to a file format specification, and the "2" refers to "Level 2" data.)

Example 4

tgextract2 infile=evt1a.fits outfile=pha2.fits
evt_filter="status=0,grade=0,2,3,4,6,energy<12000"
backscale_method=events region_file=my_region.fits
tg_order_list="-3,-2,-1,1,2,3"

Use a custom region file and determine the backscale from the background geometrical boundary determined by the intersection of the region and teh events. Since we are using unfiltered "Level 1.5" events to improve statistics of the border determination, specify a standard event filter to be applied before binning the spectra.

Example 5

tgextract2 infile=evt2.fits outfile=pha2.fits backscale_method=region
tg_order_list="-1,1" min_tg_d=-6.6e-4 max_tg_d=6.6e-4
extract_background=yes min_upbkg_tg_d=1.e-3 max_upbkg_tgd=7.e-3
max_downbkg_tg_d=-2.e-3 min_down_bkg_tg_d=-8.e-3

Use rectangular source and background regions, but offset the background region on the "down" (tg_d<0 ) side.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=no)

Name of Input event file.

e.g. acisf00001_N0001_evt1a.fits, or hrcf00001_N0002_evt1a.fits.gz.

The file must contains an EVENTS extension which contains the diffraction coordinate columns to be filtered and binned. These coordinates are written by "tg_resolve_events": The diffraction coordinate columns of the event file are:

• TG_M
• TG_LAM
• TG_MLAM
• TG_SRCID
• TG_PART
• TG_SMAP

The input file must also have sky REGION extension which defines the source list (not the diffraction coordinate binning region). The source numbers and zero-order coordinates are copied to an output diffraction coordinates REGION extension.

See "ahelp tg_resolve_events" for details of the file contents.

Parameter=outfile (file required filetype=output autoname=yes)

Output file name or template.

If "opt=pha2", this is either the literal output file name or ".". If ".", the input file name is used as a template to create the output name. For example, if "infile=root_evt2.fits", then outfile will be "root_pha2.fits".

If "opt=pha1", the name is used as the root name of the output files which will be named as: "root<srcid><part><order>_pha2.fits". As many files as there are source IDs, parts, and orders will be created.

If the output name is given as ".", the input file name is used to create the output file. For example, infile=root_extension.fits the output file name will be "root<srcid><part><order>_pha2.fits".

Columns written to the spectrum are

• SPEC_NUM (Type II only)
• TG_SRCID (Type II only) from tgdetect
• TG_PART (Type II only) 0: zero order; 1:HEG; 2:MEG; 3:LEG; 99: background
• TG_M (Type II only) diffraction order
• X (Type II only) zero order centroid sky X; from tgdetect
• Y (TYpe II only) zero order centroid sky Y; from tgdetect
• CHANNEL bin number
• BIN_LO wavelength, low bin edge
• BIN_HI wavelength, high bin edge
• COUNTS spectrum counts
• BACKSCAL scale factor for source region, which is the cross-dispersion (tg_d) width of source region in degrees
• BG_COUNTS background counts, if extracted
• BG_AREA background scale factor; degrees in tg_d for combined background "up" and "down" sides
• STAT_ERR source statistical error (only if error=gehrels)
• BG_ERR background statistical error (only if error=gehrels)

For Type I PHA output, the "Type II only" fields are written to the header. The remaining fields are array columns in Type II PHA output. The binned spectral source and background columns are consistent with dmextract spectral columns names.

Columns written to the region extension are:

• SPEC_NUM spectrum number, which points to the spectrum row
• ROWID Source or background region identifier
• SHAPE Shape of region, such as POLYGON
• TG_LAM x-coordinates for SHAPE [Angstroms], such as POLYGON vertices
• TG_D y-coordinates for SHAPE [deg], such as POLYGON vertices
• R Generalized "radii" of shape
• ROTANG Rotation angle of shape
• TG_SRCID Source identification number from tgdetect
• TG_PART 1:HEG; 2:MEG; 3:LEG;
• TG_M diffraction order
• COMPONENT index for region item

Parameter=tg_srcid_list (string required default=1 stacks=yes)

The list of sources to process. ("all"|string|@file)

"all", blank or none will process all the source id's present in the input REGION extension.

A "comma list" is a comma separated string list of source id's the user wants to process, eg: "1,2,3".

"@file" is a pointer to an ASCII file which contains source id's to process. Limit one source id per line and no "comma list" is allowed in @file.

Parameter=tg_part_list (string required default=header_value)

Grating parts to process: (HETG|HEG|MEG|LETG|header_value). The HETG has types of grating elements which produce spatially separated diffracted photon regions, either or both of which may be processed. The default is "header_value", which uses the input file's GRATING header keyword value, which is either "HETG" or "LETG" (or "NONE", but that is not a valid option).

Parameter=tg_order_list (string required default=default stacks=yes)

Grating diffraction orders to process: ("default"|comma list|range list|@file)

"default", blank or none will 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, eg. "-5, -1, 1, 3".

A range list (min..max) will process all the orders between the minimal and maximal values except 0th order. eg. "-1..5" will process orders from -1 to +5th order (excluding 0). A "range list" can be mixed with "comma list", e.g. "1,2,3,4..6".

"@file" is a pointer to an ASCII file which contains the orders to process. Limit one order per line or one range list per line in the file. And no "comma list" is allowed in @file.

Parameter=opt (string default=pha2)

Ouput file type: "PHA Type I" or "PHA Type II" (default). Both type of files contain a SPECTRUM extension and a REGION extension. Each file contains the same information. The Type II PHA file type format has a row for each order and grating part, and the row contains both scalar and array columns. The Type I PHA file type format does not have array columns; the arrays become columns, and the scalar Type II PHA's columns become header keywords.

Parameter=wav_grid (string default=use_header)

"use_hedaer" or an explicit grid specification given as min:max:step, or min:max:#bins.

If wav_grid="use_header", tgextract2 uses the value of the parameter

"wav_grid_heg" as HEG grid,
"wav_grid_meg" as MEG grid,
"wav_grid_leg" as LETG/HRC grid, and
"wav_grid_leg_acis" as LETG/ACIS grid.

Parameter=wav_grid_heg (string default=1.0:21.48:0.0025)

pre-defined standard HEG grid given as min:max:step, or min:max:#bins.

Parameter=wav_grid_meg (string default=1.0:41.96:0.0050)

pre-defined standard MEG grid given as min:max:step, or min:max:#bins.

Parameter=wav_grid_leg (string default=1.0:205.80:0.0125)

pre-defined standard LETG grid given as min:max:step, or min:max:#bins.

Parameter=wav_grid_leg_acis (string default=1.0:103.4:0.0125)

pre-defined standard LETG/ACIS grid given as min:max:step, or min:max:#bins.

Parameter=evt_filter (string default=none)

Filter to apply to events before binning into counts spectra. for example: "grade=0,2,3,status=0" or "[grade=0,2,3,status=0]" This is needed if unfiltered events are used to facilitate the use of events in implicit background region edge determination (see the backscale_method parameter).

Parameter=ignore_source_id (boolean default=yes)

match source id between input event file and region_file. If ignore_src_id="yes", then the first region found is used for all sources given by parameter "tg_srcid_list", regardless of the region file's tg_srcid. For multi-source regions, "no" will make sure each source and region ID match.

Parameter=error (string default=gaussian)

Method for error determination (gaussian|gehrels). For gaussian, set the POISSERR keyword to TRUE and omit the STAT_ERR columns. Otherwise, compute statical errors and set POISSERR to FALSE.

Parameter=region_file (file filetype=ARD default=CALDB)

Spatial filter FITS region file. This may be "none", in which case the rectangular binning region parameters are used.

Users can specify "CALDB" to automatically look up the appropriate region file for the data.

NOTE: this file is NOT the same as the grating mask file produced by the tg_create_mask tool; it must be in diffraction coordinates, whereas the other is in sky coordinates.

This file allows binning from other than rectangular spatial regions. This is especially important for HRC-S/LETG, which has high astigmatism which makes the spectrum more "bow-tie" shaped. Following this shape when binning reduces background in the low-wavelength region. (This is the default for pipeline processing.)

CAUTION must be taken with any custom regions, since they could affect the effective area by clipping the cross-dispersion profile. Spatial clipping factors are accomodated by the grating response matrix function utilities (see "ahelp mkgrmf").

The input region file should contain the following columns:

• ROWID String representation of the region. The 3 possible values are SOURCE, BACKGROUND_UP and BACKGROUND_DOWN.
• SHAPE Specifies the geometrical shape of the region. The default use polygon (even for simple rectangles).
• TG_R [deg] x (dispersion) coordinate of polygon;
• TG_D [deg] y (cross-dispersion) coordinate of polygon;
• R generalize radii; This column is needed for regions that require a radius parameter in their definition.
• ROTANG [deg] rotation angle for rotated region;
• TG_PART Numerical representation of the grating part. 1 stands for HEG, 2 stands for MEG and 3 stands for LEG.
• TG_SRCID Specifies the source to which the region pertains.
• TG_M Specifies what diffraction order sign that the region refers to. Region with TG_M=1 will be used to filter events that have positive diffraction order, while region with TG_M=-1 will be used to filter events that have negative diffraction order.
• COMPONENT running index

Parameter=geompar (file default=geom)

The name of the Pixlib Geometry parameter file.

Parameter=min_tg_d (string default=default units=degrees)

The minimum tg_d value to include in the source spectrum. ["default"|real number]

Defaults:

• HETG: -0.1 mm = -2.39 arcsec = -6.6E-04 degrees
• LETG: -0.3 mm = -7.19 arcsec = -2.00E-03 degrees

If the source region(s) is given in the input region file (region_file), the min_tg_d parameter will be ignored.

Parameter=max_tg_d (string default=default units=degrees)

The maximum tg_d value to include in the source spectrum. ["default"|real number]

Defaults:

• HETG: +0.1 mm = 2.39 arcsec = 6.6E-04 degrees
• LETG: +0.3 mm = 7.19 arcsec = 2.00E-03 degrees

Note that if source region(s) is given in the input region file (region_file), the max_tg_d parameter will be ignored.

Parameter=extract_background (boolean default=yes)

Indicate whether to bin a local background spectrum.

If set to "yes", events with cross-dispersion from the BACKGROUND_UP region that lies above (positive tg_d) the source region will be binned and summed with events binned from the BACKGROUND_DOWN component (negative tg_d). If no background regions are given in the input region file (region_file) or if there is no input region file, the min_upbkg_tg_d and max_upbkg_tg_d parameters are used to determine the size of the background_up region, and the min_downbkg_tg_d and max_downbkg_tg_d parameters are used to determine the size of the background_down region.

Parameter=min_upbkg_tg_d (string default=default units=degrees)

Specifies the minimum tg_d value to include in the background_up spectrum. ["default"|real number]

If min_upbkg_tg_d is set to default, the same value for max_tg_d will be used for min_upbkg_tg_d.

Note that if background_up region(s) is given in the input region file (region_file), the min_upbkg_tg_d parameter will be ignored.

Parameter=max_upbkg_tg_d (string default=default units=degrees)

Specifies the maximum tg_d value to include in the background_up spectrum. ["default"|real number]

Defaults:

• HETG: 1.0 mm = 23.9 arcsec = 6.6E-03 degrees
• LETGS: 2.0 mm = 47.8 arcsec = 1.33E-02 degrees

Note that if background_up region(s) is given in the input region file (region_file), the max_upbkg_tg_d parameter will be ignored.

Parameter=min_downbkg_tg_d (string default=default units=degrees)

Specifies the minimum tg_d value to include in the background_down spectrum. ["default"|real number]

Defaults:

• HETG: -1.0 mm = -23.9 arcsec = -6.6E-03 degrees
• LETGS: -2.0 mm = -47.8 arcsec = -1.33E-02 degrees

Note that if background_down region(s) is given in the input region file (region_file), the min_downbkg_tg_d parameter will be ignored.

Parameter=max_downbkg_tg_d (string default=default units=degrees)

Specifies the maximum tg_d value to include in the background_down spectrum. ["default"|real number]

If max_downbkg_tg_d is set to default, the same value for min_tg_d will be used for max_downbkg_tg_d.

Parameter=backscale_method (string default=events)

If "events", use events and region together to determine the background region boundary and compute BG_AREA ("backscale") from this. It is possible that the region, for large regions, will be truncated by the detector edge. Hence, this will give a more accurate background scaling factor. To improve statistics, even bad events can be used to simply mark the detector region implicitly. If unfiltered events are input, then an event fileter should be applied on the output before binning (see the evt_filter parameter). If "region", then compute the BG_AREA from the region (or equivalent parameters defining binning regions).

Parameter=backscale_resolution (integer default=64)

Amount in pixels (as implied by wav_grid) to bin in wavelength to improve statistics in determination of background backscale from events. This is for use in conjunction with backscale_method=events, to provide better statistics per dispersion bin in determining the boundary of the region implicitly.

Parameter=clobber (boolean default=no)

If "yes", then any existing output files will be over-written.

Parameter=verbose (integer default=0 min=0 max=5)

Program verbosity, 0 (least) to 5 (most).

Bugs

There are no known bugs for this tool.

See Also

chandra

eventdef

dm

dmbinning

tools::composite

combine_grating_spectra

tools::core

dmcopy, dmextract

tools::gratings

detilt, dewiggle, symmetrize, tg_bkg, tg_choose_method, tg_create_mask, tg_findzo, tg_resolve_events, tgdetect, tgdetect2, tgextract, tgidselectsrc, tgmask2reg, tgmatchsrc, tgsplit

tools::image

dmfilth, dmimghist, dmregrid

tools::response

mktgresp

tools::table

dmgroup, dmtype2split

tools::utilities

apply_fov_limits, get_fov_limits, get_sky_limits