Skip to the navigation links
Last modified: December 2009

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

acisspec

Context: tools

Synopsis

Coadd ACIS spectra and build weighted ARFs and RMFs.

Syntax

acisspec soufile1 root pbkfile [bgfile1] [soufile2] [bgfile2]
[souwmap1] [bgwmap1] [souwmap2] [bgwmap2] [binwmap] [ewmap] [weight1]
[weight2] [gtype] [gspec] [bggtype] [bggspec] [dafile] [clobber]
[verbose]

Description

The acisspec script is used to coadd ACIS spectra and create weighted ARFs and RMFs.

While it still is capable of extracting weighted ACIS spectra, this should now be done with the specextract tool instead.

`acisspec' is a script which lets the user:

  • extract ACIS PI spectra and associated WMAPs for both point-like and extended sources (and background)
  • create weighted responses (WARF and WRMF)
  • coadd or average two source (and background) ACIS PI spectra and associated WMAPs (and build weighted responses)
  • optionally group the output spectra.

The script combines the dmextract, dmtcalc, dmimgcalc, dmcopy, mkwarf, mkrmf, dmgroup and dmhedit CIAO tools.

The user supplies either event lists and extraction regions, or spectra for primary (and/or secondary) source and background. If spectra are supplied, they must be in PI space or the tool will exit with an error. Extraction regions have to be specified as part of the input event files, following the usual data-model syntax for filtering (see "ahelp dmsyntax"). WMAPs are also needed to create the weighted responses, and can be either supplied by the user or computed internally by the software for specified energy range and binning factor (in which case the primary and/or secondary input files must be event file).

Any combination of source and background primary and secondary event files and spectra can be input. If event files are input and WMAPs are not supplied, then acisspec will extract them (using the specified energy range and detector binning factor). If spectra are input, then WMAPs must be supplied, or the software will exit with an error.

If secondary files are provided, then acisspec will coadd primary and secondary spectra and WMAPs and will create weighted ARFs and RMFs for the summed spectrum. Background spectra and WMAPs are weighted accounting for different exposures and extraction-region areas (according to the HEASARC definition of the BACKSCAL keyword). Additional weights can be optionally provided for the sum.

The number of files created depends on the number of input files. It ranges from a minimum of 2 (weighted RMF and ARF for the input source spectrum and WMAP), to a maximum of 8 files, namely: source and background spectra, WMAPs, WARFs and WRMFs (when both source and background event files are provided and associated WMAPs are not supplied).

HEADER KEYWORDS FOR THE OUTPUT SPECTRA

Headers of the output spectra are edited to update a number of keywords.

  • The keywords RESPFILE and ANCRFILE in the header of the source spectrum are always updated with the weighted RMF and ARF filenames. The same keywords in the output backgorund spectra (if present) are updated with the corresponding responses filenames only if the user choose to group the background spectrum. Otherwise they are left blank.
  • The keyword BACKFILE in the source spectrum is updated with the filename of the output background spectrum (if present).
  • If secondary files are present, and primary and secondary files correspond to different ObsIds, the keyword EXPOSURE in the output coadded spectra is updated with the sum of the exposure times of the single ObsIds. Otherwise, the exposure time of primary and secondary files is propagated into the output spectra.
  • If secondary files are present, the keyword BACKSCAL of the background coadded spectrum is updated, while the keyword BACKSCAL of the source coadded spectrum is equalized to 1.

GROUPED OUTPUT SPECTRA

The user can choose to group the output source and background spectra. All the group-type options available with dmgroup (see "ahelp dmgroup" for details) are allowed. If the user choose to group the background output spectrum, then the keyword BACKFILE of the source spectrum is NOT updated with the background spectum filename, while both the RESPFILE and ANCRFILE keywords of the background spectrum are updated with the filenames of the corresponding WRMF and WARF. This is useful if the user wants to fit simultaneously source and background spectra, each with its own responses. If the user wants to fit the background-subtracted source spectrum, then the output background spectrum should NOT be grouped (i.e. the bggtype and bggspec parameters should be left blank)

CREATING RMFS

This script uses the older tool mkrmf to create the RMF files. Users who are working with CTI-corrected, -120 C data should run mkacisrmf standalone to generate new RMFs after using the script to create the spectrum and ARF files. The Creating ACIS RMFs with mkacisrmf thread has more details and shows how to run the tool.

Acisspec checks for CTI keywords in the input file headers and prints a warning if users should remake the RMF response with the mkacisrmf tool. The warnings are printed at verbosity > 0.

Example 1

acisspec soufile1="evt.fits[sky=region(sou.reg)]" root=mysource
pbkfile=acisf085493133N001_pbk0.fits dafile=CALDB

Extract a source spectrum from evt.fits using the region sou.reg. Extract the source WMAP from the same region, and with default binning factor (i.e. det=8) and energy range (i.e. 300:2000 eV). Don't make a background spectrum and don't group the output. The ACIS dead area correction will be applied to the ARF.

Example 2

acisspec soufile1="evt.fits[time=1000:2000][sky=region(sou.reg)]"
bgfile1="evt.fits[time=1000:2000][sky=region(bgd.reg)]"
soufile2=sou2.pi bgfile2=bgd2.pi souwmap2=sou2.wmap bgwmap2=bgd2.wmap
root=mysource gtype="NUM_CTS" gspec=20 pbkfile="" dafile=NONE

Extract primary source and background spectra and WMAPs from the same event file with different extraction regions. Coadd these spectra and WMAPs with the provided secondary spectra and WMAPs for source and background. Group the coadded source spectrum to contain a minimum of 20 counts in the grouped channels; do not group the coadded background spectrum.

The ACIS dead area correction is NOT applied to the ARFs because the spectra are coadded; see the "pbkfile" parameter description for details.

Parameters

name type ftype def reqd
soufile1 file input   yes
root string output   yes
pbkfile string input   yes
bgfile1 file input   no
soufile2 file input   no
bgfile2 file input   no
souwmap1 file input   no
bgwmap1 file input   no
souwmap2 file input   no
bgwmap2 file input   no
binwmap string   det=8 no
ewmap string   300:2000 no
weight1 real   1 no
weight2 real   1 no
gtype string     no
gspec string     no
bggtype string     no
bggspec string     no
dafile string input CALDB  
clobber boolean   no  
verbose integer   0  

Detailed Parameter Descriptions

Parameter=soufile1 (file required filetype=input)

Primary source file

The input may be either an event file or a spectrum.

Parameter=root (string required filetype=output)

Root name for the output files

Parameter=pbkfile (string required filetype=input)

The parameter block file, which defines ACIS pixel clocking parameters, is used in conjunction with the "dafile" parameter to apply the ACIS dead area correction.

Note that acisspec applies the same pbkfile to the source and background datasets. If this is not appropriate for your analysis, you will have to run mkwarf independently to create an ARF with the dead area correction. (In this case, make sure to "turn off" the correction during the acisspec run, i.e. pbkfile=NONE and dafile=NONE.)

In addition, it is not appropriate to apply the dead area correction when coadding files with acisspec. Since the coadded data is provided as input to mkwarf, there is not an accurate single file to provide for the pbkfile parameter.

This is a standard product of pipeline processing and is available for every observation. 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).

See "ahelp mkwarf" for more information on this parameter.

Parameter=bgfile1 (file not required filetype=input)

Primary background file

The input may be either an event file or a spectrum.

Parameter=soufile2 (file not required filetype=input)

Secondary background file

The input may be either an event file or a spectrum.

Parameter=bgfile2 (file not required filetype=input)

Secondary background file

The input may be either an event file or a spectrum.

Parameter=souwmap1 (file not required filetype=input)

Primary source WMAP

Parameter=bgwmap1 (file not required filetype=input)

Primary background WMAP

Parameter=souwmap2 (file not required filetype=input)

Secondary source WMAP

Parameter=bgwmap2 (file not required filetype=input)

Secondary background WMAP

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

Binning factor of the output WMAPs

Must be given in detector coordinates. See "ahelp dmextract", or "ahelp mkwarf" for details.

Parameter=ewmap (string not required default=300:2000)

Energy range for WMAP extraction

See "ahelp dmextract", or "ahelp mkwarf" for details.

Parameter=weight1 (real not required default=1)

Weight for the primary inputs

This weight is used for the primary source spectrum, background spectrum, and WMAPs to be coadded with the secondary source and background spectra.

Setting the value to "1" (or "1.0") creates unweighted output.

Parameter=weight2 (real not required default=1)

Weight for the secondary inputs

This weight is used for the secondary source spectrum, background spectrum, and WMAPs to be coadded with the primary source and background spectra.

Setting the value to "1" (or "1.0") creates unweighted output.

Parameter=gtype (string not required)

Source grouping type

Allowable values are NONE, BIN, SNR, NUM_BINS, NUM_CTS, and ADAPTIVE.

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

More information on grouping is available from "ahelp dmgroup".

Parameter=gspec (string not required)

Source grouping specification

A numerical value used for the grouping method. The format of the grouping specification depends on what is chosen for the gtype parameter. Here are some example gspec values for each gtype option:

  • gtype=NONE, gspec=NONE (no grouping)
  • gtype=BIN, gspec="10:40:5" (start:stop:stepsize)
  • gtype=SNR, gspec=30 (signal-to-noise value)
  • gtype=NUM_BINS, gspec=10 (number of bins)
  • gtype=NUM_CTS, gspec=30 (minimum number of counts per group)
  • gtype=ADAPTIVE, gspec=100 (counts value for low SNR regions)

More information on grouping is available from "ahelp dmgroup".

Parameter=bggtype (string not required)

Background grouping type

Allowable values are NONE, BIN, SNR, NUM_BINS, NUM_CTS, and ADAPTIVE; see the "gtype" parameter description for details. More information on grouping is available from "ahelp dmgroup".

Parameter=bggspec (string not required)

Background grouping specification

A numerical value used for the background grouping method. The format of the grouping specification depends on what is chosen for the bggtype parameter; see the "gtype" parameter description for details. More information on grouping is available from "ahelp dmgroup".

Parameter=dafile (string filetype=input default=CALDB)

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.

The parameter block file is required to scale the coefficients in the dafile. If dafile=NONE, then pbkfile=NONE is assumed.

See "ahelp mkwarf" for more information on this parameter.

Parameter=clobber (boolean default=no)

Overwrite existing output files?

Parameter=verbose (integer default=0)

Controls amount of information printed to the screen.

The verbose parameter provides debugging information.

CHANGES IN CIAO 4.0/ACISSPEC 4.1

Parameter defaults: pbkfile and dafile

The ACIS dead area correction is on by default in CIAO 4.0. The pbkfile and dafile parameter defaults have been updated to reflect this. The pbkfile parameter is now automatic (i.e. not hidden) and there is no default value. The default value of the dafile parameter has been changed to "CALDB".

kernel parameter

The "kernel" parameter was removed from dmtcalc and dmpaste in CIAO 4.0.

NOTES

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

Bugs

See the bugs page for this script 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, 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, specextract

Last modified: December 2009