NAME tgextract -- Extract grating 1D spectrum(a) from an event file. USAGE tgextract [infile] [regionfile] [outfile_type] [outfile] [tg_srcid_list] [tg_part_list] [tg_order_list] [ancrfile] [respfile] [backfile=] [rowid=] [grating_par=] [bin_units=] [min_bin=] [max_bin=] [bin_size=] [num_bins=] [tg_d_units=] [min_tg_d=] [max_tg_d=] [extract_background=] [min_bkg_tg_d=] [max_bkg_tg_d=] [clobber=] [display=] DESCRIPTION Bin Level 1.5 events into counts histograms, one per each source, grating part, and order, as specified by input parameters. Calculate an uncertainty array for each spectrum. Optionally bin a background region, and also calculate its uncertainty array. Output an AXAF FITS Type II PHA spectrum file, or one or more Type I PHA files. From the binning parameters, create and write region extensions for both the source and background regions. Detailed Description: This tool should serve both the pipeline and interactive needs. For pipeline usage, certain parameter defaults will be imposed; for which some external calculations may be needed to specify the parameters. Primary function is to bin the event list into one or more 1-dimensional spectra. Each spectrum is for a given set of photon attributes: - source (if there are more than one in the file), - part of the spectrum (such as HEG, MEG, LEG, or Drake 4-7), and - diffraction orders (if ACIS is the detector). The preferred output is a Type II PHA file, in which there is a row for each attribute set, and the spectrum is an array column. For simplicity, each array quantity (the spectra) stored in a column will have the same width (i.e., number of bins per spectrum). This means that the grids are different for different orders, and also, may be truncated differently for different source positions. No checking will be done in the pipeline to avoid truncation of off-axis sources. User interactive processing will be required to recover those parts of the spectra from the Level 1.5 event list). TBR: Alternatively, a Type I PHA file may be written, in which each attribute set specifies a separate file, since the Type I specification only allows a single spectrum (plus associated uncertainty and grid arrays). The cross-dispersion region is specified by limits constant with wavelength (a rectangle), TBR: or via a table. (A table input will allow variable width with energy and order, and the advantage is for keeping approximately a constant effective area for each bin (table creation is TBD). ) Limits must be consistent with the pre-filtering mask applied in Level 1.5 processing (i.e., there won't be any photons with tg_d greater than some pre-specified amount). Background regions can be specified parallel to the spectrum or (TBD: ) via a table. For pipeline use, the backgrounds will be symmetric and have top-bottom regions combined (i.e., same absolute valued region in the cross-dispersion direction, and binned together, such as -1.0 to -0.1 mm in tg_d, and 0.1 to 1.0, binned into one background spectrum instead of two). Each extract region is specified as a FITS Region table in the REGION extension of the output pha file. In the case where the background is extract, there are a total of three region sections per spectrum: the spectrum region (SOURCE), the background region above the spectrum (BAKCGROUND_UP) and the background below the spectrum region (BACKGROUND_DOWN). PARAMETERS infile [filename] (root_evt1a.fits) Input event file (output file from L1.5 data processing). regionfile [filename] (root_reg1a.fits | none) Input FITS region file associacted with event list. This file is also created in L1.5, one for each event list. This file is used for the purpose of getting source id information, in case the tg_srcid_list parameter is set to 'all'. The list of source id's is referenced from the region file in order to find out what 'all' sources are present. If 'all' is not used, then the region file does not need to be input. In later stages of the tool, the region should be an extension of the infile events. The file format can be found in the FITS REGION ASC document. Sample data: SHAPE X Y R pixel pixel pixel 1 circle 3.9763999E+03 4.1686001E+03 2.6000000E+01 0.0000000E+00 0.0000000E+00 0.0000000E+00 2 rotbox 4.0950000E+03 4.1790000E+03 8.1820000E+03 0.0000000E+00 0.0000000E+00 4.1000000E+01 3 rotbox 4.0950000E+03 4.1580000E+03 8.1820000E+03 0.0000000E+00 0.0000000E+00 5.6000000E+01 4 circle 4.0403999E+03 4.7446001E+03 4.3000000E+01 0.0000000E+00 0.0000000E+00 0.0000000E+00 ROTANG COMPONENT SOURCE GRATING deg 1 0.0000000E+00 1 1 hetg 0.0000000E+00 2 5.1799998E+00 2 1 hetg 0.0000000E+00 3 -4.7500000E+00 3 1 hetg 0.0000000E+00 4 0.0000000E+00 1 3 hetg 0.0000000E+00 outfile_type [pha2] (pha1|pha2) Ouput file type: pha1 (single spectrum of OGIP TYPE I) or pha2 (multiple spectra of OGIP Type II). outfile [filename or . or root] (root_pha2.fits or root or '.') Output file name. If outfile_type=pha2, the user can enter the full output file name or '.'. If the '.' is used, the input file name is used to create the output file; if infile = root_extension.fits, then outfile will be root_pha2.fits. If outfile_type=pha1, the user can enter the rootname of the output file or '.'. If root name is used, the output file will be named as: root__pha2.fits; if '.' is used, the input file name is used to create the output file: if infile = root_extension.fits, then outfile will be root__pha2.fits. tg_srcid_list [string] (all|string|@filename) The list of source orders to process. "all" will process all the sources id's found in the event region file. A comma separated string list can be used instead of the region file: "1,2,5,7". Another option is to use an @file which contains a comma separated list or source id's to process. tg_part_list [string] (HETG|HEG|MEG|LETG|HESF|header_value) Grating parts to process: HETG, HEG, MEG, LETG, HESF, header_value. 'header_value' will take the input event file header value of the keyword GRATING. tg_order_list [string] (default|comma list|range list|@file) Grating diffraction orders to process: 'default', comma list, range list, 'all', @file. - "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 (excluding 0) 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 ancrfile [filename] (filename or 'none') Input ancillary response file name. The filename or the word 'none' gets written to output file in the ANCRFILE column. respfile [filename] (filename or 'none') Input redistribution file name. The filename or the word 'none' gets written to output file in the RESPFILE column. (backfile = "") [filename] If BACKFILE column is to be filled in, enter name here; otherwise, the column is not present in the output file. (rowid = "") [string of length 64] If ROWID column is to be filled in, enter name here; otherwise, the column is not present in the output file. (grating_par = grating) [param name] Name of the grating parameter file with grating characteristics. (bin_units = Angstrom) [Angstrom|eV|KeV|deg|pix|mm] Bin units (for bin parameters below): Angstrom, KeV, eV, deg, pix, mm. Specifies the units of min_bin, max_bin, bin_size and of the output histogram. If units are Energy, then the tg_lam values in the event file must be converted to energy via E = hc/lambda, where hc=12398.54 (hc=12.3985 for KeV) for lambda in Angstroms and E in eV. If other bin parameters are left to defaults (Angstroms), and bin_units is not Angstrom, then binning parameters are converted to the specified unit and events are binned accordingly. NOTE: Binning Parameters ------------------------ If the grating type is HETG, the binning parameters should be given for MEG +1 order binning. The bin characteristics will be updated for all other orders and grating parts, using the the following calculations: m * lambda = P * sin(theta) order * wavelength = period * sin(diffraction angle) Diffraction angle == tg_r is small, so sin(theta) ~ theta, so m * lambda = P * tg_r Calculating a bin size is done by taking the derivative: m * delta_lambda = P * delta_tg_r or equivalently delta_lambda = (P/m) * delta_tg_r. If bins are specified for first order MEG and, the rest are scaled to: (Period_part/Period_MEG) / order If the grating is LETG (and detector is ACIS), the user can specify the binning for LETG +1, and the rest of the binning will be scaled by order only, as apposed to using the Period ratio's above. (min_bin = compute) ['compute'|real number] Minimum dispersion coordinate on which to start the binning. A real valued number can be specified in any other diffraction coordinate: max energy [keV], tg_r [deg], gdp [pix], or linear [mm]. The default is: 1.239854 Angstrom (10.0 keV). It is assumed that the bin coordinate refers to the left edge of the bin, and the bin value is incremented if the data value is GE the bin coordinate, and LT the bin coordinate plus the bin_size. Min_bin could be overspecified: min_bin = max_bin - num_bins * bin_size A value of 'compute' means calculate using a combination of the bin values entered and the default values. (max_bin = compute) ['compute'|real number] Maximum dispersion coordinate on which to stop the binning. A real valued number can specified in any other diffraction coordinate: max energy [keV], tg_r [deg], gdp [pix], or linear [mm]. Default: Determined by grating type and part: HETGS/HEG: 20 A HETGS/MEG: 40 A LETGS: 170 A LETG/ACIS-S: 100 A HETG/HEG/HRC-S: 30 A HETG/MEG/HRC-S: 60 A It is assumed that the max_bin coordinate refers to the right edge of the bin, and the bin value is incremented if the data value is GE the left edge (the bin coordinate) and LT the left edge plust the bin_size (right edge). Max_bin could be overspecified: max_bin = min_bin + num_bins * bin_size A value of 'compute' means calculate using a combination of the bin values entered and the default values. (bin_size = compute) ['compute'|real number] This is the size of the bins for storing the counts histogram. It is assumed that all bins are the same size, and that the bin coordinate refers to the left edge of the bin. Default: Determined by grating type, part, and order, for 0.012 mm linear scale (one-half spatial resolution). Wavelength bin is equal to: TG_Period * linear_scale / Rowland_Spacing / tg_m First-order nominal size for 0.012 mm: HETGS/HEG: 2.78e-03 A /MEG: 5.56e-03 A LETGS : 1.38e-03 A Bins may be specified in other diffraction coordinates: energy [eV], tg_r [deg], gdp [pix], or linear [mm]. Bin_size could be overspecified: bin_size = (max_bin - min-bin) / num_bins A value of 'compute' means calculate using a combination of the bin values entered and the default values. (num_bins = compute) ['compute'|integer] The number of bins for the resultant spectra. For now, the default values are (max_bin-min_bin)/bin_size. Default: Determined by grating type and detector. Nominal configurations: HETGS: 7014 (default bin_min, bin_max, bin_size) LETGS: 12268 (default bin_min, bin_max, bin_size) The number of bins is possibly overspecified. Min_bin, max_bin, and bin_size completely specify the number of bins. The 'compute' option is for for calculating the number of bins: num_bins = (max_bin - min_bin) / bin_size (tg_d_units = deg) [deg|arcsec|mm|pix] Tg_d bin units (for tg_d parameters below): Angstrom, eV, deg, pix, mm. Specifies the units of min_tg_d, max_tg_d, min_bkg_tg_d and max_bkg_tg_d. Only degrees are currently implemented in the tool, since tg_d is in degrees in the input file. NOTE: the following is a representation of the tg_d parameters: ----------------------------------- (+1.0)*(|max_bkg_tg_d|) =~+1.0mm the high-side background region tg_d ^ | ----------------------------------- (+1.0)*(|min_bkg_tg_d|) +0.1 ----------------------------------- max_tg_d 0.0 the "source" region (the "prime" area) +----> tg_lam -0.1 ----------------------------------- min_tg_d ----------------------------------- (-1.0)*(|min_bkg_tg_d|) the low-side background region ------------------------------------ (-1.0)*(|max_bkg_tg_d|) =~-1.0mm The region between min_tg_d and max_tg_d is the area when the data spectrum is extracted. The area between (|min_bkg_tg_d| and |max_bkg_tg_d|) && (-1.0*min_bkg_tg_d and -1.0*|max_bkg_tg_d|) is the background spectrum. Note that the top and bottom background sections get added together to create one background spectrum. (min_tg_d = compute) ['compute'|real number] Specifies the minimum tg_d range to include in the histogram. Units are specified by tg_d_units. Default: Determined by configuration: HETGS: -0.1 mm, == -2.39 arcsec, == -6.64E-04 deg LETGS: -0.2 mm, == -4.78 arcsec, == -1.33E-03 deg (max_tg_d = compute) ['compute'|real number] Specifies the maximum tg_d range to include in the histogram. Units are specified by tg_d_units. Default: Determined by configuration: HETGS: +0.1 mm, == 2.39 arcsec, == 6.64E-04 deg LETGS: +0.2 mm, == 4.78 arcsec, == 1.33E-03 deg (extract_background = no) [boolean] Extract the local background spectrum? If set to yes, the background spectrum will be in the output file(s). The parameters min_bkg_tg_d and max_bkg_tg_d are used to determine the size of the background spectrum. If set to NO, then the output column BACKGROUND is not present in the output file(s). (min_bkg_tg_d = compute) ['compute'|real number] Specifies the minimum absolute value of tg_d for a background region. The default starts where the spectral region ends (at max(|min_tg_d| || |max_tg_d|)). Events with cross-dispersion from the background region will be binned into a background spectrum. The units are to be specified by tg_d_units. Default: Depends on configuration: min_bkg_tg_d = max(|min_tg_d| || |max_tg_d|)) (max_bkg_tg_d = compute) ['compute'|real number] Specifies the maximum absolute value of tg_d for a background region. The default values are listed below; however, if the set defaults are still within the non-background tg_d range, then, the max_bkg_tg_d is set to 10 times max(|min_tg_d| || |max_tg_d|). Events with cross-dispersion from the background region will be binned into a background spectrum. The units are to be specified by tg_d_units. Default: Depends on configuration: HETGS: +/-1.0 mm == +/-23.9 arcsec, == 6.64E-03 deg LETGS: +/-2.0 mm == +/-47.8 arcsec, == 1.33E-02 deg (clobber = no) [boolean] If set to yes, existing output files will be overwritten. (display = 1) [integer 0:5] Program verbosity. 0 means display no messages to the screen while running. 5 means report maximum on what the program is doing. (mode = "ql") [string] Parameter interface mode. "ql" stands for "query and learn", which prompts you for input and updates "tgextract.par" with your responses. EXAMPLES > tgextract infile=AS_004_evt1a.fits regionfile="" outfile_type=pha2 outfile=AS_004_pha2.fits tg_srcid_list=1 tg_part_list=header_value tg_order_list=1 ancrfile=none respfile=none backfile="" rowid="" grating_par=grating bin_units=Angstrom min_bin=compute max_bin=compute bin_size=compute num_bins=compute tg_d_units=deg min_tg_d=default max_tg_d=default extract_background=yes min_bkg_tg_d=default max_bkg_tg_d=default clobber=yes The output Type II pha file is called AS_004_pha2.fits, and can be viewed by any ftools and dmtools. Here's a small section of the output file: EXTNAME=SPECTRUM ---------------- SPEC_NUM TG_M TG_PART TG_SRC_ID 1 1 1 1 1 2 2 1 2 1 ANCRFILE 1 none 2 none RESPFILE 1 none 2 none CHANNEL COUNTS STAT_ERR BACKGROUND BIN_LO counts counts counts Angstrom 1 1 0 1.8660254E+00 0 6.199579855050732E-01 2 0 1.8660254E+00 0 6.227381244564402E-01 3 0 1.8660254E+00 0 6.255182634078071E-01 ... 2 1 0 1.8660254E+00 0 1.239854000000000E+00 2 0 1.8660254E+00 0 1.245414000000000E+00 3 0 1.8660254E+00 0 1.250974000000000E+00 ... BIN_HI Angstrom 1 6.227381244564402E-01 6.255182634078071E-01 6.282984023591741E-01 ... 2 1.245414000000000E+00 1.250974000000000E+00 1.256534000000000E+00 ... EXTNAME=REGION -------------- SPEC_NUM ROWID SHAPE TG_LAM Angstrom 1 1 SOURCE box 1.031047881781376E+01 2 1 BACKGROUND_UP box 1.031047881781376E+01 3 1 BACKGROUND_DOWN box 1.031047881781376E+01 4 2 SOURCE box 2.061992700000000E+01 5 2 BACKGROUND_UP box 2.061992700000000E+01 6 2 BACKGROUND_DOWN box 2.061992700000000E+01 TG_D R ROTANG deg (Angstrom , deg) deg 1 0.000000000000000E+00 1.938104166461738E+01 0.000000000000000E+00 1.327777777777778E-03 2 3.651388888888888E-03 1.938104166461738E+01 0.000000000000000E+00 5.974999999999999E-03 3 3.651388888888888E-03 1.938104166461738E+01 0.000000000000000E+00 5.974999999999999E-03 4 0.000000000000000E+00 3.876014600000000E+01 0.000000000000000E+00 1.327777777777778E-03 5 3.651388888888888E-03 3.876014600000000E+01 0.000000000000000E+00 5.974999999999999E-03 6 3.651388888888888E-03 3.876014600000000E+01 0.000000000000000E+00 5.974999999999999E-03 COMPONENT INCLUDE TG_SRC_ID TG_M 1 1 1 1 1 2 1 1 1 1 3 1 1 1 1 4 2 1 1 1 5 2 1 1 1 6 2 1 1 1 DATE 08/10/98 09/16/98