|
|
|
|
|
SynopsisAdd positive and negative diffraction orders of a grating PHA spectra and the corresponding ARFs Syntaxadd_grating_orders pha2 order garm garfm garfp root [gtype] [gspec] [clobber] [verbose] DescriptionWHAT THE TOOL DOES`add_grating_orders' is a script which lets the user add up positive and negative diffraction orders of a given grating spectrum, and their associated ARFs. Optionally the output spectrum can be grouped. The script splits the PHA2 file into two (negative and positive) PHA spectra using the CIAO tool "dmtype2split". Then it combines a series of "dmtcalc" and "dmpaste" commands, performing math operations bewtween columns of these two temporary files, and then merging the final columns into the output PHA and ARF files. The CIAO tool "dmgroup" is then eventually run, and some header keywords of the output files are edited using "dmhedit". WHAT THE USER SHOULD SUPPLYThe user supplies (a) the input PHA2 file, the order to be coadded (i.e. 1, 2 or 3, for a default ACIS-HETG or -LETG PHA2 file), (b) the grating arm (i.e. HEG, MEG or LEG), (c) the ARFs of the negative and positive orders to coadd, and (d) optionally, the grouping type and specifications (see "ahelp dmgroup"). OUTPUT SOURCE AND BACKGROUND SPECTRUMSource counts from the two input source and background spectra are simply added together, and written out into the output PHA file. The values of the keywords BACKSCAL, BACKSCUP and BACKSCDN in the header of the output PHA file are hard-coded in the script and are equal to 1.0, 4.5, 4.5 for ACIS, and 1.0, 5.0 and 5.0 for HRC input spectra, respectively. This is correct only for input negative and positive spectra extracted with default extraction region sizes for both source and background. If non-default source and/or background extraction region have been used to extract the negative and positive spectra in the input PHA2 file, then the BACKSCUP and BACKSCDN keywords of the output PHA file should be edited and properly set to the ratios of the width of the background-up and background-down regions to the width of the source region, respectively. A new column is written with the statistical errors, calculated according to the formula: STAT_ERR = (1+sqrt(COUNTS+0.75)). OUTPUT EFFECTIVE AREAThe two effective areas are added together and written out into the output ARF file. GROUPING THE OUTPUT SPECTRUMOptionally the output spectrum is grouped, according to the given grouping type and specifications (see the parameters description, below). Currently, the following dmgroup group-type options are available: BIN, NONE, SNR, NUM_BINS, NUM_CTS, and ADAPTIVE (see "ahelp dmgroup" for details). However, the dmgroup parameters "xcolumn" and "ycolumn" are hard-coded and fixed to "channel" and "counts", respectively, as appropriate for standard PHA files. HEADER KEYWORDS IN THE OUTPUT FILESThe keyword ANCRFILE in the header of the output PHA is edit and given the output ARF filename. The keyword TG_M is not propagated into the header of the output PHA file. Example 1add_grating_orders pha2=spec.pha2 order=1 garm=HEG garfm=eff_area_m1.arf garfp=eff_area_p1.arf root=test1 gtype=NONE verbose=2 Add together negative and positive 1st order source and background HEG spectra in spec.pha2, and the corresponding ARFs in eff_area_m1.arf and eff_are_p1.arf. The output spectrum is not grouped. Output spectrum and ARF are named test1.pha and test1.arf. Example 2add_grating_orders pha2=spec.pha2 order=3 garm=LEG garfm=eff_area_m3.arf garfp=eff_area_p3.arf root=test2 gtype=BIN gspec=10 verbose=2 Add together negative and positive 3rd order source and background ACIS-LEG spectra in spec.pha2, and the corresponding ARFs in eff_area_m3.arf and eff_are_p3.arf. The output spectrum is grouped by a factor of 10. Output spectrum and ARF are named test2.pha and test2.arf. Example 3add_grating_orders pha2=spec.pha2 order=3 garm=HEG garfm=eff_area_m3.arf garfp=eff_area_p3.arf root=test3 gtype=NUM_CTS gspec=20 verbose=2 Add together negative and positive 3rd order source and background ACIS-LEG spectra in spec.pha2, and the corresponding ARFs in eff_area_m3.arf and eff_are_p3.arf. The output spectrum grouped allowing a minimum of 20 source counts per new bin. Output spectrum and ARF are named test3.pha and test3.arf. Parameters
Detailed Parameter DescriptionsParameter=pha2 (string required filetype=input)Input PHA2 filename. Parameter=order (string required filetype=input)Order of the grating spectra to extract and add together. Parameter=garm (string required filetype=input)Grating Arm (HEG, MEG or LEG). Parameter=garfm (string required filetype=input)Negative order grating effective area. Parameter=garfp (string required filetype=input)Positive order grating effective area. Parameter=root (string required filetype=output)Root name for the output files root.pha and root.arf. Parameter=gtype (string not required)The grouping type (NONE, BIN, SNR, NUM_BINS, NUM_CTS, or ADAPTIVE). See "ahelp dmgroup" for details. Parameter=gspec (string not required)The grouping specification; form depends on GTYPE. See "ahelp dmgroup" for details. Note that for the BIN grouping type, gspec corresponds to the step size of the binning. The min and max of the binning specification are hard-coded (1:8192 for ACIS, 1:16384 for HRC). Thus, '10' is a valid gspec, but '1:8192:10' is not and will produce errors. Parameter=clobber (boolean not required)Clobber existing output files? Specifies if existing output files should be overwritten. Parameter=verbose (integer not required)Controls amount of information to print (0-5). The verbose parameter provides debugging information; verbose = 0 is usually fine. CHANGES IN ADD_GRATING_ORDERS 2.6Syntax for head commandThe head command was replaced by the CIAO tool "dmkeypar". The file output is not affected. CHANGES IN ADD_GRATING_ORDERS 2.5Syntax for head commandThe syntax of the head command was updated to include the "-n" flag. The file output is not affected. CHANGES IN CIAO 4.0/ADD_GRATING_ORDERS 2.4It is necessary to specify an output block name of "SPECTRUM" in the dmtype2split commands used by the script. Quotation marks were also added to a dmhedit command so that the correct pathname written in the ANCRFILE header keyword in the output PHA file. The "kernel" parameter was removed from dmtcalc and dmpaste in CIAO 4.0. NOTESThis script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see the installation instructions page for help on installing the package. BugsSee the bugs page for this script on the CIAO website for an up-to-date listing of known bugs. See Also
|
 |
The Chandra X-Ray
Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA. Email: cxcweb@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2004. All rights reserved. |
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}