Skip to the navigation links
Last modified: December 2009

URL: http://cxc-newtest.cfa.harvard.edu/ciao4.2/specextract.html
AHELP for CIAO 4.2

specextract

Context: tools

Synopsis

Extract source and background ACIS spectra for point-like and extended sources and build associated WMAPs, ARFs and RMFs.

Syntax

specextract  infile outroot pbkfile [bkgfile] [rmffile] [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. It has the ability to determine when mkacisrmf should be used in place of mkrmf (see "Creating RMFs: mkrmf vs. mkacisrmf" section, below, for details).

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. mkacisrmf

The tool mkacisrmf represents an new method for creating ACIS response matrices; details on why mkacisrmf is more accurate than mkrmf are available in the the mkacisrmf help file. 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 Files

The 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:

  • ungrouped and grouped source spectra (.pi, grp.pi)
  • ungrouped and grouped background spectra (.pi, grp.pi)
  • source and background weight files (.fef). These files are created by mkwarf for use with mkrmf; they are not needed for any subsequent spectral analysis.
  • weighted source and background RMF and ARF files (.wrmf, .warf)

Grouping Source and Background Spectra

The 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 Spectra

As 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 1

specextract "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 2

specextract "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 3

specextract
"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 4

specextract @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

name type ftype def reqd stacks
infile file input   yes yes
outroot file     yes yes
pbkfile file input   yes yes
bkgfile file input   no yes
rmffile file input CALDB no no
dafile file input CALDB no yes
ptype string   PI no  
grouptype string   NUM_CTS no  
binspec string   15 no  
bkg_grouptype string   NONE no  
bkg_binspec string     no  
energy string   0.3:11.0:0.01 no  
channel string   1:1024:1 no  
energy_wmap string   300:2000 no  
binwmap string   det=8 no  
clobber boolean   no no  
verbose integer   0 no  

Detailed Parameter Descriptions

Parameter=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=rmffile (file not required filetype=input default=CALDB stacks=no)

The rmftool CALDB directive

CALDB directive used to select DET_GAIN calibration file, which in turn is used to select the rmf tool to use. mkacisrmf is used when the cal file selected matches the cal file specified in the input file header, otherwise mkrmf is used.

rmffile defaults to "CALDB", which will cause infile header keywords to be used to select the DET_GAIN calibration file. If the user wishes to override any keyword, CALDB parameters can be specified using the form:

CALDB(PARAMETER=VALUE;PARAMETER=VALUE...)

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.

  • NONE: The data are grouped using maximum resolution.
  • BIN: Explicitly state the binning boundaries, e.g. "10:40:5".
  • SNR: Data in are grouped until the square root of the number of counts in each group exceeds the given signal-to-noise value.
  • NUM_BINS: Data are grouped into a number of equal-width groups.
  • NUM_CTS: Data are grouped until the number of counts in each group exceeds the minimum number of counts specified.
  • ADAPTIVE: Keeps bright features ungrouped, while grouping low SNR regions.
  • ADAPTIVE_SNR: similar to the ADAPTIVE method. Uses the SNR ratio to determine cutoffs instead of a count threshold.
  • BIN_WIDTH: Data are grouped into bins of the specified width.
  • MIN_SLOPE: Groups are formed when the absolute value of the slope of the data is less than the minimum slope threshold given in grouptypeval.
  • MAX_SLOPE: Groups are formed when the absolute value of the slope of the data is greater than the minimum slope threshold given in grouptypeval.
  • BIN_FILE: Data are grouped to match a previously grouped 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:

  • grouptype=NONE, binspec=NONE (no grouping)
  • grouptype=BIN, binspec="10:40:5" (start:stop:stepsize)
  • grouptype=SNR, binspec=30 (signal-to-noise value)
  • grouptype=NUM_BINS, binspec=10 (number of bins)
  • grouptype=NUM_CTS, binspec=30 (minimum number of counts per group)
  • grouptype=ADAPTIVE, binspec=100 (counts value for low SNR regions)
  • grouptype=ADAPTIVE_SNR, binspec=50 (signal-to-noise value for low SNR regions)
  • grouptype=BIN_WIDTH, binspec=15 (width of the bins)
  • grouptype=MIN_SLOPE, binspec=50 (minimum slope of the data)
  • grouptype=MAX_SLOPE, binspec=100 (maximum slope of the data)
  • grouptype=BIN_FILE, binspec=grouped.fits (name of a file that provides the grouping to match)

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.

Bugs

Caveat: Exposure Variations

The mkwarf tool is designed to represent the weighted ARF over a large region. If the exposure varies strongly over most of the extraction region then the ARF may not fully account for this variation. This is mainly of concern for regions at the edge of an ACIS chip.

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

See Also

calibration
ardlib
tools
acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, acisspec, add_grating_orders, add_grating_spectra, asphist, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, merge_all, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsf, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, rmfimg

Last modified: December 2009