Coadding Spectra and Weighted Responses
[CIAO 3.4 Science Threads]
OverviewLast Update: 31 Mar 2008 - updated for CALDB 3.4.3: use mkacisrmf for -110 BI chips if TGAIN calibration has been applied Synopsis: Users are encouraged to use specextract in place of acisspec for new analyses, noting that specextract does not yet offer the option to coadd spectra as acisspec does; refer to the specextract thread for more information. In this thread, acisspec is used to weight the spectra for their respective exposures and (optionally) group the output spectra. It also creates weighted responses (WARF and WRMF). Purpose: To describe two ways to run the acisspec script on a point source (the zero-order source of two HETG/ACIS-S observations):
Read this thread if: you are working with an ACIS imaging observation or the 0th-order of a grating observation and would like to perform one of the analyses described in the Purpose (above).
|
Contents
- Getting Started
- Downloading acisspec
- Defining Source & Background Regions
- Calculating the Weights
- Running the Script
- Using the Ouput
- Common Warnings
- Analysis Caveats
- Parameter files:
- History
- Images
Getting Started
Sample ObsIDs used: 459 (HETG/ACIS-S, 3C 273); 2463 (HETG/ACIS-S, 3C 273)
File types needed: evt2
CALDB 3.3.0.1 patch
The CALDB 3.3.0.1 patch, released on 02 February 2007, corrects an indexing problem that may affects users of this thread. Read the Caveat: ACIS -120C FEF for CTI-corrected ACIS data for details.
Make sure that this patch has been installed in your CALDB before continuing:
unix% dmlist "$CALDB/docs/chandra/caldb_version/caldb_version.fits[cols caldb_ver,ciao_ver]" data ... 52 3.2.4 CIAO3.3.0.1 53 3.3.0 CIAO3.4 54 3.3.0.1 CIAO3.4
This file is automatically updated each time the CALDB is upgraded on your system, so the final row always indicates the current version.
Using Consistent Calibration: mkrmf vs mkacisrmf
The tool mkacisrmf is used to create RMFs for:
- all -120 ACIS data taken in (V)FAINT mode that has the time-dependent gain adjustment and CTI correction applied
- -120 ACIS GRADED mode data on the back-illuminated chips (ACIS-S1 and S3) only
- -110 ACIS data taken on the back-illuminated chips (ACIS-S1 and S3) only
All new analyses with these types of data should be done with mkacisrmf instead of mkrmf. Although this script runs mkrmf, it can still be used to create the spectrum and ARF files for the data. Then follow the Creating ACIS RMFs with mkacisrmf thread to generate new RMFs.
It is important that the calibration applied to the event file is consistent with the RMF tool chosen, as explained in the "Using Consistent Calibration" section of the why topic. If necessary, reprocess your data with the correct gain file before beginning this thread.
The ACIS dead area correction
There is a fractional area loss per unit time due to cosmic ray flux incident on the ACIS detector. Calibration to account for this ACIS "dead area" was included in CALDB 3.3.0 on 15 December 2006. The correction is non-zero for the 8 front-illuminated ACIS chips; the effect is not detectable for the BI chips, so the nominal calibration value is 0.0. The resulting chipy-dependent reduction in the EA will be approximately 2.2% at the readout, and 4.0% at the top of the chip. Refer to the ACIS Dead Area Correction why topic for technical details.
In CIAO 3.4, the application of the dead area correction is turned off by default. However, users may opt to include it in the analysis by setting the pbkfile and dafile parameters in this script. Refer to the script help file for details on these parameters.
When coadding files with acisspec it is not appropriate to apply the ACIS dead area correction. Since coadded data is provided as input to mkwarf, there is not an accurate single file to provide for the pbkfile parameter.
Downloading acisspec
The most recent version of acisspec is v4.0 (07 February 2007):
unix% grep version_ `which acisspec` version_str="4.0" version_date="07 February 2007"
Please check that you are using the most recent version before continuing. If you do not have the script installed or need to update to a newer version, please refer to the Scripts page.
Defining Source & Background Regions
First we need to define regions from which the source and background spectra will be created. The same background regions are used for both files:
unix% cat src_1.reg # Region file format: CIAO version 1.0 circle(4124.75,4069,18) unix% cat src_2.reg # Region file format: CIAO version 1.0 circle(4083.54,4085.37,18) unix% cat bgd.reg # Region file format: CIAO version 1.0 circle(4119,4014.75,10) circle(4077,4025.75,10) circle(4186.5,4023.25,10) circle(4196.25,4064.5,10)
Make sure that you save the regions in CIAO format (Regions -> File Format -> CIAO) so that they are fully compatible with the analysis tools; see the Using CIAO Regions thread for more information.
The regions are shown displayed on the event files in Figure 1 .
Calculating the Weights
In order to apply a weighting factor to the spectra before coadding them, we need to calculate the ratio of each observation's exposure to the total exposure (sum of the two).
First, find the individual exposures:
unix% dmkeypar acisf00459N002_evt2.fits EXPOSURE echo+ 38564.608926889 unix% dmkeypar acisf02463N001_evt2.fits EXPOSURE echo+ 26686.907722822
Now calculate the total exposure and the ratios:
total exposure: 38564.61+26686.91 = 65251.52 weight1: 38564.61/65251.52 = 0.59 weight2: 26686.91/65251.52 = 0.41
Running the Script
Here we give two sample runs of acisspec: one beginning at the event files and the other using spectra and WMAPs as input.
Beginning at the event files
This run of the script takes the original event files as input, creating and coadding the spectra and weighted responses. In this example, we opt to create both source and background spectra.
We need to set the input source and background files - including the regions with the appropriate DM filter - as well as the root and weight parameters:
unix% punlearn acisspec unix% pset acisspec soufile1="acisf00459N002_evt2.fits[sky=region(src_1.reg)]" unix% pset acisspec soufile2="acisf02463N001_evt2.fits[sky=region(src_2.reg)]" unix% pset acisspec bgfile1="acisf00459N002_evt2.fits[sky=region(bgd.reg)]" unix% pset acisspec bgfile2="acisf02463N001_evt2.fits[sky=region(bgd.reg)]" unix% pset acisspec root=events_3c273 unix% pset acisspec weight1=0.59 weight2=0.41
Now execute the script:
unix% acisspec Primary source file: events or spectrum (acisf00459N002_evt2.fits[sky=region(src_1.reg)]): Root name for output files (events_3c273): omit - DEC_NOM values different more than 0.000300 warning: DETNAM has different value...Merged... warning: OBJECT has different value...Merged... warning: OBSERVER has different value...Merged... warning: OBS_ID has different value...Merged... omit - RA_NOM values different more than 0.000300 omit - ROLL_NOM values different more than 1.000000 warning: SEQ_NUM has different value...Merged... warning: TITLE has different value...Merged... (messages are repeated for second file) # mkwarf (CIAO 3.4): WARNING: Input image name was "events_3c273_sou12.wmap" instead of "WMAP". Will attempt to use. ***ARDLIB warning: Filename events_3c273_sou12.wmap does not specify an extension. Assuming the first "interesting" extension. ***ARDLIB warning: Filename events_3c273_sou12.wmap does not specify an extension. Assuming the first "interesting" extension. ***ARDLIB warning: Filename events_3c273_sou12.wmap does not specify an extension. Assuming the first "interesting" extension. # mkwarf (CIAO 3.4): WARNING: Input image name was "events_3c273_bgd12.wmap" instead of "WMAP". Will attempt to use. ***ARDLIB warning: Filename events_3c273_bgd12.wmap does not specify an extension. Assuming the first "interesting" extension. ***ARDLIB warning: Filename events_3c273_bgd12.wmap does not specify an extension. Assuming the first "interesting" extension. ***ARDLIB warning: Filename events_3c273_bgd12.wmap does not specify an extension. Assuming the first "interesting" extension. Atten: grid input,"energy=0.3:11.0:0.01", is ignored as a weights file, "events_3c273_sou12.wfef", is found. Total 13 regions to be processed: --- Region #1 processed --- Region #2 processed --- Region #3 processed (clip) --- Region #11 processed --- Region #12 processed --- Region #13 processed Atten: grid input,"energy=0.3:11.0:0.01", is ignored as a weights file, "events_3c273_bgd12.wfef", is found. Total 18 regions to be processed: --- Region #1 processed --- Region #2 processed --- Region #3 processed (clip) --- Region #16 processed --- Region #17 processed --- Region #18 processed
See the Common Warnings section for an explanation of the messages printed to the screen.
Check the parameter file that was used with plist acisspec.
There are a couple things to note about this run:
-
The default values of the binwmap (det=8) and ewmap (300:2000) were used.
-
The spectra were not grouped in this case. There are four parameters that can be used to specify grouping for the source (gtype, gspec) and background (bggtype, bggspec) spectra, if desired.
You may now skip ahead to the Using the Ouput section.
Spectra and WMAPs as input
This run of the script takes source spectra as input to create and coadd the weighted spectra. When using a spectrum for either soufile parameter, it is required that the corresponding WMAP (an image of the field in detector coordinates) be supplied. This can easily be made with dmcopy; for details on this process, see the Weighting ARFs and RMFs thread, specifically the Create the WMAP: Using dmcopy section.
In this example, we opt to create only source spectra, so background WMAPs are not needed:
unix% dmcopy "acisf00459N002_evt2.fits[sky=region(src_1.reg)][energy=300:2000][bin det=8]" \ src_1.wmap unix% dmcopy "acisf02463N001_evt2.fits[sky=region(src_2.reg)][energy=300:2000][bin det=8]" \ src_2.wmap
The input spectra were created with a basic dmextract command:
unix% dmextract "acisf00459N002_evt2.fits[sky=region(src_1.reg)][bin pi]" src_1.pi unix% dmextract "acisf02463N001_evt2.fits[sky=region(src_2.reg)][bin pi]" src_2.pi
We can now set the necessary parameters:
unix% punlearn acisspec unix% pset acisspec soufile1=src_1.pi soufile2=src_2.pi unix% pset acisspec souwmap1=src_1.wmap souwmap2=src_2.wmap unix% pset acisspec root=spectra_3c273 unix% pset acisspec weight1=0.59 weight2=0.41
And execute the script:
unix% acisspec Primary source file: events or spectrum (src_1.pi): Root name for output files (spectra_3c273): omit - DEC_NOM values different more than 0.000300 warning: DETNAM has different value...Merged... warning: OBJECT has different value...Merged... warning: OBSERVER has different value...Merged... warning: OBS_ID has different value...Merged... omit - RA_NOM values different more than 0.000300 omit - ROLL_NOM values different more than 1.000000 warning: SEQ_NUM has different value...Merged... warning: TITLE has different value...Merged... # mkwarf (CIAO 3.4): WARNING: Input image name was "spectra_3c273_sou12.wmap" instead of "WMAP". Will attempt to use. ***ARDLIB warning: Filename spectra_3c273_sou12.wmap does not specify an extension. Assuming the first "interesting" extension. ***ARDLIB warning: Filename spectra_3c273_sou12.wmap does not specify an extension. Assuming the first "interesting" extension. ***ARDLIB warning: Filename spectra_3c273_sou12.wmap does not specify an extension. Assuming the first "interesting" extension. Atten: grid input,"energy=0.3:11.0:0.01", is ignored as a weights file, "spectra_3c273_sou12.wfef", is found. Total 12 regions to be processed: --- Region #1 processed --- Region #2 processed --- Region #3 processed (clip) --- Region #10 processed --- Region #11 processed --- Region #12 processed
See the Common Warnings section for an explanation of the messages printed to the screen.
Check the parameter file that was used with plist acisspec.
There are a couple things to note about this run:
Using the Ouput
In each case, the script has created a number of output files:
unix% ls events_3c273* events_3c273_bgd12.pi events_3c273_bgd12.wrmf events_3c273_sou12.wmap events_3c273_bgd12.warf events_3c273_sou12.pi events_3c273_sou12.wrmf events_3c273_bgd12.wmap events_3c273_sou12.warf unix% ls spectra_3c273* spectra_3c273_sou12.pi spectra_3c273_sou12.wmap spectra_3c273_sou12.warf spectra_3c273_sou12.wrmf
The BACKFILE, RESPFILE, and ANCRFILE header keywords have been updated in the source spectrum files:
unix% dmkeypar events_3c273_sou12.pi BACKFILE echo+ events_3c273_bgd12.pi unix% dmkeypar events_3c273_sou12.pi ANCRFILE echo+ events_3c273_sou12.warf unix% dmkeypar events_3c273_sou12.pi RESPFILE echo+ events_3c273_sou12.wrmf
Since no background spectrum was created for the second run, the BACKFILE keyword is unaffected:
unix% dmkeypar spectra_3c273_sou12.pi BACKFILE echo+ none unix% dmkeypar spectra_3c273_sou12.pi ANCRFILE echo+ spectra_3c273_sou12.warf unix% dmkeypar spectra_3c273_sou12.pi RESPFILE echo+ spectra_3c273_sou12.wrmf
When the source spectra are read into Sherpa, the background file (when applicable) and source-related responses will automatically be read in as well. The RESPFILE and ANCRFILE header keywords are not updated in the background spectrum in order to allow for background subtraction in Sherpa.
For help on fitting this data in Sherpa, follow the Fitting PHA Data thread.
Common Warnings
There are several warning messages that you may see printed to the screen during the acisspec run:
-
Originating library: ardlib
***ARDLIB warning: Filename events_3c273_sou12.wmap does not specify an extension. Assuming the first "interesting" extension.
The warning may be ignored as it does not adversely affect the output; it is explained in this FAQ.
-
Originating tool: dmmerge
omit - DEC_NOM values different more than 0.000300 warning: DETNAM has different value...Merged... warning: OBJECT has different value...Merged... warning: OBSERVER has different value...Merged... warning: OBS_ID has different value...Merged... omit - RA_NOM values different more than 0.000300 omit - ROLL_NOM values different more than 1.000000 warning: SEQ_NUM has different value...Merged... warning: TITLE has different value...Merged...
The messages are related to how the tool merges the header information in the input files. The merging_rules ahelp file explains the rules and how they affect the output file header.
-
Originating tool: mkwarf
# mkwarf (CIAO 3.4): WARNING: Input image name was "spectra_3c273_sou12.wmap" instead of "WMAP". Will attempt to use.
There are two ways to create a WMAP, with dmextract or with dmcopy; acisspec uses the dmcopy method. In this process, the primary block of the WMAP file is name EVENTS_IMAGE, as opposed to WMAP. Since we know that sources.wmap8 was created as a WMAP image (i.e. the detector coordinate system was used), the warning message can be ignored.
-
Originating tool: mkwarf
Couldn't determine chip position for pixel: (4076.500000,4052.500000) with value=3.000000. Skipping pixel
If the source is near a chip boundary, mkwarf may not be able to determine the chip location of every pixel in the WMAP. This has to do with the lack of SIM info in the image; details are available in this FAQ.
In the vast majority of cases, the number of counts ignored (i.e. the sum of the "value" of each ignored pixel) is much smaller than the total signal in the WMAP. However, this may not be the case for small regions near chip boundaries. dmstat may be used to determine the sum of all pixels in the WMAP for comparison to the sum of the ignore pixel values.
-
Originating tool: mkrmf
Atten: grid input,"energy=0.3:11.0:0.01", is ignored as a weights file, "es_1447_sou.wfef", is found.
The energy axis grid is ignored since the grid is read from the weights file. Since the value entered for the energy axis (axis1 in this case) must be syntactically correct for the tool to parse over it properly, acisspec uses "energy=0.3:11.0:0.0" as a placeholder.
Analysis Caveats
Users should be cautious about analyzing the data for sources near the edges of the ACIS CCDs.
-
For X-rays passing through the mirrors, the very bottom of each CCD is obscured by the frame store. As a result, some of the events in rows with CHIPY <= 8 are not detected. (The set of rows affected varies from CCD to CCD.) Since the CIAO tools do not compensate for this effect, the ARFs and exposure maps for sources in these regions may be inaccurate.
-
For sources within about thirty-two pixels of any edge of a CCD, the source may be dithered off the CCD during part of an observation. The aspect histogram, which is used to create ARFs and exposure maps, is designed to compensate for this effect.
-
A contaminant has accumulated on the optical-blocking filters of the ACIS detectors, as described in the ACIS QE Degradation why topic. Since there is a gradient in the temperature across the filters (the edges are colder), there is a gradient in the amount of material on the filters. (The contaminant is thicker at the edges.) Within about 100 pixels of the outer edges of the ACIS-I and ACIS-S arrays, the gradient is relatively steep. Therefore, the effective low-energy (' 1 keV) detection efficiency may vary within the dither pattern in this region. The ARF and instrument map tools are designed to read a calibration file which describes this spatial dependence.
Parameters for /home/username/cxcds_param/acisspec.par soufile1 = acisf00459N002_evt2.fits[sky=region(src_1.reg)] Primary source file: events or spectrum root = events_3c273 Root name for output files (bgfile1 = acisf00459N002_evt2.fits[sky=region(bgd.reg)]) Primary background file: events or spectrum (soufile2 = acisf02463N001_evt2.fits[sky=region(src_2.reg)]) Secondary source file: events or spectrum (bgfile2 = acisf02463N001_evt2.fits[sky=region(bgd.reg)]) Secondary background file: events or spectrum (souwmap1 = ) Primary source WMAP (bgwmap1 = ) Primary background WMAP (souwmap2 = ) Secondary source WMAP (bgwmap2 = ) Secondary background WMAP (binwmap = det=8) Binning factor for WMAPs (ewmap = 300:2000) Energy Range for WMAPs (weight1 = 0.59) Weight for the primary source spectrum (weight2 = 0.41) Weight for the secondary source spectrum (gtype = ) Source spectrum grouping type (NONE, BIN, SNR, NUM_BINS, NUM_CTS, or ADAPTIVE) (gspec = ) Source spectrum grouping specs (NONE,10,etc) (bggtype = ) Background spectrum grouping type (NONE, BIN, SNR, NUM_BINS, NUM_CTS, or ADAPTIVE) (bggspec = ) Background spectrum grouping specs (NONE,10,etc) (pbkfile = NONE) NONE, or name of the parameter block file (dafile = NONE) CALDB, NONE, or name of ACIS dead-area calibration file (clobber = no) Clobber existing file (verbose = 0) Debug Level(0-5) (mode = ql) |
Parameters for /home/username/cxcds_param/acisspec.par soufile1 = src_1.pi Primary source file: events or spectrum root = spectra_3c273 Root name for output files (bgfile1 = ) Primary background file: events or spectrum (soufile2 = src_2.pi) Secondary source file: events or spectrum (bgfile2 = ) Secondary background file: events or spectrum (souwmap1 = src_1.wmap) Primary source WMAP (bgwmap1 = ) Primary background WMAP (souwmap2 = src_2.wmap) Secondary source WMAP (bgwmap2 = ) Secondary background WMAP (binwmap = det=8) Binning factor for WMAPs (ewmap = 300:2000) Energy Range for WMAPs (weight1 = 0.59) Weight for the primary source spectrum (weight2 = 0.41) Weight for the secondary source spectrum (gtype = ) Source spectrum grouping type (NONE, BIN, SNR, NUM_BINS, NUM_CTS, or ADAPTIVE) (gspec = ) Source spectrum grouping specs (NONE,10,etc) (bggtype = ) Background spectrum grouping type (NONE, BIN, SNR, NUM_BINS, NUM_CTS, or ADAPTIVE) (bggspec = ) Background spectrum grouping specs (NONE,10,etc) (pbkfile = NONE) NONE, or name of the parameter block file (dafile = NONE) CALDB, NONE, or name of ACIS dead-area calibration file (clobber = no) Clobber existing file (verbose = 0) Debug Level(0-5) (mode = ql) |
History
14 Dec 2004 | updated for CIAO 3.2: created Using Consistent Calibration section; can be run on 0th order grating in CIAO 3.2 |
25 Feb 2005 | acisspec updated to version 3.4: better error handling (see the script update history for a complete description of the changes) |
23 Jun 2005 | CIAO 3.2.2 patch: new calibration for mkacisrmf is available; see the Using Consistent Calibration: mkrmf vs mkacisrmf section |
16 Dec 2005 | updated for CIAO 3.3: the acisspec script has been updated to version 3.5; note about specextract in the Overview |
01 Feb 2006 | added link to specextract thread |
14 Feb 2006 | correction: weight1 was given in some places as 0.58, when it should be 0.59 |
16 Feb 2006 | acisspec updated to version 3.6: improved the conditional statement for recognizing weighted vs. unweighted cases. |
05 Apr 2006 | specextract use update added to Overview |
14 Jun 2006 | corrected link in "Calibration Updates"; clarified information on GRADED mode data |
01 Dec 2006 | updated for CIAO 3.4: acisspec updated to version 3.7 (removed "punlearn mkwarf" to allow new CIAO 3.4 mkwarf parameters (asolfile, pbkfile, dafile) to be set before running the script, if desired); CIAO version in warnings |
02 Feb 2007 | updated for CALDB 3.3.0.1 patch |
26 Feb 2007 | acisspec v4.0: Dead area correction parameters added to the acisspec.par file: pbkfile and dafile (added ACIS dead area correction section). Script prints a warning if RMF should be remade with mkacisrmf. |
31 Mar 2008 | updated for CALDB 3.4.3: use mkacisrmf for -110 BI chips if TGAIN calibration has been applied |