Creating ACIS RMFs with mkacisrmf

ACIS GRADED Mode Data

There is limited use for mkacisrmf when working with data taken in GRADED mode.

unix% dmkeypar acis_evt1.fits DATAMODE echo+
GRADED

New gain files were released in CIAO 3.2.1 (15 December 2005) which make it possible to use mkacisrmf when creating responses for the back-illuminated chips (ACIS-S1 and S3) only. When doing so, set the gain parameter to the name of the gain file used in processing the data, which is recorded in the GAINFILE header keyword of the event file, as is shown in the Creating an RMF at a specific location example.

Responses for the front-illuminated chips in GRADED mode data should still be created by running mkrmf.

Running specextract: since calibration is only available for the two chips in GRADED mode, the specextract script will use mkrmf to create the RMF response files. If your source is on ACIS-S1 or S3, follow the instructions in the Using mkacisrmf with the specextract script section to create a new response file with mkacisrmf.

Creating an RMF at a specific location

For this case, it is assumed the user wishes to create an RMF file for a specific location on one of the ACIS CCDs, independent of a given dataset or extraction region. In such a situation, the user must explicitly supply the value of the infile and gain parameters, since the tool does not have access to any header information to determine which calibration files should be used.

First the dmkeypar tool is used to make sure that the same gain file used in the data processing is provided to mkacisrmf:

unix% dmkeypar evt2.fits gainfile echo+
/soft/ciao/CALDB/data/chandra/acis/bcf/gain/acisD2000-01-29gain_ctiN0005.fits

This event file has been reprocessed with the version 5 gain file; refer back to the Get Started section for an explanation of why this is important. If the gain file was applied in standard data processing at the CXC, the path will need to be altered for the mkacisrmf command to point to your local CALDB installation.

Choose the mkacisrmf calibration file (called a "P2_RESP" file). The P2_RESP and gain files are released in pairs of matching versions, so simply choose the file which has the same "N000x" version as the gain:

unix% ls -1 $CALDB/data/chandra/acis/cpf/p2_resp/
acisD2000-01-29p2_respN0002.fits
acisD2000-01-29p2_respN0003.fits
acisD2000-01-29p2_respN0004.fits
acisD2000-01-29p2_respN0005.fits

For this gain, acisD2000-01-29gain_ctiN0005.fits, we should use the acisD2000-01-29p2_respN0005.fits file. This is the value for the infile parameter.

Now we can run mkacisrmf. Note that when specifying the input response and gain files, the path must be included.

unix% mkacisrmf \
      infile=$CALDB/data/chandra/acis/cpf/p2_resp/acisD2000-01-29p2_respN0005.fits \
      outfile=location_rmf.fits \
      wmap=none \
      energy=0.3:10.0:0.005 \
      channel=1:1024:1 \
      chantype=PI \
      ccd_id=7 \
      chipx=645 \
      chipy=10 \
      gain=$CALDB/data/chandra/acis/bcf/gain/acisD2000-01-29gain_ctiN0005.fits 

This command creates an RMF at a position of (645, 10) in CHIP coordinates on CCD 7.

The corresponding mkrmf syntax is:

unix% mkrmf \
      infile="$CALDB/data/chandra/acis/cpf/fefs/acisD1999-09-16fef_phaN0002.fits[FUNCTION][ccd_id=7,chipx=257:288,chipy=353:384]" \
      outfile=3c273.rmf axis1="energy=0.1:11.0:0.01" axis2="pi=1:1024:1"

Creating an RMF to match an extracted spectrum

This method is the recommended way of constructing RMFs with mkacisrmf.

In this scenario, the user has extracted a spectrum from a given region using dmextract and wishes to compute a matching RMF. For example:

unix% dmextract \
      "data_evt2.fits[(x,y)=circle(4232,3289,30)][bin pi=1:1024:1]" \
      test_src_pi.fits  wmap="det=8"

unix% mkacisrmf infile=CALDB \
      outfile=test_wrmf.fits \
      energy=0.3:9.5:0.005 \
      channel=1:1024:1 \
      chantype=PI \
      wmap=test_src_pi.fits \
      gain=CALDB

The energy range is chosen as 0.3:9.5:0.005 in order to avoid an error from mkwarf later in the analysis; see the mkwarf bugs page for details.

These commands extract a spectrum from within the indicated region and create a weighted RMF appropriate for that region. Here, the wmap option in the call to dmextract creates a weight map (see the documentation for dmextract) which mkacisrmf will use to create a counts-weighted RMF over the extraction region. The infile parameter is set to "CALDB" and mkacisrmf uses the information in the header of the input wmap file to determine the P2_RESP calibration file to use.

Similarly, the gain parameter should be set to "CALDB" in order to ensure that the gain file which matches the P2_RESP file is used. By using the CALDB value for the infile parameter, mkacisrmf will automatically select the appropriate file.

If you prefer, it is always acceptable to give a full path to the gain file in the CALDB, e.g.

unix% pset mkacisrmf \
      gain=$CALDB/data/chandra/acis/bcf/gain/acisD2000-01-29gain_ctiN0005.fits

The corresponding mkrmf syntax is:

unix% mkrmf infile=CALDB outfile=sources.wrmf \
      axis1="energy=0:1" axis2="pi=1:1024:1" weights=sources.wgt

Using mkacisrmf with the specextract script

specextract, a new script for creating ACIS spectra, was released in CIAO 3.3 (21 November 2005). The major feature is the script's ability to determine when mkacisrmf should be used in place of mkrmf.

specextract reads the source and background file header keywords to determine when the observation was taken and what calibration has been applied. The script then does a CALDB lookup to compare the calibration applied to the event file and the most recent file available in the CALDB. This means that the data needs to have been processed with the very newest calibration, not just a "good enough" version; that is, even if the new calibration will have a minimal effect on your data, specextract requires that it be applied for the "use mkacisrmf" switch to be triggered.

Users who don't wish to reprocess can still use specextract, and run mkacisrmf afterwards to create a new RMF file. This approach is also appropriate for users who have run specextract on GRADED mode data, and want to create an RMF for a source on ACIS-S1 or S3.

unix% dmkeypar acis_evt2.fits GAINFILE echo+
acisD2000-01-29gain_ctiN0004.fits

Since this file has an older CTI-corrected gain file applied, specextract used mkrmf to create the RMFs. The version 4 calibration is sufficient for mkacisrmf, though, so we run the tool independently of the script to create a new response file.

Choose the mkacisrmf calibration file (called a "P2_RESP" file). The P2_RESP and gain files are released in pairs of matching versions, so simply choose the file which has the same "N000x" version as the gain:

unix% ls -1 $CALDB/data/chandra/acis/cpf/p2_resp/
acisD2000-01-29p2_respN0002.fits
acisD2000-01-29p2_respN0003.fits
acisD2000-01-29p2_respN0004.fits
acisD2000-01-29p2_respN0005.fits

For this gain, acisD2000-01-29gain_ctiN0004.fits, we should use the acisD2000-01-29p2_respN0004.fits file. This is the value for the infile parameter.

Please read the "Matching the ARF and RMF energy grids" caveat before continuing. That information applies to users who intend to use XSpec instead of Sherpa to model and fit the data.

Now we can run the tool:

unix% mkacisrmf \
      infile="$CALDB/data/chandra/acis/cpf/p2_resp/acisD2000-01-29p2_respN0004.fits" \
      outfile=acis_new_rmf.fits \
      energy=0.3:10.0:0.005 \
      channel=1:1024:1 \
      chantype=PI \
      wmap=acis_src1.pi \
      gain=$CALDB/data/chandra/acis/bcf/gain/acisD2000-01-29gain_ctiN0004.fits 

The wmap parameter is set to the source spectrum file created by specextract. The script always creates a WMAP block, so this approach will work with any specextract output. The new RMF file is name acis_new_rmf.fits.

Be sure to update the spectrum file header to contain the name of the new RMF file.

Using mkacisrmf with the psextract script

The psextract script uses the mkrmf tool to create the RMF. Users who have the correct calibration applied to the data may run mkacisrmf independently to create a new RMF.

unix% dmkeypar acis_point_evt2.fits GAINFILE echo+
acisD2000-01-29gain_ctiN0005.fits

The file has an appropriate CTI-corrected gain applied to it, so we can use mkacisrmf. First, however, we need a weight map (WMAP) for the data; mkacisrmf uses this file to create a weighted RMF over multiple response regions. The WMAP image is created by using the DM binning syntax with dmcopy:

unix% dmcopy "acis_point_evt2.fits[bin det=8]" acis_point_wmap.fits

This command creates a WMAP image in detector coordinates.

Choose the mkacisrmf calibration file (called a "P2_RESP" file). The P2_RESP and gain files are released in pairs of matching versions, so simply choose the file which has the same "N000x" version as the gain:

unix% ls -1 $CALDB/data/chandra/acis/cpf/p2_resp/
acisD2000-01-29p2_respN0002.fits
acisD2000-01-29p2_respN0003.fits
acisD2000-01-29p2_respN0004.fits
acisD2000-01-29p2_respN0005.fits

For this gain, acisD2000-01-29gain_ctiN0005.fits, we should use the acisD2000-01-29p2_respN0005.fits file. This is the value for the infile parameter.

Please read the "Matching the ARF and RMF energy grids" caveat before continuing. That information applies to users who intend to use XSpec instead of Sherpa to model and fit the data.

Now we have all the information to run the tool:

unix% mkacisrmf \
      infile="$CALDB/data/chandra/acis/cpf/p2_resp/acisD2000-01-29p2_respN0005.fits" \
      outfile=acis_point_rmf.fits \
      energy=0.3:10.0:0.005 \
      channel=1:1024:1 \
      chantype=PI \
      wmap=acis_point_wmap.fits \
      gain=$CALDB/data/chandra/acis/bcf/gain/acisD2000-01-29gain_ctiN0005.fits

The wmap parameter is set to WMAP created by dmcopy. The new RMF file is name acis_new_rmf.fits.

Be sure to update the spectrum file header to contain the name of the new RMF file.

Create the RMF first

Since mkacisrmf can change the requested grid to match the calibration data, create the RMF first and then use it to define the energy grid when creating the ARF. This will work for both mkarf and mkwarf:

unix% pset mkarf \
      engrid="grid(sources_ciao32.wrmf[cols ENERG_LO,ENERG_HI])"

or

unix% pset mkwarf \
      egridspec="grid(sources_ciao32.wrmf[cols ENERG_LO,ENERG_HI])"

Match an existing ARF

If the specextract, psextract or acisspec scripts were used, you already have an ARF file for the data. Rather than remake both the RMF and ARF, get the grid information from the history in the ARF file:

unix% dmhistory acis_src1.warf tool=all
# dmhistory (CIAO3.3): WARNING: Found "pixlib" library parameters

# dmhistory (CIAO3.3): WARNING: Found "ardlib" library parameters

mkwarf infile="acis_src1.[WMAP]" outfile="acis_src1.warf" weightfile="acis_src1.wfef" spectrumfile=""
egridspec="0.3:9.5:0.01" threshold="0" feffile="CALDB" mskfile="" mirror="HRMA" 
detsubsysmod="" ardlibpar="ardlib" geompar="geom" clobber="no" verbose="2"  

Your file may have been created with mkarf instead of mkwarf; the dmhistory tool=all will show the tool used in either case.

Use the egridspec value (or engrid in the mkarf case) as input for the energy parameter in mkacisrmf:

unix% pset mkacisrmf energy="0.3:9.5:0.01"