acisspec

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.

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

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