Jump to: Description · Examples · Parameters · Deprecation of 'pbkfile' parameter · Tool Version · Bugs · See Also

AHELP for CIAO 4.16

mkarf

Synopsis

Generate an ARF for Chandra imaging data (and grating 0th order)

Syntax

mkarf  asphistfile outfile sourcepixelx sourcepixely engrid obsfile
[pbkfile] detsubsys grating maskfile [dafile] [mirror] [ardlibparfile]
[geompar] [verbose] [clobber]

Description

`mkarf' generates an OGIP style ARF appropriate for imaging observations. The ARF gives the effective area vs. energy for a given observation and instrument configuration; it has units of [cm**(2) counts/photon]. As input, 'mkarf' requires an aspect histogram (computed by asphist) along with a file with complete header information about the observation, such as a Level 1 event file. It outputs an ARF suitable for use in a spectral analysis package such as Sherpa.

The input calibration data (detector quantum efficiencies (QE), mirror effective areas, locations of bad pixels) are obtained using a software library called ARDLIB which is also used by a number of other programs. The ARDLIB library has its own parameter file, ardlib.par, which contains a large number of parameters, of which only a few are actually used by mkarf. For most users, the ARDLIB parameter values will specify files from the calibration database. Consult the ARDLIB documentation for information about specific ardlib.par parameters.

By default, the time and spatial dependence of the ACIS QE due to the buildup of contamination on the optical blocking filter is accounted for automatically. The ACIS QE is adjusted using the current contamination model, interpolating to the observation date taken from the header of the specified 'obsfile'. Alternatively, an observation date can be specified explicitly using the ARDLIB 'TIME' qualifier on the detsubsys parameter. For more information about the ACIS filter contamination model, see the ACIS calibration web page. The contamination correction can be excluded using the ARDLIB detsubsys qualifier "CONTAM=NO".

The definition of the ARF and its use in spectral analysis are discussed by Davis (2001), ApJ, 548, 1010.

Correcting for the PSF Fraction

The ARF is computed assuming that the spectral extraction region is large enough to include the entire PSF (e.g. PSF fraction=1.0). If the spectral extraction region excludes part of the PSF, the computed effective area should include only fraction of the PSF contained in the spectral extraction region. For example, if the spectral extraction region includes only 80% of the encircled energy, the computed effective area for that extraction region should be smaller by a factor of 0.8.

The arfcorr tool determines the approximate fraction of the point spread function (PSF) enclosed by a region and corrects the ARF. It is recommended that arfcorr be run on the ARF created by mkarf. Refer to the arfcorr help file for technical information and details on when to apply the correction.

Examples

Example 1

mkarf asphistfile="acis_i3_asphist.fits[asphist]"
outfile=acis_i3_arf.fits sourcepixelx=4139 sourcepixely=4120
engrid="grid(rmf.fits[MATRIX][cols ENERG_LO,ENERG_HI])" dafile=NONE
obsfile=evt2.fits detsubsys="ACIS-I3"

Computes an ARF for the point (4139,4120) on ACIS-I3 using an energy grid from the file rmf.fits (in particular columns ENERG_LO and ENERG_HI in the MATRIX block), and writes it to acis_i3_arf.fits. The QE, accounting for the buildup of contamination on the optical blocking filter, is computed using the observation start time, TSTART, taken from the header of evt2.fits.

Example 2

mkarf asphistfile="acis_s3_asphist.fits[asphist]"
outfile=acis_s3_arf.fits sourcepixelx=4146.05 sourcepixely=4045.95
engrid="grid(s3_rmf.fits[MATRIX][cols ENERG_LO,ENERG_HI])"
obsfile=evt2.fits detsubsys=ACIS-S3 dafile=CALDB

Computes an ARF for the point (4146.0,4045.95) on ACIS-S3. The dafile parameter is set to apply the dead area correction.

Example 3

mkarf asphistfile="acis_s3_asphist.fits" outfile=acis_s3nc_arf.fits
sourcepixelx=3950 sourcepixely=4900 engrid="0.1:10.0:0.01" dafile=NONE
obsfile=evt2.fits detsubsys="ACIS-S3;CONTAM=NO"

Computes an ARF for the point (3950, 4900) on ACIS-S3. The ARDLIB qualifier CONTAM=NO means that the QE will not be corrected for absorption by the contamination layer on the optical blocking filter (the default is CONTAM=YES). The energy grid will span the range 0.1-10 keV in steps of 0.01 keV

Parameters

name	type	ftype	def	reqd
asphistfile	file	input		yes
outfile	file	output		yes
sourcepixelx	real	input		yes
sourcepixely	real	input		yes
engrid	string	input		yes
obsfile	file	input		yes
pbkfile	string	input		no
detsubsys	string	input		yes
grating	string	input	NONE	yes
maskfile	file	input	NONE	yes
dafile	string	input	CALDB
mirror	string	input	HRMA
ardlibparfile	file	input	ardlib.par
geompar	string	input	geom
verbose	integer		0
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=asphistfile (file required filetype=input)

The name of the file containing the binned aspect history in the form of an aspect histogram.

Note that each ACIS CCD has its own GTI file. This means that each chip will have its own aspect histogram file.

Parameter=outfile (file required filetype=output)

The name of the output ARF file.

Parameter=sourcepixelx (real required filetype=input)

Parameter=sourcepixely (real required filetype=input)

These parameters specify the (x,y) sky position [pixels] of the point source, in the appropriate tangent plane coordinate system for the detector.

Parameter=engrid (string required filetype=input)

Energy grid specification string. This string may specify either a file or an explicit energy grid. For example, to read a grid from the block MATRIX of an RMF file called rmf.fits, use:

"engrid=grid(rmf.fits[MATRIX][cols ENERG_LO,ENERG_HI])"

To specify an explicit grid running from 0.3 keV to 10.0 keV in 0.01 keV increment steps, use:

"engrid=0.3:10.0:0.01"

The allowed energy range for the tool is 0.224004 - 12 keV; choosing values outside this range may result in errors. Refer to the ACIS calibration pages for information on the detector calibration: https://cxc.harvard.edu/cal/Acis/index.html

Parameter=obsfile (file required filetype=input)

The name of a FITS file, such as a level 2 event file, containing keywords which specify the mission, detector, SIM offsets, start time, etc.

Parameter=pbkfile (string not required filetype=input)

Deprecated. See below.

Parameter=detsubsys (string required filetype=input)

The value of this parameter is passed to ARDLIB to select a particular detector subsystem so that the appropriate QE can be computed. It specifies the specific device (e.g. the specific chip or MCP of the detector) for which the ARF is to be computed. For Chandra, it must specify one of the following detector subsystems:

HRC-I
HRC-S1, HRC-S2, HRC-S3
ACIS-I0, ACIS-I1, ACIS-I2, ACIS-I3
ACIS-S0, ACIS-S1, ACIS-S2, ACIS-S3, ACIS-S4, ACIS-S5
ACIS-0, ACIS-1, ACIS-2, ACIS-3,
ACIS-4, ACIS-5, ACIS-6, ACIS-7, ACIS-8, ACIS-9

For these detector subsystems, the following qualifiers or options are supported:

QE=value
CONTAM=yes|no
UNIFORM (forces QE to be uniform)
IDEAL (equivalent to "QE=1;UNIFORM;CONTAM=NO")
CHIP=value (CHIP=4 ==> ACIS-4 (ACIS-S0))
WINDOW=xmin,ymin,xmax,ymax
REGION=BOX(xcenter,ycenter,xsize,ysize)
REGION=RECTANGLE(xmin,xmax,ymin,ymax)
TIME=value (in seconds since MJDREF)

Note that only simple rectangular regions are supported.

For ACIS, the BPMASK qualifier allows one to include bad pixels selected according to the status column in the bad pixel file:

BPMASK=hex value    (Specified as, e.g., 0x3f9ff)
BPMASK=dec value    (Specified as, e.g., 260607)
BPMASK=FAINT        (=0x3f9ff, 260607)
BPMASK=VFAINT       (=0x3ffff, 262143)

If this option is not present, the default is FAINT.

Parameter=grating (string required filetype=input default=NONE)

This parameter controls whether or not to compute a zeroth order grating ARF. For grating observations, the value is either HETG or LETG. For imaging observations, the value of this parameter is NONE.

When creating a zero-order ARF (grating=HETG or grating=LETG), the TG_M header keyword in the output file is set to "0". (TG_M records the diffraction order of the photons.)

Note: For HETG, the PSF in zeroth order is believed to be identical to the imaging PSF. However, for LETG this is definitely not the case and it is unclear whether or not the PSF library will properly handle this case. For this reason, it is recommended that the region be selected to guarantee a PSF fraction of 1.0.

Parameter=maskfile (file required filetype=input default=NONE)

The mask file (msk1.fits) for the observation. The mask file is needed in particular when a window or subarray was used. A value of "NONE" indicates that no mask file will be applied.

More information on the mask file is available in the CIAO Dictionary.

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

ACIS "dead area" coefficients file, which may have the values "NONE" (no dead area computation), CALDB (for automatic lookup), or an explicit file reference to an ACIS "dead area" coefficients FITS table.

The ACIS dead area refers to a slight decrease in detector efficiency due to the background cosmic ray flux which temporarily renders some pixels useless. The calibration product is a coefficient (per CCD) which gives the fractional area lost (or "deadened") per second. Since the area lost increases with time, the magnitude of the effect depends upon the ACIS clocking parameters (number of rows, window location, frame-time) which determine how long a pixel was exposed to the background cosmic ray flux during the primary exposure and during electronic readout from the frame-store area. For full-frame timed-exposure, the dead area is about 4% at maximum CHIPY and about 2% at the readout. It is smaller for subarrays.

The dafile parameter is ignored for HRC data.

Parameter=mirror (string filetype=input default=HRMA)

For Chandra, the mirror parameter must be set to "HRMA". However, the following ARDLIB qualifiers are also supported:

AREA=value
SHELL=value (possible values: 1,3,4,6)
BITMAP=value

NOTE: the ardlib mirror qualifiers are not applied when computing a 0th order grating arf with mkarf.

To compute an instrument map for using shells 1 and 3, which corresponds to the bitmap "1100", use "HRMA;bitmap=1100" for the value of this parameter. To compute using a mirror area of 1, use "HRMA;AREA=1".

Parameter=ardlibparfile (file filetype=input default=ardlib.par)

The name of the parameter file to be used by ARDLIB.

The tool-specific parameter file contains no explicit CALDB parameters. Instead, the CALDB parameters are all contained in a separate parameter file selectable using the `ardlibparfile' parameter; "ardlib.par" is the default file name. Calibration files are specified implicitly via the `DetSubsys' and `Mirror' parameters described below.

Parameter=geompar (string filetype=input default=geom)

The name of the Pixlib Geometry parameter file.

Parameter=verbose (integer default=0)

The verbosity level for messages.

Parameter=clobber (boolean default=no)

If set to yes, existing output files will be overwritten.

Deprecation of 'pbkfile' parameter

In CIAO 4.6, the ACIS parameter block file is no longer a required input to this tool. Therefore the 'pbkfile' parameter has been deprecated. The parameter has been retained for now but it is non functional.

This change is made possible by a series of header keyword updates that were made in Chandra standard data processing and are replicated in the chandra_repro script. Four new keywords: SUM_2X2, FEP_CCD, ORC_MODE, and OCLKPAIR have been added to the standard ACIS event file, that, in addition to existing keywords, provide the tool the information needed for the ACIS Dead Area calibration.

These keywords are required to use this tool in CIAO 4.6. Data from the archive with ASCDSVER newer than DS8.4.2 will already have these keywords. This will be the default for all but a few early observations. Users with data that was created prior to ASCDSVER=8.4.2 will need to follow one of these paths to use CIAO 4.6.

Retrieve most recent data from Chandra archive. All but a few datasets in the Chandra archive have been reprocessed to include these keywords (the earliest observations). The last bulk reprocessing included several updates including corrections for aspect "drift" within an observation as well as updated timing information. A summary of the updates can be found here: https://cxc.harvard.edu/cda/repro4.html
Reprocess the data through chandra_repro. This will update the headers with the new keywords and ensure that the other calibrations are consistent with the latest CALDB.
Just update the headers using the r4_header_update script. This will just add new keywords to the event file without any other calibration updates.

Tool Version

The command "mkarf --version" prints the version of mkarf and the associated libraries. This is useful when reporting problems with the tool.

Bugs

Caveats

Warnings related to missing SUM_2X2, OCLKPAIR, FEP_CCD, or ORC_MODE keywords

Users trying to run this tool with old versions of data products, those created with ASCDSVER less than version 8.4.2, may see warnings like


FITSIO status = 202: keyword not found in header
*** ERROR: *** Unable to get the value of `SUM_2X2' in /data/acisf04425_000N003_evt1.fits

Users should reprocess their data or use the r4_header_update script.

Comments and units are not always clear

The comments and units of the output ARF file has some keyword and column that do not follow the standards (eg "sec" instead of "s" for seconds). The data values and keyword/column names are correct.