Last modified: 7 Feb 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/pointlike/

Extract Spectrum and Response Files for a Pointlike Source

CIAO 4.15 Science Threads


Overview

Synopsis:

Using a combination of CIAO tools, we extract source and optionally background spectra for a pointlike source. The spectrum is grouped, if desired. The appropriate Response Matrix Files (RMFs) and Ancillary Response Files (ARFs) are created.

The specextract script automates these steps for extended and pointlike sources.

[CAUTION]
Warm ACIS observations taken after 2022-11-01

Due to on going thermal challenges, some ACIS observations will be taken with the focal plane temperature, FP_TEMP, warmer than the currently calibrated high temperature limit of -109 C (164.15 K). Use the following command to get the median FP_TEMP in degrees Kelvin for the observation:

unix% dmkeypar acis_repro_evt2.fits FP_TEMP echo+
170.2

Users fitting ACIS imaging spectra that fulfill all the following three conditions may see line-centroids shifted by 1-2% from systematic offsets due to calibration uncertainty:

  1. Spectra with more than 1000 counts on a front-illuminated (FI) chip or more than 2000 counts on a back-illuminated (BI) chip (CCD_ID 5,7).
  2. More than half of source counts were acquired above the current temperature limit of -109 C.
  3. More than half of source counts are in emission or absorption lines.

Under these conditions, users may benefit from trying to identify time periods when the focal plane temperature was within the currently calibrated range, below -109C, using the following thread: Removing Warm ACIS Data.

Purpose:

To generate source and, optionally, background spectra of a pointlike source and build the proper RMFs and ARFs.

Related Links:

Last Update: 7 Feb 2022 - Review for CIAO 4.14. Updated for Repro-5 and CALDB 4.9.6


Contents


Get Started

Download the sample data: 13858 (ACIS, SDSS J091449.05+085321.1)

Users are strongly encouraged to reprocess data retrieved from the archive using the chandra_repro script to apply the latest calibrations consistent with the current versions of CIAO and the CALDB.

unix% chandra_repro 13858 outdir=""

Build Source and Background Regions

We need to define two regions, one for the source and another for the background. To do this, first display the image:

unix% ds9 acisf13858_repro_evt2.fits 

A circular region is used for the on-axis point source and an annulus (drawn with a dashed line) is used for the optional background region.

Figure 1: Extraction regions on the event file

[Thumbnail image: The circular source region with the disjoint background annulus.]

[Version: full-size]

[Print media version: The circular source region with the disjoint background annulus.]

Figure 1: Extraction regions on the event file

A circular region is used for the source. A co-located, disjoint annulus is used for the background. Generally, the background should be extracted from a region near the source.

The source and background regions are saved into separate region files: src.reg and bkg.reg. These can be saved in either CIAO or ds9 format in either physical or WCS coordinates.

The resulting region files will look like:

unix% cat src.reg
# Region file format: DS9 version 4.1
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
fk5
circle(9:14:49.090,+8:53:21.231,4.083")

unix% cat bkg.reg
# Region file format: DS9 version 4.1
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
fk5
annulus(9:14:49.074,+8:53:20.987,9.064",46.425") # background

Using specextract

specextract runs the following tools for the pointlike source case:

  • dmextract: to extract source and (optionally) background spectra. This tool also creates the WMAP used as input to mkacisrmf.
  • mkarf: to create ARF(s).
  • arfcorr: to apply an energy-dependent point-source aperture correction to the source ARF file.
  • mkrmf or mkacisrmf: to build the RMF(s), depending on which is appropriate for the data and the calibration; see the Creating ACIS RMFs why topic for details.
  • dmgroup: to group the source spectrum and/or background spectrum.
  • dmhedit: to update the BACKFILE, RESPFILE and ANCRFILE keys in the source and background spectrum files.

1. Run the script

specextract can determine the ancillary files (aspect solution, bad pixel, mask) from the header of the event file, which means that you only need give the source file, output directory, and possibly background file:

unix% punlearn specextract
unix% pset specextract infile="acisf13858_repro_evt2.fits[sky=region(src.reg)]"
unix% pset specextract bkgfile="acisf13858_repro_evt2.fits[sky=region(bkg.reg)]"
unix% pset specextract outroot=SDSSJ091449.05+085321
unix% pset specextract correctpsf=yes
unix% pset specextract weight=no

The weight parameter is set to "no" to tell the script to make a pointlike ARF and the correctpsf parameter is set to "yes" so that arfcorr will be run to correct the ARF. These must be changed since the default behavior is weight=yes and correctpsf=no.

Running the tool is then just:

unix% specextract
Source event file(s) (acisf13858_repro_evt2.fits[sky=region(src.reg)]): 
Output directory path + root name for output files (SDSSJ091449.05+085321): 
Running specextract
Version: 18 November 2021

Using event file acisf13858_repro_evt2.fits[sky=region(src.reg)]

Aspect solution file pcadf13858_000N001_asol1.fits found.

Bad-pixel file acisf13858_repro_bpix1.fits found.

Mask file acisf13858_000N002_msk1.fits found.

Setting bad pixel file 

Converting source region to physical coordinates 

Extracting src spectra 

Creating src ARF 

Calculating aperture correction for src ARF 

Creating src RMF 

Using mkacisrmf...

Grouping src spectrum 

Updating header of SDSSJ091449.05+085321.pi with RESPFILE and ANCRFILE keywords.

Updating header of SDSSJ091449.05+085321_grp.pi with RESPFILE and ANCRFILE keywords.

Setting bad pixel file 

Extracting bkg spectra 

Creating bkg ARF 

Creating bkg RMF 

Using mkacisrmf...

Updating header of SDSSJ091449.05+085321_bkg.pi with RESPFILE and ANCRFILE keywords.

Updating header of SDSSJ091449.05+085321.pi with BACKFILE keyword.

Updating header of SDSSJ091449.05+085321_grp.pi with BACKFILE keyword.

The lines in bold indicate the ancillary files that have been picked up automatically. The contents of the parameter file may be checked with plist specextract.

[NOTE]
Note

If you want more details on what the script is doing, set verbose=2 before running specextract.

How does specextract determine the center?

Users can supply specextract an arbitrary region: eg circle, ellipse, polygon, or even a mask. Since only the most basic, simple shapes (circle, ellipse, box) have a defined center, specextract must compute the center from the infile. With weight=no, specextract computes the location of the source center by identifying the location of the brightest pixel in an image of the source region. Essentially

dmstat "acisf13858_repro_evt2.fits[sky=region(src.reg)][bin sky=2]"
pget dmstat out_max_loc

The data are always binned by a factor of 2 which corresponds to 1 pixel = 2*0.492 arcsec for ACIS.

[NOTE]
Note

This is different than the centroid algorithm shown below in the Step-By-Step section.

In specextract, the center of the region is used when

This algorithm is appropriate for the majority of users, especially those looking at point-like sources. Typically point-like regions are centered on the brightest pixel and are large enough enclose a significant fraction of the PSF (over 90%).

However, for users who have intentionally offset their source region from the brighest pixel and|or those who are using small source regions which includes a lower PSF fraction (below 90%), the results of the PSF correction may be incorrect. For example, this could happen in a crowded field with multiple overlapping sources when trying to extract the spectrum from a nearby, fainter source. Users in this situation should set the refcoord to the desired center location, for example:

unix% pset specextract refcoord="9:14:49.090,+8:53:21.231"

When refcoord is set with weight=no, it will override the brightest-pixel location when computing ARF, selecting the FEF, and when computing the PSF correction.

Ancillary files

If you want to explicitly give the location of the ancillary files then, in this case, you would add the following before the call to specextract (note that the asp parameter accepts a stack for those observations with multiple aspect solution files):

unix% pset specextract asp=pcadf13858_000N001_asol1.fits

or

unix% pset specextract asp=@acisf13858_asol1.lis

and for the other files:

unix% pset specextract mskfile=acisf13858_000N002_msk1.fits
unix% pset specextract badpixfile=acisf13858_repro_bpix1.fits

Background responses

The above call created an ARF and RMF for the background region; if you only intend to subtract the background, rather than fitting it, you do not need these responses and can save some time by setting bkgresp=no when running specextract.

If responses are created for the background region, they should use the weight=yes and weight_rmf=yes settings used to create the source responses.

Grouping the output spectra

We choose to use the default grouping values: the source spectrum will be grouped to a minimum number of 15 counts per new channel and the background spectrum will be ungrouped. The grouptype and binspec parameters are used to specify the source spectrum grouping, and the bkg_grouptype and bkg_binspec parameters specify the background spectrum grouping.


2. Examining the 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 this case, the output files are:

SDSSJ091449.05+085321.pi            ungrouped source spectrum
SDSSJ091449.05+085321.arf           source ARF, no PSF corrections
SDSSJ091449.05+085321.corr.arf      source ARF, with PSF corrections applied
SDSSJ091449.05+085321.rmf           source RMF
SDSSJ091449.05+085321_grp.pi        grouped source spectrum

SDSSJ091449.05+085321_bkg.pi        background spectrum
SDSSJ091449.05+085321_bkg.arf       background ARF
SDSSJ091449.05+085321_bkg.rmf       background RMF

Read the analysis caveats before proceeding to fitting the spectrum.

This completes this thread. The next sections shows the individual steps used by spexectract.


Step-by-Step Guide

This section explains how to manually run the analysis steps that are used by specextract.

The source and background extractions are shown separately.

1. Extract Source Spectra

In this example, we extract the spectra in the standard pulse invariant (PI) channels. This creates a histogram of number of counts vs. PI channel:

unix% pset dmextract infile="acisf13858_repro_evt2.fits[sky=region(src.reg)][bin pi]" 
unix% pset dmextract outfile=step_by_step.pi 
unix% pset dmextract op=pha1
unix% dmextract
Input event file  (acisf13858_repro_evt2.fits[sky=region(src.reg)][bin pi]): 
Enter output file name (step_by_step.pi): 

You can check the parameter file that was used with plist dmextract.

Setup ardlib.par (acis_set_ardlib)

Badpixel and bad column information is stored the bpix1.fits file. This file is used by several tools and is accessed via the ardlib.par parameter file. When working with single datasets chandra_repro will, by default, automatically setup the ardlib.par file with the correct bad pixel file. However, if other observations have been recalibrated, then the ardlib.par file may not be pointing to the correct files.

unix% punlearn ardlib
unix% acis_set_ardlib acisf13858_repro_bpix1.fits absolute=no
Updated ardlib parameter file: /home/user/cxcds_param4/ardlib.par
  AXAF_ACIS0_BADPIX_FILE -> CALDB
  AXAF_ACIS1_BADPIX_FILE -> CALDB
  AXAF_ACIS2_BADPIX_FILE -> CALDB
  AXAF_ACIS3_BADPIX_FILE -> CALDB
  AXAF_ACIS4_BADPIX_FILE -> CALDB
  AXAF_ACIS5_BADPIX_FILE -> acisf13858_repro_bpix1.fits[BADPIX5]
  AXAF_ACIS6_BADPIX_FILE -> acisf13858_repro_bpix1.fits[BADPIX6]
  AXAF_ACIS7_BADPIX_FILE -> acisf13858_repro_bpix1.fits[BADPIX7]
  AXAF_ACIS8_BADPIX_FILE -> acisf13858_repro_bpix1.fits[BADPIX8]
  AXAF_ACIS9_BADPIX_FILE -> CALDB

More details about this process can be found in the Setting the Observation-specific Bad Pixel Files thread.

Locate Centroids (dmstat and dmcoords)

Since the calibration varies across the chips, we need to locate the centroid (in chip coordinates) of the source. This information is needed to create the ARFs, as well as to select which FEF (FITS Embedded Function) to use in calculating the RMFs with mkrmf.

First we determine the centroid of the source region in sky coordinates

unix% dmstat "acisf13858_repro_evt2.fits[sky=region(src.reg)][bin sky=1]" centroid=yes
EVENTS_IMAGE(x, y)
    min:	0 	      @:	( 4101.6360734 4108.1609418 )
    max:	489 	      @:	( 4104.6360734 4116.1609418 )
cntrd[log] :	( 8.8409350057 8.6539338655 )
cntrd[phys]:	( 4090.7813681 4077.6010666 )
   good:	218 
   null:	71 

and then convert that into CHIP coordinates

unix% punlearn dmcoords
unix% dmcoords acisf13858_repro_evt2.fits op=sky x=4090.7813681 y=4077.6010666
unix% pget dmcoords chip_id chipx chipy
7
206.9115965134037
517.9529717523046

You can check the parameter files for these commands with plist dmstat and plist dmcoords.

The centroid of the source region is (x,y)=(4104.477,4115.815) in sky coordinates which is located on ACIS-7, aka ACIS-S3, at (chipx,chipy)=(207,517).


2. Calculate the RMFs

The observation used in this thread was taken at the -120 C focal plane temperature and the source is on ACIS-7, a back-illuminated chip. Therefore, it is possible to use mkacisrmf to create the RMF file.

The syntax for both mkacisrmf and mkrmf are given in this section. The only datasets which require using mkrmf are datasets taken at warm focal plane temperatures (above -110C) which occurred early in the mission (in 1999 and very early in 2000).

Using mkacisrmf (mkacisrmf)

The mkacisrmf why topic has more details on using the mkacisrmf tool.

For the source:

unix% pset mkacisrmf infile=CALDB
unix% pset mkacisrmf wmap=none
unix% pset mkacisrmf obsfile=acisf13858_repro_evt2.fits
unix% pset mkacisrmf ccd_id=7 chipx=207 chipy=517
unix% pset mkacisrmf chantype=PI channel=1:1024:1 energy=0.3:11.0:0.01
unix% pset mkacisrmf outfile=step_by_step.rmf 
unix% mkacisrmf
scatter/rsp matrix file (CALDB): 
RMF output file (step_by_step.rmf): 
WMAP file (none): 
energy grid in keV (lo:hi:bin) (0.3:11.0:0.01): 
channel grids in pixel (min:max:bin) (1:1024:1): 
channel type (PI|PHA) (PI): 
filter CCD-ID (0:9) (7): 
filter chipx in pixel (207): 
filter chipy in pixel (517): 
gain file (CALDB): 


Single region, #1233 , processed.

You can check the parameter file that was used with plist mkacisrmf.

If you use mkacisrmf to create the RMFs, you can now continue to the Calculate the ARFs step.

Using mkrmf (acis_fef_lookup, mkrmf)

First acis_fef_lookup is needed to determine the correct input calibration file called FITS Embedded Functions or FEFs. For the source:

unix% pset acis_fef_lookup infile=acisf13858_repro_evt2.fits 
unix% pset acis_fef_lookup chipid=7 chipx=207 chipy=517
unix% acis_fef_lookup
Source file (event or spectrum) (acisf13858_repro_evt2.fits): 
ACIS chip number (none|NONE|0|1|2|3|4|5|6|7|8|9) (7): 
ACIS chip x coordinate (1:1024) (207): 
ACIS chip y coordinate (1:1024) (517): 
/soft/ciao-4.8/CALDB/data/chandra/acis/fef_pha/acisD2000-01-29fef_pha_ctiN0004.fits[FUNCTION][ccd_id=7,chipx=193:224,chipy=513:544]

You can check the parameter file that was used with plist acis_fef_lookup.

Now that we have the FEFs, we can compute RMFs with mkrmf. It is important that the axes are defined correctly. The energy range (keV) for axis1 should cover the detector response range, which is ~0.2-12 keV for ACIS-S. The standard extraction in PI space is axis2=1:1024:1

unix% pset mkrmf infile=")acis_fef_lookup.outfile" 
unix% pset mkrmf axis1=energy=0.3:11.0:0.01
unix% pset mkrmf axis2=pi=1:1024:1
unix% pset mkrmf outfile=step_by_step_fef.rmf
unix% mkrmf
name of FEF input file ()acis_fef_lookup.outfile -> /soft/ciao-4.8/CALDB/data/chandra/acis/fef_pha/acisD2000-01-29fef_pha_ctiN0004.fits[FUNCTION][ccd_id=7,chipx=193:224,chipy=513:544]): 
name of RMF output file (step_by_step_fef.rmf): 
axis-1(name=lo:hi:btype) (energy=0.3:11.0:0.01): 
axis-2(name=lo:hi:btype) (pi=1:1024:1): 

The syntax ")acis_fef_lookup.outfile" is a form of parameter-redirection that allows one parameter file to use the value from another parameter file. More information can be found in the parameter file help file.

You can check the parameter file that was used with plist mkrmf.


3. Calculate the ARFs

Compute the Aspect Histogram (asphist)

We now need to create the aspect histogram, which is a binned representation of aspect motion during the observation.

The aspect histogram uses the information about the Good Time Intervals (GTI) from the event file. Since there are multiple GTIs, one set for each CCD_ID, we need to filter the event file with the correct CCD_ID filter to select the correct GTI.

unix% pset asphist infile=pcadf13858_000N001_asol1.fits
unix% pset asphist evtfile="acisf13858_repro_evt2.fits[ccd_id=7]" 
unix% pset asphist outfile=asp7.hist
unix% asphist
Aspect Solution List Files (pcadf13858_000N001_asol1.fits): 
Aspect Histogram Output File (asp7.hist): 
Event List Files (acisf13858_repro_evt2.fits[ccd_id=7]): 

You can check the parameter file that was used with plist asphist.

[NOTE]
Note

There may sometimes be more than one aspect solution file (pcad_asol1.fits) for an observation. All the files must be input to the infile parameter, either as a list or as a stack.

Compute the ARFs (mkarf)

The sourcepixelx and sourcepixely were found in the Locate Centroids step. The energy grid (engrid) must be the same as that used in the RMF.

To obtain an accurate ARF at the very edge of a CCD, subarray or window, it is necessary to include the mask file (msk1.fits).

unix% punlearn mkarf
unix% pset mkarf asphistfile=asp7.hist
unix% pset mkarf sourcepixelx=4090.7813681 sourcepixely=4077.6010666
unix% pset mkarf engrid=0.3:11.0:0.01
unix% pset mkarf obsfile=acisf13858_repro_evt2.fits
unix% pset mkarf detsubsys="ACIS-7"
unix% pset mkarf maskfile=acisf13858_000N002_msk1.fits
unix% pset mkarf outfile=step_by_step_mkarf.arf
[NOTE]
pbkfile

Please see the Watch Out page for a discussion of the pbkfile parameter file change.

[NOTE]
Gratings

mkarf can also be used to create the ARF for the 0th order grating response. Users need to specify the grating parameter to match their observation.

Run mkarf for the source:

unix% mkarf
Aspect Histogram File (asp7.hist): 
Output File Name (step_by_step_mkarf.arf): 
Source X Pixel (4090.7813681): 
Source Y Pixel (4077.6010666): 
Energy grid spec (0.3:11.0:0.01): 
Name of fits file with obs info (evt file -- include extension) (acisf13858_repro_evt2.fits): 
Verbosity (0:5) (0): 
Detector Name (ACIS-7): 
Grating for zeroth order ARF (NONE|LETG|HETG) (NONE): 
NONE, or name of ACIS window mask file (acisf13858_000N002_msk1.fits): 
NONE, or the name of the parameter block file (): 

You can check the parameter file that was used with plist mkarf.

Correct the Source ARF (arfcorr)

arfcorr calculates the energy-dependent point-source aperture correction (PSF fraction) for the source and applies the correction to the ARF file.

The (x,y) position used when running mkarf is input to arfcorr, as is the extraction region used for the source spectrum. An input image is required to set the size and scale of the PSF image that will be generated.

unix% pset arfcorr infile="acisf13858_repro_evt2.fits[sky=region(src.reg)][bin sky]"
unix% pset arfcorr region="region(src.reg)"
unix% pset arfcorr x=4090.7813681 y=4077.6010666
unix% pset arfcorr arf=step_by_step_mkarf.arf
unix% pset arfcorr outfile=step_by_step_corrected.arf
unix% arfcorr
input image file (acisf13858_repro_evt2.fits[sky=region(src.reg)][bin sky]): 
input ARF (step_by_step.warf): 
output PSF image or PSF_FRAC table (step_by_step_corrected.arf): 
source region (region(src.reg)): 
image centroid, sky x coordinate (4090.7813681): 
image centroid, sky y coordinate (4077.6010666): 

The output file, step_by_step_corrected.arf, is a copy of the input ARF with two column changes:

  • an additional column, "PSF_FRAC", lists the fraction of PSF counts within the input region at each energy (i.e., the ECF at each energy).
  • the "SPECRESP" column values have been multiplied by the PSF_FRAC value, resulting in column values of effective area scaled by the ECF.

You can check the parameter file that was used with plist arfcorr.


4. Update the Spectrum Files

Group the Source Spectrum (dmgroup)

The source spectrum is grouped to have a minimum number of 15 counts per new channel:

unix% punlearn dmgroup
unix% pset dmgroup infile=step_by_step.pi
unix% pset dmgroup outfile=step_by_step_grp.pi
unix% pset dmgroup grouptype=NUM_CTS 
unix% pset dmgroup grouptypeval=15
unix% pset dmgroup xcolumn=channel
unix% pset dmgroup ycolumn=counts
unix% dmgroup
Input dataset name (step_by_step.pi): 
Output dataset name (step_by_step_grp.pi): 
Grouping type (NONE|BIN|SNR|NUM_BINS|NUM_CTS|ADAPTIVE|ADAPTIVE_SNR|BIN_WIDTH|MIN_SLOPE|MAX_SLOPE|BIN_FILE) (NUM_CTS): 
Grouping type value (15): 
Binning specification (): 
Name of x-axis (channel): 
Name of y-axis (counts): 

Update File Headers (dmhedit)

Finally, update the appropriate header keywords in the both the ungrouped and grouped source PHA files.

unix% punlearn dmhedit
unix% dmhedit step_by_step.pi filelist="" operation=add key=ANCRFILE value=step_by_step_corrected.arf 
unix% dmhedit step_by_step.pi filelist="" operation=add key=RESPFILE value=step_by_step.rmf

unix% dmhedit step_by_step_grp.pi filelist="" operation=add key=ANCRFILE value=step_by_step_corrected.arf 
unix% dmhedit step_by_step_grp.pi filelist="" operation=add key=RESPFILE value=step_by_step.rmf

This allows modeling and fitting applications such as sherpa to automatically locate and load the correct response files when the data set are read in.


Background

[NOTE]
Note

Earlier versions of this thread created response files using the same tools/logic as for a point source. However, given that the background is generally extracted over a large region, the background responses should be created using the same steps as for an extended source.

1. Is background spectrum necessary?

Before extracting the background spectrum and optionally creating background response files, users should consider if that is really necessary for their specific analysis. For the on-axis point-source case covered by this thread, the source region is expected to be small. Given the Chandra background count rates, the expected number of background counts in that small region is often going to be negligible. If the counts in the source region is large, then it is often the case that the background can simply be ignored. Similarly, if the counts in the source region are low, then the source error bars may be large enough such that including the background or omitting it may yield statistically indistinguishable results. The only way to tell whether the background is important or not may be to do the analysis both ways.

The next question is then whether the background response files are needed. If the analysis approach is to simply subtract the background (properly scaled for area and exposure), then there is no need to create background response files. When subtracting, the underlying assumption is that the events in the background region have the same response as the background events in the source region. Therefore the events in the background region and the background events in the source region share the same response files. When modeling and fitting and using subtract, the background response files are ignored.

If instead the analysis will model the background, possibly simultaneously with the source, then the background responses may be necessary. In fact depending on the complexity of the background model both the source and background responses may be necessary.


2. Extract background spectrum

The background spectrum is extracted in a similar way as the source spectrum, just using the background region.

unix% dmextract "acisf13858_repro_evt2.fits[sky=region(bkg.reg)][bin pi]" step_by_step_bkg.pi op=pha1

3. Create background ARF

[NOTE]
Note

Earlier versions of this thread suggested using mkarf. Given the large regions typically used for background extraction, the background should be considered as an extended source, rather than as a point source.

The largest difference will be in the computation of the ARF. The point-source assumptions when badpixels, columns, and chip-edges are applied could cause the mkarf to overestimate the effective area.

This thread now shows how to create weighted responses for the background region.

Aspect histogram

This step uses the aspect histogram, asp7.hist, from the source spectrum extraction part of this thread.

Create weight map for ARF

To create the weighted ARF requires a weight map (wmap). The sky2tdet tool is used to create a wmap for the events in the background region as shown here

unix% pset sky2tdet asphist=asp7.hist 
unix% pset sky2tdet infile="acisf13858_repro_evt2.fits[sky=region(bkg.reg)][energy=300:2000][bin sky]" 
unix% pset sky2tdet outfile="step_by_step_tdet_bkg.wmap[wmap]" 
unix% sky2tdet
Input image in sky (x,y) coordinates (acisf13858_repro_evt2.fits[sky=region(bkg.reg)][energy=300:2000][bin sky]): 
Input aspect histogram file (asp7.hist): 
Output TDET  WMAP file (step_by_step_tdet_bkg.wmap[wmap]): 

The [wmap] appended to the output file specifies that the output block name should be wmap. This is done for convenience to avoid some non-fatal warnings from mkwarf

You can check the parameter file that was used with plist sky2tdet.

Create background weighted ARF

unix% pset mkwarf egrid=0.3:11.0:0.01
unix% pset mkwarf mskfile=acisf13858_000N002_msk1.fits
unix% pset mkwarf infile=step_by_step_tdet_bkg.wmap
unix% pset mkwarf outfile=step_by_step_bkg.warf 
unix% pset mkwarf feffile=CALDB
unix% pset mkwarf weight=step_by_step_bkg.wghts
unix% mkwarf
Input detector WMAP (step_by_step_tdet_bkg.wmap): 
Output weighted ARF file (step_by_step_bkg.warf): 
Output FEF weights (step_by_step_bkg.wghts): 
Input Spectral weighting file (<filename>|NONE) (): 
Output energy grid [kev] (0.3:11.0:0.01): 
Parameter block file (): 

You can check the parameter file that was used with plist mkwarf.

For very large background regions, this can take a very long time to complete. Users can adjust the sky2tdet bin parameter; larger values will run faster but the fidelity of the ARF can be degraded.


4. Create background RMF

As discussed above, most users will have data that is calibrated with the mkacisrmf tool. However, some will need to use the mkrmf tool to compute the RMF. Both are shown here form completeness.

Using mkacisrmf

To create a weighted RMF with mkacisrmf also requires a WMAP. However, since the RMF is not calibrated on the same spatial scale as the ARF, users can benefit from using a more coarsely binned wmap with mkacisrmf. The wmap could have been created at the same time that the spectrum was extracted with dmextract, or can be computed on-the-fly as is shown here:

unix% pset mkacisrmf infile=CALDB
unix% pset mkacisrmf wmap="acisf13858_repro_evt2.fits[sky=region(bkg.reg)][energy=300:2000][bin tdet=8]"
unix% pset mkacisrmf obsfile=acisf13858_repro_evt2.fits
unix% pset mkacisrmf ccd_id=7 chipx=207 chipy=517   # these parameter value are required by not used
unix% pset mkacisrmf chantype=PI channel=1:1024:1 energy=0.3:11.0:0.01
unix% pset mkacisrmf outfile=step_by_step_bkg.rmf 
unix% mkacisrmf
scatter/rsp matrix file (CALDB): 
RMF output file (step_by_step_bkg.rmf): 
WMAP file (acisf13858_repro_evt2.fits[sky=region(bkg.reg)][energy=300:2000][bin tdet=8]): 
energy grid in keV (lo:hi:bin) (0.3:11.0:0.01): 
channel grids in pixel (min:max:bin) (1:1024:1): 
channel type (PI|PHA) (PI): 
gain file (CALDB): 


Total 33 regions to be processed:
    1> reg# 1135  processed
    2> reg# 1136  processed
    3> reg# 1138  processed
   ...
   33> reg# 1329  processed
[NOTE]
det or tdet?

Users are encouraged to use TDET, Tiled Detector, coordinates to create responses.

The coordinate transforms from detector coordinates, det, to a location on the chip requires using an average value for the location of the detector relative to the mirrors -- specifically the mean SIM offsets, DY_AVG, DZ_AVG, DTH_AVG. Early in the mission those values were small had small variations throughout an observation. However, as the mission progressed these values have grown large and can vary significantly from their mean values during an observation.

The coordinate transformation from tdet to chip coordinates though are independent of the SIM.

Using mkrmf

The mkwarf output weights file, weightfile, is used with mkrmf to create the RMF for those early, warm datasets that still require it. The weight input has the information mkrmf needs to automatically identify the correct FEF file and regions, so users need only specify the following:

unix% pset mkrmf infile=CALDB
unix% pset mkrmf weight=step_by_step_bkg.wghts
unix% pset mkrmf axis1=energy=0.3:11.0:0.01
unix% pset mkrmf axis2=pi=1:1024:1
unix% pset mkrmf outfile=step_by_step_fef_bkg.rmf
unix% mkrmf
name of FEF input file (CALDB): 
name of RMF output file (step_by_step_fef_bkg.rmf): 
axis-1(name=lo:hi:btype) (energy=0.3:11.0:0.01): 
axis-2(name=lo:hi:btype) (pi=1:1024:1): 

5. Updates to background files

Group background spectra

The background can be grouped independently from the source region. In the following example the data are grouped into 20-channel wide bins.

unix% pset dmgroup infile=step_by_step_bkg.pi
unix% pset dmgroup outfile=step_by_step_bkg_grp.pi
unix% pset dmgroup grouptype=BIN
unix% pset dmgroup binspec=1:1024:20
unix% pset dmgroup xcolumn=channel
unix% pset dmgroup ycolumn=counts
unix% dmgroup
Input dataset name (step_by_step_bkg.pi): 
Output dataset name (step_by_step_bkg_grp.pi): 
Grouping type (NONE|BIN|SNR|NUM_BINS|NUM_CTS|ADAPTIVE|ADAPTIVE_SNR|BIN_WIDTH|MIN_SLOPE|MAX_SLOPE|BIN_FILE) (BIN): 
Grouping type value (15): 
Binning specification (1:1024:20):
Name of x-axis (channel): 
Name of y-axis (counts): 

Update headers

The background file headers are updated to point to the RMF and ARF files

unix% dmhedit step_by_step_bkg.pi filelist="" operation=add key=ANCRFILE value=step_by_step_bkg.warf
unix% dmhedit step_by_step_bkg.pi filelist="" operation=add key=RESPFILE value=step_by_step_bkg.rmf

unix% dmhedit step_by_step_bkg_grp.pi filelist="" operation=add key=ANCRFILE value=step_by_step_bkg.warf
unix% dmhedit step_by_step_bkg_grp.pi filelist="" operation=add key=RESPFILE value=step_by_step_bkg.rmf

and then finally, the source spectrum is updated to point to the background spectrum file

unix% dmhedit step_by_step_grp.pi filelist="" operation=add key=BACKFILE value=step_by_step_bkg_grp.pi

Fitting

Below is a simple example showing how the data are loaded into sherpa to perform a basic fit.

unix% sherpa
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.9 Sherpa version 1 Friday, December 2, 2016

sherpa-1> load_data("step_by_step_grp.pi")
read ARF file step_by_step_mkarf.arf
read RMF file step_by_step.rmf
read ARF (background) file step_by_step_bkg.warf
read RMF (background) file step_by_step_bkg.rmf
read background file step_by_step_bkg_grp.pi
sherpa-2> notice(0.3,6)
sherpa-3> subtract()  
sherpa-4> set_source(xsphabs.a1*xspowerlaw.p1)
sherpa-5> fit()
Dataset               = 1
Method                = levmar
Statistic             = chi2gehrels
Initial fit statistic = 8.56767e+10
Final fit statistic   = 147.207 at function evaluation 297
Data points           = 79
Degrees of freedom    = 76
Probability [Q-value] = 1.8345e-06
Reduced statistic     = 1.93694
Change in statistic   = 8.56767e+10
   a1.nH          0.0321446    +/- 0.063568    
   p1.PhoIndex    3.14019      +/- 0.119264    
   p1.norm        0.000174434  +/- 1.02475e-05 

This fit is just shown to illustrate the commands used; the models and results are not meant to be meaningful. For a more detailed example users can read the Introduction to Fitting PHA Spectra thread.


Analysis Caveats

Users should be cautious about analyzing the data for sources near the edges of the ACIS CCDs.

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

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

  3. An ARF calculated at the edge of a chip will not be accurate since the response tools for spectral extraction (specifically the ARF) assume that 100% of the PSF is enclosed - i.e. on the chip - all the time, which may not be the case. The amount of error introduced depends on how close the source is to the edge, the morphology of the source, and the characteristics of the PSF, which depends on the source spectrum.

  4. A contaminant has accumulated on the optical-blocking filters of the ACIS detectors, as described in the ACIS QE Contamination 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.


Summary

In this thread we showed how to use specextract to extract the source spectrum for a point like source and how to extract the background spectrum. We then showed the individual steps that specextract does using dmextract, acis_fef_lookup, acis_set_ardlib, mkrmf, mkacisrmf, dmstat, dmcoords, mkarf, arfcorr, asphist, sky2tdet, mkwarf, dmgroup, and dmhedit. Finally, the data were loaded into sherpa and a simple fit was performed.



Parameters for /home/username/cxcds_param/acis_fef_lookup.par


        infile = acisf13858_repro_evt2.fits Source file (event or spectrum)
        chipid = 7                ACIS chip number
         chipx = 207              ACIS chip x coordinate
         chipy = 517              ACIS chip y coordinate
       outfile = /soft/ciao-4.8/CALDB/data/chandra/acis/fef_pha/acisD2000-01-29fef_pha_ctiN0004.fits[FUNCTION][ccd_id=7,chipx=193:224,chipy=513:544] FEF file to use
       quality = no               Should you use the FEF file (if no use mkacisrmf)?
      (verbose = 0)               Verbose level
         (mode = ql)              




Parameters for /home/username/cxcds_param/acis_set_ardlib.par


    badpixfile = acisf13858_repro_bpix1.fits Bad pixel file for the observation
 (absolutepath = yes)             Use an absolute path in the parameter file
   (ardlibfile = ardlib)          Parameter file to change
      (verbose = 1)               Verbosity (0 for no screen output)
         (mode = ql)              




Parameters for /home/username/cxcds_param/asphist.par


#--------------------------------------------------------------------------
#
#       Parameter file for the ASPECT HISTOGRAM Tool
#
#--------------------------------------------------------------------------
        infile = pcadf456520092N001_asol1.fits Aspect Solution List Files
       outfile = asp7.hist        Aspect Histogram Output File
       evtfile = acisf13858_repro_evt2.fits[ccd_id=7] Event List Files
       dtffile =                  Live Time Correction List Files for HRC
      (geompar = geom)            Parameter file for Pixlib Geometry files
       (res_xy = 0.5)             Aspect Resolution x and y in arcsec
     (res_roll = 600.)            Aspect Resolution roll in arcsec
      (max_bin = 10000.)          Maximal number of bins
      (clobber = no)              Clobber output
      (verbose = 0)               Verbose
         (mode = ql)              




Parameters for /home/username/cxcds_param/arfcorr.par


        infile = acisf13858_repro_evt2.fits[sky=region(src.reg)][bin sky] input image file
           arf = step_by_step_mkarf.arf input ARF
       outfile = step_by_step_corrected.arf output PSF image or PSF_FRAC table
        region = region(src.reg)  source region
             x = 4104.4770084     image centroid, sky x coordinate
             y = 4115.8148756     image centroid, sky y coordinate
       (energy = )                energy in keV (0 = read from ARF)
       (e_step = 50)              energy stepsize (read every 'e_step' row from ARF)
       (radlim = 2.0)             radius at which PSF artificially drops to 0 (multiplies last radius)
      (nsubpix = 5)               subpixelation (1d) of ecf model pixels to choose image pix value
     (nfracpix = 1)               subpixelation (1d) of ecf pixels when calculating psffrac
      (ecffile = ${CALDB}/data/chandra/default/reef/hrmaD1996-12-20reefN0001.fits -> /soft/ciao-4.8/CALDB/data/chandra/default/reef/hrmaD1996-12-20reefN0001.fits) ecf file
       (tmpdir = ${ASCDS_WORK_PATH} -> /tmp) Directory for temp. files
      (clobber = no)              OK to overwrite existing output file?
      (verbose = 0)               Debug level (0-5)
         (mode = ql)              




Parameters for /home/username/cxcds_param/dmcoords.par


        infile = acisf13858_repro_evt2.fits Input dataset/block specification
#
# Position of photon in different coord systems
#
       chip_id = 7                Chip ID number
         chipx = 207.6230236707885 Chip X [pixel]
         chipy = 517.8459951502056 Chip Y [pixel]
         tdetx = 4124.623023670789 TDETX [pixel]
         tdety = 2219.845995150205 TDETY [pixel]
          detx = 4109.570395890681 FPC X [pixel]
          dety = 4080.194729879038 FPC Y [pixel]
             x = 4104.4770084     Sky X [pixel]
             y = 4115.8148756     Sky Y [pixel]
      logicalx = 4104.4770084     X coordinate in binned image [pixel]
      logicaly = 4115.8148756     Y coordinate in binned image [pixel]
            ra = 09:14:49.088     RA [deg or hh:mm:ss]
           dec = +08:53:21.15     Dec [deg or dd:mm:ss]
         theta = 0.1713578455819632 Off axis angle [arcmin]
           phi = 308.7158584206837 Azimuthal angle [deg]
         order = 0                Grating order
        energy = 1                Energy [keV]
    wavelength = 0                Wavelength [A]
         ra_zo = 09:14:49.088     RA of zero order
        dec_zo = +08:53:21.15     Dec of zero order
     (asolfile = none)            Input aspect solution file
       (option = )                Conversion option
#
# Override setup for observation
# All parameters here are strings so that they can
# be set blank, in which case the data file value is used
#
       (celfmt = hms)             RA and Dec format [deg or hms] (xx.xx or xx:xx:xx.x)
     (detector = )                Detector (ACIS or HRC-I or HRC-S)
      (grating = )                Grating
        (fpsys = )                FP convention
          (sim = )                SIM position (eg 0.0 0.0 -190.6)
     (displace = )                STF displacement (X,Y,Z,AX,AY,AZ)
       (ra_nom = )                Nominal pointing RA [deg or hh:mm:ss]
      (dec_nom = )                Nominal dec [deg or dd:mm:ss]
     (roll_nom = )                Nominal roll [deg]
       (ra_asp = )                Instantaneous pointing RA [deg]
      (dec_asp = )                Instantaneous pointing Dec [deg]
     (roll_asp = )                Instantaneous Aspect roll [deg]
#
      (geompar = geom)            Parameter file for Pixlib Geometry files
      (verbose = 0)               Debug Level
         (mode = ql)              




Parameters for /home/username/cxcds_param/dmextract.par


#--------------------------------------------------------------------
#
# DMEXTRACT -- extract columns or counts from an event list
#
#--------------------------------------------------------------------
        infile = acisf13858_repro_evt2.fits[sky=region(bkg.reg)][bin pi] Input event file 
       outfile = step_by_step_bkg.pi Enter output file name
          (bkg = )                Background region file or fixed background (counts/pixel/s) subtraction
        (error = gaussian)        Method for error determination(gaussian|gehrels|<variance file>)
     (bkgerror = gaussian)        Method for background error determination(gaussian|gehrels|<variance file>)
      (bkgnorm = 1.0)             Background normalization
          (exp = )                Exposure map image file
       (bkgexp = )                Background exposure map image file
      (sys_err = 0)               Fixed systematic error value for SYS_ERR keyword
          (opt = pha1)            Output file type 
     (defaults = ${ASCDS_CALIB}/cxo.mdb -> /soft/ciao-4.8/data/cxo.mdb) Instrument defaults file
         (wmap = )                WMAP filter/binning (e.g. det=8 or default)
      (clobber = no)              OK to overwrite existing output file(s)?
      (verbose = 0)               Verbosity level
         (mode = ql)              




Parameters for /home/username/cxcds_param/dmgroup.par


        infile = step_by_step.pi  Input dataset name
       outfile = step_by_step_grp.pi Output dataset name
     grouptype = NUM_CTS          Grouping type
  grouptypeval = 15               Grouping type value
       binspec =                  Binning specification
       xcolumn = channel          Name of x-axis
       ycolumn = counts           Name of y-axis
      (tabspec = )                Tab specification
    (tabcolumn = )                Name of tab column
     (stopspec = )                Stop specification
   (stopcolumn = )                Name of stop column
    (errcolumn = )                Name of error column
      (clobber = no)              Clobber existing output file?
      (verbose = 0)               Verbosity level
    (maxlength = 0)               Maximum size of groups (in channels)
         (mode = ql)              




Parameters for /home/username/cxcds_param/dmstat.par


        infile = acisf13858_repro_evt2.fits[sky=region(src.reg)][bin sky=1] Input file specification
   out_columns = x,y              Output Column Label
       out_min = 0                Output Minimum Value
   out_min_loc = 4101.6360734,4108.1609418 Output Minimum Location Value
       out_max = 489              Output Maximum Value
   out_max_loc = 4104.6360734,4116.1609418 Output Maximum Location Value
      out_mean =                  Output Mean Value
    out_median =                  Output Median Value
     out_sigma =                  Output Sigma Value
       out_sum =                  Output Sum of Values
      out_good = 218              Output Number Good Values
      out_null = 71               Output Number Null Values
    out_cnvrgd =                  Converged?
 out_cntrd_log = 8.8409350057,8.6539338655 Output Centroid Log Value
out_cntrd_phys = 4104.4770084,4115.8148756 Output Centroid Phys Value
out_sigma_cntrd =                  Output Sigma Centroid Value
     (centroid = yes)             Calculate centroid if image?
       (median = no)              Calculate median value?
        (sigma = yes)             Calculate the population standard deviation?
         (clip = no)              Calculate stats using sigma clipping?
       (nsigma = 3)               Number of sigma to clip
      (maxiter = 20)              Maximum number of iterations
      (verbose = 1)               Verbosity level
         (mode = ql)              




Parameters for /home/username/cxcds_param/mkacisrmf.par


        infile = CALDB            scatter/rsp matrix file
       outfile = step_by_step.rmf RMF output file
          wmap = none             WMAP file
        energy = 0.3:11.0:0.01    energy grid in keV (lo:hi:bin)
       channel = 1:1024:1         channel grids in pixel (min:max:bin)
      chantype = PI               channel type
        ccd_id = 7                filter CCD-ID
         chipx = 207              filter chipx in pixel
         chipy = 517              filter chipy in pixel
          gain = CALDB            gain file
     (asolfile = )                aspect solution file or a stack of asol files
      (obsfile = acisf13858_repro_evt2.fits) obs file
      (logfile = )                log file
      (contlvl = 100)             # contour level
      (geompar = geom)            pixlib geometry parameter file
       (thresh = 1e-06)           low threshold of energy cut-off probability
      (clobber = no)              overwrite existing output file (yes|no)?
      (verbose = 0)               verbosity level (0 = no display)
         (mode = ql)              




Parameters for /home/username/cxcds_param/mkarf.par


   asphistfile = asp7.hist        Aspect Histogram File
       outfile = step_by_step_mkarf.arf Output File Name
  sourcepixelx = 4104.4770084     Source X Pixel
  sourcepixely = 4115.8148756     Source Y Pixel
        engrid = 0.3:11.0:0.01    Energy grid spec
       obsfile = acisf13858_repro_evt2.fits Name of fits file with obs info (evt file -- include extension)
#
       pbkfile =                  NONE, or the name of the parameter block file
     detsubsys = ACIS-7           Detector Name
       grating = NONE             Grating for zeroth order ARF
      maskfile = acisf13858_000N001_msk1.fits NONE, or name of ACIS window mask file
       verbose = 0                Verbosity
       (dafile = CALDB)           NONE, CALDB, or name of ACIS dead-area calibration file
#
       (mirror = HRMA)            Mirror Name
#
(ardlibparfile = ardlib.par)      name of ardlib parameter file
      (geompar = geom)            Parameter file for Pixlib Geometry files
      (clobber = no)              Overwrite existing files?
#
         (mode = ql)              Enter mode for parameter file.




Parameters for /home/username/cxcds_param/mkrmf.par


        infile = )acis_fef_lookup.outfile -> /soft/ciao-4.8/CALDB/data/chandra/acis/fef_pha/acisD2000-01-29fef_pha_ctiN0004.fits[FUNCTION][ccd_id=7,chipx=193:224,chipy=513:544] name of FEF input file
       outfile = step_by_step_fef.rmf name of RMF output file
         axis1 = energy=0.3:11.0:0.01 axis-1(name=lo:hi:btype)
         axis2 = pi=1:1024:1      axis-2(name=lo:hi:btype)
      (logfile = STDOUT)          name of log file
      (weights = )                name of weight file
       (thresh = 1e-5)            low threshold of energy cut-off probability
       (outfmt = legacy)          RMF output format (legacy|cxc)
      (clobber = no)              overwrite existing output file (yes|no)?
      (verbose = 0)               verbosity level (0 = no display)
        (axis3 = none)            axis-3(name=lo:hi:btype)
        (axis4 = none)            axis-4(name=lo:hi:btype)
        (axis5 = none)            axis-5(name=lo:hi:btype)
         (mode = ql)              




Parameters for /home/username/cxcds_param/mkwarf.par


        infile = step_by_step_tdet_bkg.wmap Input detector WMAP
       outfile = step_by_step_bkg.warf Output weighted ARF file
    weightfile = none             Output FEF weights
  spectrumfile =                  Input Spectral weighting file (<filename>|NONE)
     egridspec = 0.3:11.0:0.01    Output energy grid [kev]
       pbkfile =                  Parameter block file
    (threshold = 0)               Percent threshold cut for FEF regions
      (feffile = none)            FEF file
      (mskfile = acisf13858_000N001_msk1.fits) Mask file
     (asolfile = )                Stack of aspect solution files
       (mirror = HRMA)            ARDLIB Mirror specification
 (detsubsysmod = )                Detector sybsystem modifier
       (dafile = CALDB)           Dead area file
    (ardlibpar = ardlib)          Parameter file for ARDLIB files
      (geompar = geom)            Parameter file for Pixlib Geometry files
      (clobber = no)              Clobber existing outputs
      (verbose = 0)               Tool chatter level
         (mode = ql)              




Parameters for /home/username/cxcds_param/sky2tdet.par


        infile = acisf13858_repro_evt2.fits[sky=region(bkg.reg)][energy=300:2000][bin sky] Input image in sky (x,y) coordinates
   asphistfile = asp7.hist        Input aspect histogram file
       outfile = step_by_step_tdet_bkg.wmap[wmap] Output TDET  WMAP file
          (bin = 1)               Binning factor
      (geompar = geom)            Pixlib geometry file
      (verbose = 0)               Verbosity
      (clobber = no)              Remove existing files?
         (mode = ql)              




Parameters for /home/username/cxcds_param/specextract.par


        infile = acisf13858_repro_evt2.fits[sky=region(src.reg)] Source event file(s)
       outroot = SDSSJ091449.05+085321 Output directory path + root name for output files
      (bkgfile = acisf13858_repro_evt2.fits[sky=region(bkg.reg)]) Background event file(s)
          (asp = )                Source aspect solution or histogram file(s)
      (dtffile = )                Input DTF files for HRC observations
      (mskfile = )                Maskfile (input to mkwarf)
      (rmffile = CALDB)           rmffile input for CALDB
   (badpixfile = )                Bad pixel file for the observation
       (dafile = CALDB)           Dead area file (input to mkwarf)
      (bkgresp = yes)             Create background ARF and RMF?
       (weight = no)              Should response files be weighted?
   (weight_rmf = no)              Should RMF also be weighted?
     (refcoord = )                RA and Dec of responses?
   (correctpsf = yes)             Apply point source aperture correction to ARF?
      (combine = no)              Combine ungrouped output spectra and responses?
    (grouptype = NUM_CTS)         Spectrum grouping type (same as grouptype in dmgroup)
      (binspec = 15)              Spectrum grouping specification (NONE,1:1024:10,etc)
(bkg_grouptype = NONE)            Background spectrum grouping type (NONE, BIN, SNR, NUM_BINS, NUM_CTS, or ADAPTIVE)
  (bkg_binspec = )                Background spectrum grouping specification (NONE,10,etc)
       (energy = 0.3:11.0:0.01)   Energy grid
      (channel = 1:1024:1)        RMF binning attributes
  (energy_wmap = 300:2000)        Energy range for (dmextract) WMAP input to mkacisrmf
   (binarfcorr = 1)               Detector pixel binnning factor for (arfcorr) to determine size and scale of PSF to derive aperture corrections at each energy step.
      (binwmap = tdet=8)          Binning factor for (dmextract) WMAP input to mkacisrmf
   (binarfwmap = 1)               Binning factor for (sky2tdet) WMAP input to mkwarf
       (tmpdir = ${ASCDS_WORK_PATH} -> /tmp) Directory for temporary files
      (clobber = no)              OK to overwrite existing output file?
      (verbose = 1)               Debug Level(0-5)
         (mode = ql)              



History

14 Dec 2004 updated for CIAO 3.2: created "Using Consistent Calibration" and Downloading the Scripts sections
23 Jun 2005 CIAO 3.2.2 patch: new calibration for mkacisrmf is available; see the "Using Consistent Calibration: mkrmf vs mkacisrmf section"
15 Dec 2005 updated for CIAO 3.3: the psextract script has been updated to version 3.3 for the new asphist tool syntax; note about specextract in the Overview; default value of dmextract error and bkgerror parameters is "gaussian" (this tool is called by psextract)
01 Feb 2006 added link to specextract thread
31 Mar 2006 specextract use update added to Overview; title changed from "Extract ACIS Spectra for Pointlike Sources and Make RMFs and ARFs" to "Using psextract to Extract ACIS Spectra and Response Files for Pointlike Sources"
14 Jun 2006 corrected link in "Calibration Updates"; clarified information on GRADED mode data
25 Jul 2006 added Creating an RMF with mkacisrmf section, moved "Using Consistent Calibration: mkrmf vs mkacisrmf" section
01 Dec 2006 updated for CIAO 3.4: psextract version 3.4 (mkarf obsfile parameter is set to event file instead of asphist file); acis_fef_lookup version 1.19 (changes for CTI lookup)
02 Feb 2007 updated for CALDB 3.3.0.1 patch
26 Feb 2007 psextract v4.0 and acis_fef_lookup v1.20: Dead area correction parameters added to the psextract.par file: pbkfile and dafile (added "ACIS dead area correction section"). Script prints a warning if RMF should be remade with mkacisrmf. Several other minor code changes that don't affect the output files (see the Script History page for details).
22 Jan 2008 updated for CIAO 4.0: psextract v4.0.1 (parameter updates for applying ACIS dead area correction, which is turned on by default); acis_fef_lookup v1.21 (updated to to run under S-Lang v2; functionality is unchanged); available links updated to point to Sherpa Beta website; removed old calibration updates
31 Mar 2008 updated for CALDB 3.4.3: use mkacisrmf for -110 BI chips if TGAIN calibration has been applied
30 May 2008 psextract v4.0.3 (Unix head and tail commands replaced by pget and dmkeypar); thread images are inline
04 Aug 2008 the source and background region(s) must be confined to a single chip
02 Feb 2009 updated for CIAO 4.1: image converted to inline; acis_fef_lookup vCIAO 4.1 - 1.0 (rewritten to be compatible with CALDB 4.1); "ARDLIB warning ... Assuming the first "interesting" extension." no longer printed; updated Sherpa thread link to 4.1 version; input data must have a CTI_APP keyword
05 Mar 2009 added information about matching the ARF and RMF grids to the Creating an RMF with mkacisrmf section
06 May 2009 check the version of the CIAO scripts package instead of the individual script
21 May 2009 added explanation of why ungrouped background filename is used in the BACKFILE header keyword of the grouped source spectrum
12 Jan 2010 updated for CIAO 4.2: ObsID 459 file versions and corresponding minor changes to screen output; calibration update - the ACIS QE contamination model has been upgraded to vN0005.
15 Dec 2010 updated for CIAO 4.3: users should run arfcorr on the source ARF file (Correct the Source ARF section); new ACIS contamination calibration file
20 Jan 2011 users are encouraged to use specextract in place of the psextract script for new analyses
25 Feb 2011 updated for 25 Feb scripts package release: the asp parameter can take aspect solution files directly (don't have to run asphist make an aspect histogram first); if the bad pixel file is supplied in the badpixfile parameter, the ardlib parameters are set by the script; the mask file is applied when making unweighted ARFs (mkarf)
01 Mar 2011 CALDB 4.4.2 release: fix to the header of the ACIS QE contamination file. Prior to this release, CIAO would fail when trying to look up the contamination model correction for chips ACIS-8 (S4) and ACIS-9 (S5).
04 Apr 2011 updated for 04 Apr scripts package release: acis_fef_lookup script prints the version at verbose > 0. specextract: user is prompted for the bkgfile parameter (previously was hidden); new parameter, bkgresp, determines whether a background ARF and RMF should be created; additional changes are outlined in detail in the script release notes for 04 Apr 2011.
12 Apr 2011 updated for specextract changes in the 12 Apr scripts package release: the grating parameter in mkarf was not being set for zero-order grating data point source extraction (weight=no); bug fix - regions may be specified on the command line or in a file, i.e. "sky=circle(344,435,10)" vs. "sky=region(src.reg)".
26 Apr 2011 install version 2 of the tools package for CIAO 4.3 to fix the mkrmf bug; specextract was updated in the 25 April scripts package release, but the changes do not affect this thread
25 May 2011 expanded the creating an RMF with mkacisrmf section
07 Jun 2011 the "Step-by-Step Guide to Creating ACIS Spectra for Pointlike Sources" thread is now a section of this thread
06 Jul 2011 specextract bug fixes were released in the 07 July 2011 scripts package; required software updates are listed in Synopsis
06 Sep 2011 a specextract bug fix was released in the 06 Sep 2011 scripts package
06 Oct 2011 a specextract bug fix and a workaround for a known CIAO bug were released in the 06 Oct 2011 scripts package
15 Dec 2011 reviewed for CIAO 4.4: documentation on psextract has been removed since the script is no longer part of the scripts package.
16 Feb 2012 a specextract bug fix was released in the 16 Feb 2012 scripts package: the script will not error out if you set outroot to be a stack and have correct=yes and weight=no.
30 May 2012 corrected typo in arfcorr command.
03 Dec 2012 Review for CIAO 4.5; minor edits
07 Aug 2013 Updated for the contributed scripts 4.5.4 release: the "ancillary" files - e.g. aspect solution and bad-pixel files - can now be picked up from information in the event file (in many cases). The psextract information has been removed.
10 Dec 2013 Review for CIAO 4.6. Updated with infor relating to the deprecation of the pbkfile parameters. Added note about early observation requiring reprocessing.
03 Apr 2014 Added information about background responses and how they are affected by the response weighting parameters.
22 Dec 2014 Review for CIAO 4.7; minor edits only.
08 Dec 2016 The thread has been almost entirely re-written using a different example source. Most of the basic processing steps are the same. The background extraction section has been reworked to clarify that it is optional, but if performed should use a weighted ARF.
22 Jun 2020 A note has been added about the how specextract determines the source location and about the refcoord parameter.
07 Feb 2022 Review for CIAO 4.14. Updated for Repro-5 and CALDB 4.9.6