|
|
|
|
|
SynopsisExtract source and background ACIS spectra for point-like and extended sources and build associated WMAPs, ARFs and RMFs. Syntaxspecextract infile outroot pbkfile [bkgfile] [dafile] [ptype] [grouptype] [binspec] [bkg_grouptype] [bkg_binspec] [energy] [channel] [energy_wmap] [binwmap] [clobber] [verbose] Description`specextract' is a script which lets the user create source and background PHA or PI spectra and their associated WMAPs, ARFs and RMFs files for point and extended sources. specextract is designed to replace the psextract and acisspec scripts currently distributed in the CIAO Scripts package. The major improvement over its predecessors is the ability to determine when mkacisrmf should be used in place of mkrmf (see "Creating RMFs: mkrmf vs. mkacisrmf" section, below, for details). The new script, which is written in S-Lang ("ahelp slang"), is also able to accept a stack of input files in order to generate many spectra from one command. Note that specextract does *not* offer the option to coadd spectra as acisspec does. The script combines the dmextract, mkwarf, mkrmf OR mkacisrmf, dmgroup and dmhedit tools; see the individual help files for information on each of these, e.g. "ahelp dmextract". Creating RMFs: mkrmf vs. mkacisrmfThe tool mkacisrmf was introduced in CIAO 3.2 and represents an entirely new method for creating ACIS response matrices; details on why mkacisrmf is more accurate than mkrmf are available in the the mkacisrmf help file. As of CALDB 3.1.0, released on 23 June 2005, mkacisrmf can be used to create RMFs for all observations taken at the -120 C focal plane temperature, which have had the appropriate calibration applied. The Creating ACIS RMFs with mkacisrmf why topic contains details about the tool and its calibration. specextract reads the source and background file header keywords to determine when the observation was taken and what calibration has been applied. If all the requirements are met, the script uses mkacisrmf to generate the source and background RMF(s) for the data. If the observation was not done at -120 or has not been reprocessed with the newest calibration available, specextract creates the RMF(s) with mkrmf. Output FilesThe number of files created depends on if a background event file was provided and if source and/or background grouping was specified. In the most general case (source and background both provided and grouping given for both), the output files will be:
Grouping Source and Background SpectraThe user can choose to group the output source spectrum; all the grouptype options available with dmgroup are allowed. However, the dmgroup parameters "xcolumn" and "ycolumn" are hard-coded to "channel" and "counts" respectively, as appropriate for standard PHA files. If grouping is chosen, both the grouped and ungrouped source and background spectra files are written out; the grouped are designated by the "_grp.pi" ending in the filename. The RESPFILE and ANCRFILE keywords in the header of the grouped source and background spectrum will be updated, as will the BACKFILE header keyword in the source spectra only. Fitting the SpectraAs mentioned, the BACKFILE, ANCRFILE, and RESPFILE header keywords in the source and background spectra are updated appropriately by specextract. This means that the spectra can then be read into Sherpa and all the supporting files will automatically be read as well; the background (if available) will be defined, as will the source and background response files. Please see the Sherpa threads for more information on using Sherpa to fit spectral data. Example 1specextract "acis_evt2.fits[sky=region(3c273.reg)]" outroot=3c273 bkgfile="acis_evt2.fits[sky=region(3c273_bg.reg)]" pbkfile=NONE dafile=NONE grouptype=NONE binspec=NONE Extract source and background spectra from the same event file using the region files "3c273.reg" and "3c273_bg.reg", respectively. Neither of the spectra will be binned. Default values are used for creating the WMAP and RMF files. Example 2specextract "acis_evt2.fits[sky=region(1447_src.reg)]" pbkfile=acisf063875928N002_pbk0.fits dafile=CALDB outroot=acis_1447 bkgfile="acis_evt2.fits[sky=region(1447_bkg.reg)]" grouptype=NUM_CTS binspec=10 bkg_grouptype=NUM_CTS bkg_binspec=10 Similar to the previous example, except the source and background spectra are each grouped such that there are 10 counts in a bin. The pbkfile and dafile parameters are set to apply the dead area correction. Example 3specextract "acis_5027_evt2.fits[sky=region(5027_srcA.reg)],acis_5027_evt2.fits[sky= region(5027_srcB.reg)]" pbkfile=NONE dafile=NONE outroot=5027 bkgfile="" ptype=PI grouptype=NONE binspec=NONE Two event files are given as a stack, so two sets of output files are created based on the outroot value "5027": 5027_src1 and 5027_src2. No grouping is applied to the source spectra, and no background spectra are created. Default values are used for creating the WMAP and RMF files. Example 4specextract @input.lis @output.lis @pbk.lis The input event files, output filenames, and parameter block files are all defined as a stack: unix% cat input.lis acisf00459N002_evt2.fits[sky=region(3c273.reg)] 5027_repro_evt2.fits[sky=region(5027_src.reg)] unix% cat output.lis 459_3c273 5027_sl4 unix% cat pbk.lis acisf063875928N002_pbk0.fits acisf212079072N002_pbk0.fits Default values are used for all the other parameters. Parameters
Detailed Parameter DescriptionsParameter=infile (file required filetype=input stacks=yes)The source event file(s) The primary input to this tool is an event file (or stack of event files) with a filter defining the extraction region for the spectrum. See "ahelp dmfiltering" for information on defining region filters, and "ahelp stack" for details on using stacks of files. Parameter=outroot (file required stacks=yes)Root for the output filenames or a stack of filenames If a string is given, it is used in naming all files created by specextract. In this case, the tool creates output files designated as "src1", "src2", etc. The background files are named "bkg1", "bkg2", etc., to correspond to the source Alternatively, a stack of output filenames can be specified, one for each input file. See "ahelp stack" for details on using stacks of files. Parameter=pbkfile (file required filetype=input stacks=yes)The parameter block file(s) The parameter block file, which defines ACIS pixel clocking parameters, is a standard product of pipeline processing and is available for every observation. This file contains information which defines how long any pixel is exposed before being read-out, which is related to the probability that any pixel will be disabled ("deadened") by cosmic rays. See the description of the "dafile" parameter for more information on ACIS dead area. If a stack of input filenames is given, there must be the same number of parameter block files specified. Parameter block files have names of the form, "acisf146860615N001_pbk0.fits". The long string of digits refers to the time of observation (seconds since reference date) and "N001" is a revision number. Since the pbkfile contents are observation-dependent, there is no default other than "NONE". In this case, no dead area correction is applied, and dafile is assumed to have the value "NONE". If pbkfile is set to a valid file, then the dafile parameter must also refer to a calibration file. The pbkfile parameter is ignored for HRC data. Parameter=bkgfile (file not required filetype=input stacks=yes)The background event file(s) The background event file (or stack of event files) with a filter defining the extraction region for the spectrum. See "ahelp dmfiltering" for information on defining region filters, and "ahelp stack" for details on using stacks of files. If background spectra are desired, the source and background stacks must contain the same number of elements. It is allowable to leave this parameter value blank, which results in no background spectra being created. Parameter=dafile (file not required filetype=input default=CALDB stacks=yes)ACIS "dead area" coefficients file, which may have the values "NONE" (no dead area computation), CALDB (for automatic lookup), or an explicit file reference to an ACIS "dead area" coefficients FITS table. If a stack of pbkfile filenames is given and dafile is not set to "CALDB", there must be the same number of dead area FITS tables as parameter block files specified. The ACIS dead area refers to a slight decrease in detector efficiency due to the background cosmic ray flux which temporarily renders some pixels useless. The calibration product is a coefficient (per CCD) which gives the fractional area lost (or "deadened") per second. Since the area lost increases with time, the magnitude of the effect depends upon the ACIS clocking parameters (number of rows, window location, frame-time) which determine how long a pixel was exposed to the background cosmic ray flux during the primary exposure and during electronic readout from the frame-store area. For full-frame timed-exposure, the dead area is about 4% at maximum CHIPY and about 2% at the readout. It is smaller for subarrays. The ACIS clocking parameters required to scale the coefficients in the dafile are contained in the observation-specific parameter block file, which can be set by the associated parameter of this tool, "pbkfile". If dafile=NONE, then pbkfile=NONE is assumed. The dafile parameter is ignored for HRC data. Parameter=ptype (string not required default=PI)Spectrum type to extract Determines if the RMF grids are energy vs PHA or energy vs PI. Valid values are PHA and PI; these values are case-sensitive. Read the "channel" parameter description for important information about PI and PHA binning. Parameter=grouptype (string not required default=NUM_CTS)Source spectrum grouping type The allowed values the same as those in dmgroup: NONE, BIN, SNR, NUM_BINS, NUM_CTS, ADAPTIVE, ADAPTIVE_SNR, BIN_WIDTH, MIN_SLOPE, MAX_SLOPE, and BIN_FILE.
More information on grouping is available from "ahelp dmgroup". Parameter=binspec (string not required default=15)Source spectrum grouping specification A numerical value used for the grouping method. The format of the grouping specification depends on what is chosen for the "grouptype" parameter. Here are some example values for each option:
More information on grouping is available from "ahelp dmgroup". Parameter=bkg_grouptype (string not required default=NONE)Background spectrum grouping type The allowed values are the same as those in dmgroup: NONE, BIN, SNR, NUM_BINS, NUM_CTS, ADAPTIVE, ADAPTIVE_SNR, BIN_WIDTH, MIN_SLOPE, MAX_SLOPE, and BIN_FILE; see the "grouptype" parameter description for details. More information on grouping is available from "ahelp dmgroup". Parameter=bkg_binspec (string not required)Background spectrum grouping specification A numerical value used for the background grouping method. The format of the grouping specification depends on what is chosen for the "bkg_grouptype" parameter; see the "binspec" parameter description for details. More information on grouping is available from "ahelp dmgroup". Parameter=energy (string not required default=0.3:11.0:0.01)Energy grid in keV The grid is specified by giving the lower bound, upper bound, and binning step, separated by the ":" character. For example, the default value "energy=0.3:11.0:0.01" bins from 0.3 to 11.0 keV in steps of 0.01 keV. The default value of this parameter is suitable for most analyses. Parameter=channel (string not required default=1:1024:1)RMF binning specification in pixels The grid is specified by giving the minimum, maximum channel, and binning step, separated by the ":" character. For example, "channel=1:1024:1" bins from channel 1 to 1024 in steps of 1. The default value is suitable for most analyses of PI spectra. A binning of "channel=1:4096:2" is suitable for most analyses of PHA spectra. NB: the default PHA binning used by dmextract is "1:4096:2"; refer to the "defaults" parameter in "ahelp dmextract" for more information. If you intend to finish your analysis in XSpec, you must set "channel=1:4096:2", so that the spectrum and RMF have the same binning. Sherpa does not require that the spectrum and response be binned the same. If you want an unbinned PHA spectrum (e.g. 1:4096:1), you will have to run dmextract independently of specextract. Setting "channel=1:4096:1" in specextract will produce an RMF and ARF appropriate for use with the unbinned PHA spectrum. Parameter=energy_wmap (string not required default=300:2000)Energy range for WMAPs The WMAP (weight map) file is an image of the extraction region. Specifically, the PHA FITS file has in its primary header an image containing a low resolution map of the source in detector coordinates. This allows downstream software to determine the appropriate weighting for calibrations which depend on detector position (for instance, effective areas may depend on the off-axis angle). An energy filter may be included when creating a WMAP to better represent the event distribution in a particular energy range, e.g. the default value of 300:2000 eV. This parameter is used in conjunction with the "binwmap" value. Parameter=binwmap (string not required default=det=8)Binning factor for WMAPs. The binwmap parameter allows the user to define the binning of the WMAP; see the "energy_wmap" parameter for a description of what a WMAP is. We recommend 'binwmap="det=8"' (the default) to create a map in DETX,DETY coordinates binned by a factor 8. This parameter is used in conjunction with the "energy_wmap" value. Parameter=clobber (boolean not required default=no)Specifies if an existing output file should be overwritten. Parameter=verbose (integer not required default=0)Specifies the level of verbosity (0-5) in displaying diagnostic messages. CHANGES IN CIAO 4.0 Beta 1Dead area correction parametersTwo new parameters have been added to specextract to allow the ACIS dead area correction to be taken into account: "pbkfile" and "dafile". See the individual parameter descriptions for more information. The ACIS dead area correction is "on" by default in CIAO 4.0 Beta 1. Users who wish to continue analysis without the dead area correction should set both of these parameters to "NONE":
unix% pset specextract pbkfile=NONE dafile=NONE
BugsSee the bugs page for this tool 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}