specextract

Synopsis

Extract source and background ACIS spectra for point-like and extended sources and build associated unweighted or weighted ARFs and RMFs.

specextract  infile outroot weight correct asp combine pbkfile mskfile
bkgfile bkgresp [rmffile] [ptype] [grouptype] [binspec] [bkg_grouptype]
[bkg_binspec] [energy] [channel] [energy_wmap] [binwmap] [binarfwmap]
[dafile] [badpixfile] [clobber] [verbose]

Description

`specextract' is a script which lets the user create source and background PHA or PI spectra and their associated unweighted or weighted ARF and RMF 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 OR mkarf, mkrmf OR mkacisrmf, dmgroup, dmhedit, dmmakereg, sky2tdet, and arfcorr tools, as well as the acis_set_ardlib script; see the individual help files for information on each of these, e.g. "ahelp dmextract".

Creating RMFs: mkrmf vs. mkacisrmf

The tool mkacisrmf represents a 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 uses the input event file to query the CALDB for a P2_RESP file, the calibration used by mkacisrmf. If a calibration file exists, specextract runs mkacisrmf to create the RMF. This improvement means that specextract will choose mkacisrmf for all the valid observation cases. If a calibration file for the data is not available, specextract creates the RMF(s) with mkrmf.

Weighted vs. Unweighted Responses

The specextract 'weight' Boolean parameter allows the user to choose between generating weighted versus unweighted ARF and RMF files. If 'weight=yes' (default), specextract will create a weighted ARF (with extension .warf) by running mkwarf, where the input detector WMAP to mkwarf is created with the sky2tdet tool in TDET coordinates, with the user-specified binning ('binarfwmap' parameter). A weighted RMF (extension .wrmf) is generated via mkrmf or mkacisrmf, depending on the existence of the P2_RESP calibration file for the observation in the CALDB (refer to the "Creating RMFs: mkrmf vs. mkacisrmf" section above for details). If mkacisrmf is run, the input WMAP is not the same WMAP in TDET coordinates input to mkwarf, but is that which is created by dmextract in the spectral extraction step of the script, with the binning and energy specified in the specextact 'binwmap' and 'energy_wmap' parameters. It is required that one detector mask file per input source observation be input to the specextract 'mskfile' parameter for both 'weight=no' and 'weight=yes' options.

If 'weight=no', mkarf is used to create an unweighted ARF (extension .arf), which is considered appropriate for point-source analysis. In this case, an unweighted RMF (extension .rmf) is generated via mkrmf or mkacisrmf , depending on the existence of the P2_RESP calibration file for the observation in the CALDB (refer to the "Creating RMFs: mkrmf vs. mkacisrmf" section above for details).

It is required that one or multiple aspect solution files, or one aspect histogram file (output of asphist) per input source observation, be input to the specextract 'asp' parameter for both the 'weight=yes' and 'weight=no' options. The is because an aspect histogram file is required input to the sky2tdet tool invoked for 'weight=yes', and for mkarf for the 'weight=no' option. The 'asp' parameter accepts either a list of aspect solution files (one or more per source observation), or a list of aspect histogram files (only one per source observation), not a mix of both types. If aspect solution files are entered, the script invokes the asphist tool for generating the required aspect histogram file input.

When both the 'infile' and 'asp' parameters contain a list of files - source observation files and aspect solution files, respectively - it is required that all files in each list have a non-NULL OBS_ID header keyword value to ensure fail-safe matching of aspect solution files to source files. To work around the OBS_ID header key requirement, aspect histogram files may be entered into 'asp' instead of aspect solution files.

Corrected vs. Uncorrected Unweighted ARFs

For the case of 'weight=no', the user has the option to apply a point-source aperture correction to the SPECRESP column contained in the ARF generated by mkarf, via the specextract 'correct' Boolean parameter. If 'correct=yes' (and 'weight=no'), specextract will invoke the arfcorr tool to apply this correction, as well as to add an additional PSF_FRAC column to the ARF output by mkarf; see the arfcorr ahelp file for details. The output corrected ARF will have extension '.corr.arf'. If 'correct=no' (and 'weight=no'), the ARF output by mkarf will be unaltered, with extension '.arf'.

All source regions input to the specextract 'infile' parameter are converted to physical coordinates via dmmakereg for point-source analysis with the ARF correction ('weight=no' and 'correct=yes'), as arfcorr requires input regions to be in physical coordinates. (Background ARFs do not get corrected since they are extended.)

Combining Output Spectra and Responses

The specextract 'combine' Boolean parameter gives the user the option to combine a stack of source and background spectra generated by specextract - in the event that stacks of soure/background observations were input to the tool and spectra were successfully created - as well as associated ARFs and RMFs output by specextract. This is done by invoking the combine_spectra script when 'combine=yes', which will sum source spectra, sum area- and exposure-weighted background spectra, compute an exposure-weighted ARF, and an ARF-weighted RMF; see the ahelp for details. The output combined spectra and response filenames will include the specextract 'outroot' string plus the string "combined", e.g. "5027_combined_src.pi", "5027_combined_bkg.rmf", etc. Note that the filenames of combined ARFs and RMFs will have extension '.arf' and '.rmf', even if weighted '.warf' and '.wrmf' files were combined.

Output Files

The number of files created depends on if a background event file was provided, if source and/or background grouping was specified, and the setting for the 'weight', 'correct', and 'combine' parameters. In the most general case (source and background both provided and grouping given for both, 'weight=yes', 'combine=no'), 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 (.wfef). These files are created by mkwarf for use with mkrmf; they are not needed for any subsequent spectral analysis.
• source and background TDET WMAP files generated by sky2tdet for input to mkwarf ('tdet.fits[wmap]')
• 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. Note that output grouped spectra and responses will not be combined if the specextract 'combine' parameter is set to 'yes'; only ungrouped files may be combined via the combine_spectra script invoked by specextract in this case.

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)]" asp=@pcad_asol1.lis
mskfile=msk1.fits badpixfile=bpix1.fits 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. The default value for the 'weight' parameter ("yes") is used for creating the weighted ARF and RMF files. Since 'weight=yes', the 'correct' parameter is ignored, and since only one file was input to the 'infile' and 'bkgfile' parameters, the 'combine' parameter is ignored. The 'asp' parameter is set with a list of aspect solution files, and the 'mskfile' parameter is set with a detector mask file (secondary data product with extension msk1.fits). The (optional) 'badpixfile' parameter is set with the appropriate bad pixel file for the observation.

Example 2

specextract "acis_evt2.fits[(x,y)=region(1447_src.reg)]"
pbkfile=acisf063875928N002_pbk0.fits dafile=CALDB outroot=acis_1447
weight="yes" binarfwmap=4 asp=asphist.fits mskfile=msk1.fits
bkgfile="acis_evt2.fits[(x,y)=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, and the 'asp' parameter includes an aspect histogram file (output of asphist). The pbkfile and dafile parameters are set to apply the dead area correction, and no bad pixel file has been set. The binning of the WMAP (output by sky2tdet) used to create the weighed ARF is changed to a value higher than 1, since the source region is very large and causes mkwarf to hit a memory limit when the WMAP is input at the highest resolution (binarfwmap=1 is the recommended setting for all other cases).

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 weight="no"
correct="yes" combine="yes" asp=asphist.fits mskfile=""

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. The 'weight' parameter is set to 'no' for creating the unweighted ARF and RMF files appropriate for point-source analysis. The output stacks of source spectra and unweighted source response files are combined, producing files "5027_combined_src.pi", "5027_combined_src.arf", and "5027_combined_src.rmf".

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

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.

If a stack of event files is entered, and 'asp' contains a stack of aspect solution files, then the lists of aspect solution and event files must be matched; this requires that all event files in the 'infile' list have a valid OBS_ID header keyword value.

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=weight (boolean required default=yes)

Determines whether to generate weighted or unweighted response files.

A Boolean switch to determine if ARF and RMF responses should be weighted or not, as appropriate for extended versus point source analysis. Weighted .warf response files are generated with mkwarf - where the input WMAP in TDET coordinates is created with sky2tdet - and unweighted .arf response files are created by mkarf. Weighted .wrmf or unweighted .rmf response files are created using either mkacisrmf or mkrmf, depending upon the existence of the P2_RESP calibration file in the CALDB for the corresponding observation. If mkacisrmf is chosen, the input WMAP (in TDET coordinates by default) is that which is created by dmextract in the spectral extraction step of the script, with the binning and energy specified in the 'binwmap' and 'energy_wmap' parameters.

Parameter=correct (boolean required default=no)

Determines whether or not to apply a point-source aperture correction to unweighted ARFs.

A Boolean switch to specify whether or not to apply the arfcorr point-source aperture correction to the unweighted ARF generated by mkarf when 'weight=no', as well as to add an additional PSF_FRAC column to this file (see the arfcorr ahelp file for details).

Parameter=asp (file required filetype=input stacks=yes)

The aspect solution or aspect histogram file(s) for the input source observation(s)

One or more aspect solution files, or one aspect histogram file created with the asphist tool, for each input observation. If aspect solution files are entered, the asphist tool is invoked to generate the required aspect histogram input to sky2tdet when 'weight=yes' and mkarf when 'weight=no'.

If a stack of aspect solution files is entered, and 'infile' contains a stack of event files, then the lists of aspect solution and event files must be matched; this requires that all aspect solution files in the 'asp' list have a valid OBS_ID header keyword value.

Parameter=combine (boolean required default=no)

Determines whether or not to combine output spectra and responses.

A Boolean switch to specify whether or not to combine the spectra and ARF and RMF files output by specextract, in the event that stacks of observations were input to the script, and spectra and responses were successfully created for these observations. This is done by invoking the combine_spectra script when 'combine=yes', which will sum source spectra, sum area- and exposure-weighted background spectra, compute an exposure-weighted ARF, and an ARF-weighted RMF; see the ahelp for details. The output combined spectra and response filenames will include the specextract 'outroot' string plus the string "combined", e.g. "5027_combines_src.pi", "5027_combines_bkg.rmf", etc. Note that the filenames of combined ARFs and RMFs will have extension '.arf' and '.rmf', even if weighted '.warf' and '.wrmf' files were combined.

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 the dafile should also be set to "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=mskfile (file required filetype=input stacks=yes)

The detector mask file(s) for the input source observation(s)

The secondary data product msk1.fits file for each input observation, for input to mkwarf when 'weight=yes' and mkarf when 'weight=no'.

Parameter=bkgfile (file 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. If background ARF and RMF files are also desired, the 'bkgresp' parameter should be set to "yes". It is allowable to leave the 'bkgfile' parameter value blank, which results in no background spectra or responses being created.

Parameter=bkgresp (boolean required default=yes)

Determines whether or not to write background responses.

A Boolean switch to specify if background ARF and RMF response files should be written for each background event file input to 'bkgfile'. If set to "no", only background spectra will be output. If no background event files are entered, 'bkgresp' is ignored.

Parameter=rmffile (file not required filetype=input default=CALDB stacks=no)

The CALDB directive used to determine the RMF tool

CALDB directive (calquiz calfile parameter) used to search for the P2_RESP calibration file(s) corresponding to the input file, the presence of which is used to determine which RMF tool to use. If a P2_RESP file is returned by the CALDB search, mkacisrmf is used; otherwise, mkrmf is used.

rmffile defaults to "CALDB", which will cause infile header keywords to be used to select the P2_RESP calibration file, along with the ccd_id value of the input source region (an rmffile value of "CALDB" gets converted internally to "CALDB(ccd_id=#)"). If the user wishes to override any keyword, CALDB parameters can be specified using the form:

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

In this case, users are urged to include a "CCD_ID=VALUE" filter in their custom CALDB directive, as specextract will not automatically add one in this case. This is to ensure that mkrmf will always be chosen over mkacisrmf for an observation taken at the -110 C focal plane temperature, where the source region lies on a front-illuminated chip.

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 ACIS detector is calibrated over the range 0.224004 - 12 keV; choosing values outside this range may result in errors from the tool. 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.

The energy_wmap parameter is used in conjunction with the "binwmap" value for creating the low-resolution WMAP in DET coordinates with dmextract (for input to mkacisrmf), as well as the high-resolution WMAP in TDET coordinates with sky2tdet (for input to mkwarf for the 'weight=yes' setting).

Parameter=binwmap (string not required default=tdet=8)

Binning factor for RMF WMAPs.

The binwmap parameter allows the user to define the binning of the WMAP generated by dmextract in the spectral extraction step of the script, for input to mkacisrmf if this tool is chosen over mkrmf for creating the RMF; see the "energy_wmap" parameter for a description of what a WMAP is. We recommend 'binwmap="tdet=8"' (the default) to create a map in TDETX,TDETY coordinates binned by a factor 8. (Note that this parameter does not influence the binning of the WMAP in TDETX,TDETY coordinates generated by sky2tdet for input to mkwarf, used for the 'weight=yes' setting.) If a TDET column is not found in an input source or background event file, 'binwmap="det=8"' is used.

This parameter is used in conjunction with the "energy_wmap" value.

Parameter=binarfwmap (string not required default=1)

Binning factor for ARF WMAPs.

The binarfwmap parameter allows the user to specify the binning of the WMAP generated by sky2tdet for input to mkwarf when weighted responses are created ('weight=yes'). Setting this parameter to a value greater than 1 can significantly reduce the time required to create the weighted ARF in the event that the source region is suitably large, however reducing the the WMAP resolution in this way may introduce aliasing effects in the CHIP->TDET coordinate transform performed by sky2tdet. It is for this reason that increasing the binning of the WMAP is recommended only for the cases where mkwarf cannot process the unbinned (bin=1) input file (mkwarf may hit a memory limit when trying to process a large file).

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

The dafile parameter is ignored for HRC data.

Parameter=badpixfile (file not required filetype=input stacks=yes)

The bad pixel file(s) for the input source observation(s)

The appropriate bad pixel file to use for an input source observation, e.g. the primary/secondary data product bpix1.fits file. When this parameter is set, the acis_set_ardlib script is run in order to set the ACIS bad pixel parameters to use the specified bad pixel file, for all the BADPIX<n> blocks in that file.

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 the December 2010 Release

The specextract script in CIAO 4.3 is an enhanced version of the specextract available in CIAO 4.2. Enhancements include:

• the added option for choosing between extended versus point source analysis via the new 'weight' parameter,
• the option to apply a point-source aperture correction to unweighted ARFs created in the 'weight=no' branch of analysis with the new 'correct' parameter,
• and the option to combine stacks of output spectra and associated responses via the new 'combine' parameter.

Additionally, weighted ARFs generated by mkwarf are more accurate as a result of running this tool in conjunction with the new sky2tdet tool; this required adding the new parameter 'mskfile' to specextract.

Finally, both the 'weight=yes' and 'weight=no' options require the user to supply an aspect histogram file, therefore the 'asp' parameter was also added to specextract.

Changes in the February 2011 Release

The 'mskfile' input is now applied to point-source ARFs (previously, the mkarf 'mskfile' value was hardcoded as "NONE" as in psextract).

A new 'badpixfile' parameter is available for setting a different bad pixel file in ARDLIB for each input source observation.

Both aspect solution files (pcad*asol1.fits) and aspect histogram files (output of asphist) are supported in the 'asp' parameter (one type or the other, not a mix).

Updated to work around a bug in the arfcorr tool (which is invoked when 'weight=no' and 'correct=yes' for point-source analysis with ARF correction): user-input source regions are converted to physical coordinates before being input to arfcorr.

If the ObsIDs of input background observations are mismatched to input source observations, background input will be ignored. Users should be sure to add the appropriate OBS_ID header key to any input observations which may be missing one, e.g., a blank-sky background file input to the 'bkgfile' parameter.

Entered source or background files missing the CTI_APP header keyword, required by many CIAO tools, will be updated according to the following rules, to avoid an acis_fef_lookup error:

• If CTI_CORR=yes, then CTI_APP=PPPPPBPBPP will be added (via dmhedit).
• If CTI_CORR=no or does not exist, then CTI_APP=NNNNNNNNNN.

The default "det=8" value for the 'binwmap' parameter has been changed to "tdet=8".

The script no longer generates temporary output files.

Changes in the April 2011 Release

There is a new parameter, 'bkgresp', to determine whether a background ARF and RMF should be created. Set to "no" to create just a background spectrum (e.g. if the background will be subtracted in analysis).

The user is now prompted for 'bkgfile' parameter input (was hidden previously).

Input source regions are converted to physical coordinates before input to arfcorr when "correct=yes" and "weight=no".

An ObsID header keyword is no longer required in background file input; this resolves problems when using the blank-sky background files, for instance. (An ObsID header keyword is required in the source and aspect solution file input only when stacks of each are entered and must be matched.)

If the input file does not have a TDET column, the ARF file is created with binwmap="det=8" instead of "tdet=8".

The script prints the version number when verbosity is greater than 0.

For 'weight=no' analysis with zeroth-order grating data as input, the mkarf 'grating' parameter is now set to the value of the GRATING header keyword in the input file ('NONE' if null or nonexistent).

It is no longer required that source regions be input in file format for the 'weight=no'/'correct=yes' branch of analysis.

Changes in the July 2011 Release

A "CCD_ID=VALUE" filter is now automatically added to the CALDB directive used to locate calibration files for determining which RMF tool to use, when the rmffile parameter is left at its default value "CALDB". (If the user has entered a custom directive of the form "CALDB(PARAMETER=VALUE;PARAMETER=VALUE...)", they are urged to include a "CCD_ID=VALUE" filter, as specextract will not automatically add one in this case. This is to ensure that mkrmf will always be chosen over mkacisrmf for an observation taken at the -110 C focal plane temperature, where the source region lies on a front-illuminated chip.)

The script no longer fails when using large stacks for both the bkgfile and asp parameters. This was due to a bug in an underlying module; a different routine is now used to avoid that bug.

When specextract is used to extract sources for tens of sources, the combining spectra step (combine=yes) no longer fails due to a string length problem. An update to an underlying module resolved the issue.

Several functions were enhanced for speed and other improvements when large files stacks are entered.

Changes in the September 2011 Release

When background spectra are extracted and combine=yes, the background spectra will be summed, even if bkgresp=no. The previous version of the script required background responses when combine=yes.

All input files are now checked for readability before an attempt is made to use them in analysis, to avoid long or confusing error messages which resulted in some cases.

Changes in the October 2011 Release

When a compressed (gzipped) source event file was input to the script without the '.gz' extension (something which most CIAO tools can handle), the arfcorr tool (invoked when weight=no/correct=yes) would fail on account of not being able to locate the file. The script now adds the extension to the input file at the arfcorr step, avoiding this error.

If a source region is entered in a format which is not supported by CIAO, the script will exit since the tools it invokes will determine that the region contains zero counts. In this case, the script now catches the error and exits nicely.

Changes in the December 2011 Release

There is a new 'binarfwmap' parameter tied to the new 'bin' parameter of the sky2tdet tool, to allow users to change the binning of the WMAP used to create weighted ARFs (in previous releases, the binning was hardcoded to a value of 1). This parameter is helpful to users who run up against mkwarf's memory limit when they input large source regions to specextract with 'weight=yes'; setting the ARF WMAP binning to a value greater than 1 works around this issue.

File input parameters were updated to support the following null values, in addition to "": "NONE", "none", "None".

Changes in the February 2012 Release

A bug was fixed which caused the script to exit in error when the 'outroot' parameter contained a stack, and 'weight=no' and 'correct=yes'.

Bugs

Caveats

The same asp, pbkfile, and mask files are used for source and background responses  (28 Dec 2010)

The script assumes that corresponding items in the source and background stack are defined from the same event file, and uses the specified asp, pbkfile, and mskfile files for creating both the source and background responses.

For example, if the input command includes:

specextract infile="file1.fits[sky=region(i.reg)],file2.fits[sky=region(i.reg)]" \
bkgfile="file1.fits[sky=region(bg.reg)],file2.fits[sky=region(bg.reg)]" \
asp="asphist1.fits,asphist2.fits" outroot="src_i" 

The "asphist1.fits" file is used in creating both the source and background WMAP files:

sky2tdet
"file1.fits[sky=region(i.reg)][energy=300:2000][bin
sky=1]" asphist1.fits "src1_tdet.fits[wmap]" clobber=yes

sky2tdet
"file1.fits[sky=region(bg.reg)][energy=300:2000][bin
sky=1]" asphist1.fits "bkg1_tdet.fits[wmap]" clobber=yes

Users who wish to define the source and background from different event files will need to run the script twice to do so.

Remember that if you plan on subtracting the background, then you do not need to create a background RMF and ARF. You may simply use dmextract to create the spectrum. In this case, leave the bkgfile parameter blank so that specextract will only create the source spectrum and responses.

The mkwarf tool may run out of memory for large regions.
# mkwarf (CIAO): dsALLOCERR -- ERROR: Could not allocate memory.  (15 Dec 2011)

If a weighted ARF is being created for a large region, on order of a full chip (or larger), mkwarf may hit the intrinsic memory limit of a 32-bit application.

Workaround:

In CIAO 4.4, there is a new specextract parameter - binarfwmap - that specifies the binning of the sky2tdet WMAP, which is used as input to mkwarf.

If you encounter this error, increase the binarfwmap value to create a coarser WMAP.

# specextract (<date>): ERROR An error occurred while running 'sky2tdet':
# sky2tdet (CIAO): ERROR: no non-null/0/nan pixels are in the input image

 (02 Mar 2012)

The most likely cause of this error is that the region and energy filter set in the energy_wmap parameter do not select any events:

unix% dmlist "evt2.fits[sky=region(ciao.reg)][energy=300:2000]" counts
0 

Workaround:

Adjust the energy_wmap value to match that of your events. The range of event energies in the region can be found with dmstat:

unix% dmstat "evt2.fits[sky=region(ciao.reg)][cols energy]"
energy[eV]
min: 2231.7507324 @: 61
max: 7980.6259766 @: 35
mean: 4012.0070413
sigma: 1252.6216735
sum: 429284.75342
good: 107
null: 0

See Also

calibration

ardlib

psf

psf

tools

acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, add_grating_orders, add_grating_spectra, addresp, asphist, combine_spectra, dither_region, dmarfadd, dmextract, eff2evt, fluximage, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, merge_all, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsf, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, rmfimg, sky2tdet