mkinstmap

Synopsis

Generate a Chandra instrument map (effective area vs. detector position)

mkinstmap  outfile spectrumfile monoenergy pixelgrid obsfile detsubsys
grating maskfile pbkfile [mirror] [dafile] [ardlibparfile] [geompar]
[verbose] [clobber]

Description

'mkinstmap' generates an instrument map used in the analysis of imaging observations. An image in detector coordinates, the instrument map is essentially the product of the mirror effective area projected onto the detector surface with the detector quantum efficiency (QE); the units are those of effective area [cm**(2) counts/photon]. The instrument map also incorporates bad pixels and ACIS windows (if any) by setting the efficiency to zero at the appropriate locations on the detector. When computing a zeroth order grating instrument map, the 0th order grating efficiency is also included.

The input calibration data (QEs, effective areas, 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 `mkinstmap'. 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 quantum efficiency 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. If necessary, 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 the ACIS calibration web page

At present, the ARDLIB does not support the use of time-dependent bad-pixel files. This applies to the creation of instrument maps for merged observations, when the number and distribution of bad pixels changes between observations. Typically the changes in bad pixels are small enough that a single bad-pixel file may be used.

For a quantitative definition of the instrument map, see Davis (2001) [ApJ 548, 1010].

Examples

Example 1

mkinstmap outfile="acis_i3_instmap.fits" monoenergy=1.5
pixelgrid="1:1024:#1024,1:1024:#1024" obsfile="evt.fits[EVENTS]"
dafile=NONE detsubsys="ACIS-I3"

Computes a 1024x1024 instrument map for 1.5 keV photons incident on ACIS-I3 and writes it to acis_i3_instmap.fits. By default, this instrument map includes a position-dependent QE correction for optical blocking filter contamination appropriate for the observation start date (TSTART) obtained from the header of the obsfile.

Example 2

mkinstmap outfile=instmap_1.7kev_7.fits monoenergy=1.7 detsubsys=ACIS-7
pixelgrid="1:1024:#1024,1:1024:#1024" obsfile="evt.fits[EVENTS]"
maskfile=acisf01838_000N001_msk1.fits dafile=CALDB

Computes a 1024x1024 instrument map for 1.7 keV photons incident on ACIS-7. The dafile parameter is set to apply the dead area correction.

Example 3

mkinstmap outfile="acis_s3_nc.fits" spectrumfile=spec.dat
pixelgrid="1:1024:#128,1:1024:#128" obsfile="evt.fits[EVENTS]"
dafile=NONE detsubsys="ACIS-S3;CONTAM=NO"

Computes a 128x128 weighted instrument map for ACIS-S3 which excludes the QE correction due to the buildup of contamination on the ACIS optical blocking filter. The result is a weighted sum of monochromatic instrument maps computed using photon energies and map weights given in the file spec.dat.

Example 4

mkinstmap outfile="acis_s3_shell1.fits"
pixelgrid="1:1024:#128,1:1024:#128" obsfile="evt.fits[EVENTS]"
dafile=NONE mirror="HRMA;AREA=1" detsubsys="ACIS-S3"

Computes a 128x128 instrument map for ACIS-S3 which includes only the effects of the detector QE. This is useful way to obtain an image of the QE uniformity of a particular device.

Example 5

mkinstmap outfile="hrc_i_ideal_instmap.fits"
pixelgrid="1:16384:#128,1:16384:#128" obsfile="evt.fits[EVENTS]"
detsubsys="HRC-I;IDEAL"

Computes a 128x128 instrument map for the full HRC-I that does not include the effects of the detector quantum efficiency (QE), and writes it to hrc_i_ideal_instmap.fits

In this case, the output instrument map is an image of the mirror effective area. This example illustrates the flexibility provided through the use of ARDLIB qualifiers and options.

Parameters

Detailed Parameter Descriptions

Parameter=outfile (file required filetype=input)

The name of the output instrument map file.

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

Input spectral weights file

If the value of this parameter is "NONE", then a monochromatic instrument map will be computed. Otherwise, a weighted instrument map will be computed using the user-provided spectral weights.

The spectrumfile is a two-column ASCII file: the first column specifies the energy in keV (E_i) and the second column specifies a spectral weighting (W_i). The spectral weight column should sum to 1. The weighted instrument map is then computed as a linear combination of monochromatic maps at energies E_i with weights W_i:

weightedinstmap = SUM(over i) W_i * QE(E_i) * Area (E_i)

The "Calculating Spectral Weights for mkinstmap" analysis thread shows how to use Sherpa to create a spectral weights file for input to mkinstmap.

Before using this option, make sure that you fully understand how the resulting instrument map, and consequently the exposure map relates to your source. Otherwise, the result may not be what you want. Further information is available in the "Introduction to Exposure Maps" document.

Parameter=monoenergy (real required filetype=input default=1.0)

The energy, in keV, for which the instrument map will be computed. This parameter is used only if the value of `SpectrumFile' is "NONE".

Parameter=pixelgrid (string required filetype=input)

This string specifies the detector region and the resolution of the output instrument map image. The recommended format is "x0:x1:#nx,y0:y1:#n2", where x0, x1, y0, y1, nx, and ny are positive integers. This specifies the region on the detector with pixel coordinates (X,Y) satisfying the conditions x0<=X<=x1 and y0<=Y<=y1, and indicates that the region is to be regridded to nx by ny pixels in the output image.

For example, to compute a 1024x1024 instrument map for an ACIS chip, use "1:1024:#1024,1:1024:#1024". To compute a 128x128 instrument map for the HRC-I, use "1:16384:#128,1:16384:#128". The latter will produce an instrument map with a LINEAR WCS to map the 128x128 pixels in the instrument map to the the 16384x16384 detector pixel plane. Since the instmap contains WCS, it is not necessary that the pixel grid should match the eventual output of mkexpmap.

It is useful to remember that each ACIS chip consists of 1024x1024 pixels. The HRC-I pixel plane consists of 16384x16384 pixels, and each HRC-S MCP is mapped to a 4096x16456 pixel plane.

Parameter=obsfile (file required filetype=input)

The name of a FITS file containing keywords which specify the mission, detector, SIM offsets, observation date, etc. This should be an event file.

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 exposure map 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
UNIFORM (forces QE to be uniform)
CONTAM=yes|no
IDEAL (equivalent to "QE=1;UNIFORM;CONTAM=NO")
TIME=value (in seconds since MJDREF)
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)

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 instrument map. If the value of this parameter is NONE, then a standard imaging instrument map will be computed. Otherwise, the value must be either HETG or LETG causing the corresponding zeroth order to be computed.

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=pbkfile (string required filetype=input)

Deprecated. See below.

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

For example, 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=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=ardlibparfile (string filetype=input default=ardlib.par)

The name of the parameter file to be used by ARDLIB. Typically, "ardlib.par" will be used.

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 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 "mkinstmap --version" prints the version of mkinstmap 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.

See Also

calibration

ardlib

psf

psf

tools::aspect

asphist, dither_region

tools::background

acis_bkgrnd_lookup, hrc_bkgrnd_lookup, readout_bkg

tools::composite

combine_grating_spectra, combine_spectra, specextract

tools::coordinates

sky2tdet

tools::core

dmextract

tools::response

acis_fef_lookup, acis_set_ardlib, addresp, dmarfadd, eff2evt, find_mono_energy, fullgarf, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkpsfmap, mkrmf, mkwarf, psf_project_ray, rmfimg

tools::statistics

aprates