Last modified: December 2013

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/ardlib.html
Jump to: Description · Parameters · Bugs · See Also


AHELP for CIAO 4.16

ardlib

Context: calibration

Synopsis

Analysis Reference Data Library

Syntax

Example:
pset ardlib AXAF_ACIS7_BADPIX_FILE = \
"/data/ObsID1843/primary/acisf01843_000N001_bpix1.fits[BADPIX7]"

Description

ARDLIB is a software library that provides a mission independent interface to instrument-specific calibration data. Tools such as `mkarf', `mkwarf', `mkinstmap', `mkgrmf', and `mkexpmap' use this library to compute effective areas, detector efficiencies, and so on.

Currently the only mission supported by ARDLIB is Chandra. The following Chandra instruments are supported:

Some instruments supported by ARDLIB allow the specification of one or more qualifiers. The use of qualifiers allows the user to influence the calculation performed by ARDLIB for the corresponding instrument. For instance, an exposure map representing the total amount of time spent observing a point in the sky may be easily constructed by using a uniform detector QE of 1.0 (e.g., detsubsys="ACIS-I3;QE=1;UNIFORM;CONTAM=NO") and a mirror effective area of 1.0 (e.g., mirror="HRMA;area=1"). Qualifiers allow one to specify these constraints in a simple way. Further details on the use of these parameter qualifiers are given in the help files for individual tools, such as mkinstmap, which use the ARDLIB interface.

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

Generic qualifiers:

Option
HELP

This option causes the calling program to halt with a message specifying the options for the associated parameter. For example, to get a listing of the options for the `detsubsys' parameter of `mkarf', one can use detsubsys="ACIS-S3;HELP" This causes `mkarf' to exit, displaying a summary of the valid options for the ACIS-S3 subsystem.

HRMA qualifiers:

Option Details
AREA=value
SHELL=n n=1,3,4, or 6
BITMAP=xxxx x=0 or 1

For example, to specify HRMA shells 1 and 3, which correspond to the bitmap "1100", use "HRMA;bitmap=1100". To compute using a mirror area of 1, use "HRMA;AREA=1".

ACIS-S/I qualifiers:

Option Details
QE=value
UNIFORM forces QE to be uniform
CONTAM=yes|no if yes (the default), correct for ACIS QE changes due to the buildup of contamination on the optical blocking filter.
IDEAL equivalent to "QE=1;UNIFORM;CONTAM=NO"
CHIP=value CHIP=4 means ACIS-4, which is also known as ACIS-S0
WINDOW=xmin,ymin,xmax,ymax
REGION=BOX(xcenter,ycenter,xsize,ysize)
REGION=RECTANGLE(xmin,xmax,ymin,ymax)
BPMASK=value BPMASK=0 means ignore the bad pixel file
TIME=value Units are seconds since MJDREF

By default, the time dependence of the ACIS QE, due to the buildup of contamination on the optical blocking filter, is accounted for automatically (CONTAM=yes). The QE correction factor is computed for the observation start time, TSTART, taken from the FITS header. For more information about the ACIS filter contamination model, see the ACIS calibration web page at https://cxc.cfa.harvard.edu/cal/Acis/detailed_info.html#obf_contam.

If the Observation Information file, e.g., obsfile as specified in mkarf.par, has CTI_CORR=yes, then the CALDB lookups will specify CTI-corrected files.

Note that "QE=xxx" affects the mean QE only; the QE uniformities (QEU) are still applied.

Explicit use of the TIME parameter is normally unnecessary because most tools automatically obtain the observation time from the FITS header. However, if necessary, this option may be used to specify time-dependent instrument parameters such as the ACIS QE. For example, to obtain the value of the correction factor used to account for ACIS-S3 contamination in observations carried out in Jan 2003, one may compute an ARF using the detector subsystem parameter set to:

detsubsys="ACIS-7;QE=1;UNIFORM;TIME=1.57788e+08"

HEG, MEG, LEG qualifiers:

Option Details
SHELL=n n=1,3,4, or 6
BITMAP=xxxx x=0 or 1

The SHELL and BITMAP parameters allow the computation of a grating efficiency for the corresponding rings of the LETG or HETG grating assembly.

HRC-S/I qualifiers:

Option Details
QE=value
UNIFORM forces QE to be uniform
IDEAL equivalent to "QE=1;UNIFORM"

ARDLIB has many parameters that specify calibration data for the various missions that it supports. Currently, the only mission that is supported is Chandra. If a parameter value is set to CALDB, the library will query the calibration database (ie CALDB) to find the best file: if you wish to specify a specific file - such as the bad-pixel file that is supplied for each ACIS observation - then you change the parameter to point to that file. Further details are available at the CIAO threads web page.


Parameters

name type def
ArdlibDataPath string $ASCDS_CALIB
GENERIC_EFFAREA_FILE string xrt_ea_v2_0.fits
GENERIC_VIGNET_FILE string /dev/null
AXAF_EFFAREA_FILE_0001 string CALDB
AXAF_EFFAREA_FILE_0010 string CALDB
AXAF_EFFAREA_FILE_0100 string CALDB
AXAF_EFFAREA_FILE_1000 string CALDB
AXAF_EFFAREA_FILE_1111 string CALDB
AXAF_VIGNET_FILE_0001 string CALDB
AXAF_VIGNET_FILE_0010 string CALDB
AXAF_VIGNET_FILE_0100 string CALDB
AXAF_VIGNET_FILE_1000 string CALDB
AXAF_VIGNET_FILE_1111 string CALDB
AXAF_ACIS0_QE_FILE string CALDB
AXAF_ACIS1_QE_FILE string CALDB
AXAF_ACIS2_QE_FILE string CALDB
AXAF_ACIS3_QE_FILE string CALDB
AXAF_ACIS4_QE_FILE string CALDB
AXAF_ACIS5_QE_FILE string CALDB
AXAF_ACIS6_QE_FILE string CALDB
AXAF_ACIS7_QE_FILE string CALDB
AXAF_ACIS8_QE_FILE string CALDB
AXAF_ACIS9_QE_FILE string CALDB
AXAF_ACIS0_QEU_FILE string CALDB
AXAF_ACIS1_QEU_FILE string CALDB
AXAF_ACIS2_QEU_FILE string CALDB
AXAF_ACIS3_QEU_FILE string CALDB
AXAF_ACIS4_QEU_FILE string CALDB
AXAF_ACIS5_QEU_FILE string CALDB
AXAF_ACIS6_QEU_FILE string CALDB
AXAF_ACIS7_QEU_FILE string CALDB
AXAF_ACIS8_QEU_FILE string CALDB
AXAF_ACIS9_QEU_FILE string CALDB
AXAF_ACIS0_BADPIX_FILE string CALDB
AXAF_ACIS1_BADPIX_FILE string CALDB
AXAF_ACIS2_BADPIX_FILE string CALDB
AXAF_ACIS3_BADPIX_FILE string CALDB
AXAF_ACIS4_BADPIX_FILE string CALDB
AXAF_ACIS5_BADPIX_FILE string CALDB
AXAF_ACIS6_BADPIX_FILE string CALDB
AXAF_ACIS7_BADPIX_FILE string CALDB
AXAF_ACIS8_BADPIX_FILE string CALDB
AXAF_ACIS9_BADPIX_FILE string CALDB
AXAF_ACIS0_CONTAM_FILE string CALDB
AXAF_ACIS1_CONTAM_FILE string CALDB
AXAF_ACIS2_CONTAM_FILE string CALDB
AXAF_ACIS3_CONTAM_FILE string CALDB
AXAF_ACIS4_CONTAM_FILE string CALDB
AXAF_ACIS5_CONTAM_FILE string CALDB
AXAF_ACIS6_CONTAM_FILE string CALDB
AXAF_ACIS7_CONTAM_FILE string CALDB
AXAF_ACIS8_CONTAM_FILE string CALDB
AXAF_ACIS9_CONTAM_FILE string CALDB
AXAF_HRC-I_QE_FILE string CALDB
AXAF_HRC-I_QEU_FILE string CALDB
AXAF_HRC-I_BADPIX_FILE string NONE
AXAF_HRC-S1_QE_FILE string CALDB
AXAF_HRC-S2_QE_FILE string CALDB
AXAF_HRC-S3_QE_FILE string CALDB
AXAF_HRC-S1_QEU_FILE string CALDB
AXAF_HRC-S2_QEU_FILE string CALDB
AXAF_HRC-S3_QEU_FILE string CALDB
AXAF_HRC-S_BADPIX_FILE string NONE
AXAF_HETG_1000_FILE string CALDB
AXAF_HETG_0100_FILE string CALDB
AXAF_HETG_0010_FILE string CALDB
AXAF_HETG_0001_FILE string CALDB
AXAF_LETG_1000_FILE string CALDB
AXAF_LETG_0100_FILE string CALDB
AXAF_LETG_0010_FILE string CALDB
AXAF_LETG_0001_FILE string CALDB
AXAF_HETG_1100_LSF_FILE string CALDB
AXAF_HETG_0011_LSF_FILE string CALDB
AXAF_LETG_1111_LSF_FILE string CALDB
AXAF_RMF_FILE string CALDB
AXAF_GAIN_FILE string CALDB

Detailed Parameter Descriptions

Parameter=ArdlibDataPath (string default=$ASCDS_CALIB)

Directory containing data files

A colon delimited list of pathnames to search for data files. If the first character of the string is a `$', then the value represents the name of an environment variable.

Parameter=GENERIC_EFFAREA_FILE (string default=xrt_ea_v2_0.fits)

Effective area file

For generic mission support.

Parameter=GENERIC_VIGNET_FILE (string default=/dev/null)

Vignetting file

For generic mission support.

Parameter=AXAF_EFFAREA_FILE_0001 (string default=CALDB)

AXAF eff-area file 0001

These parameters specify the name of the FITS file and extension number for the on-axis Chandra HRMA effective area for the appropriate shell. The numerical suffixes specify the mirror shell as a shell-bitmap. For instance, _0001 refers to shell 6, _0100 refers to shell 3, and _1111 refers to shells 1,3,4,6.

Parameter=AXAF_EFFAREA_FILE_0010 (string default=CALDB)

AXAF eff-area file 0010

Parameter=AXAF_EFFAREA_FILE_0100 (string default=CALDB)

AXAF eff-area file 0100

Parameter=AXAF_EFFAREA_FILE_1000 (string default=CALDB)

AXAF eff-area file 1000

Parameter=AXAF_EFFAREA_FILE_1111 (string default=CALDB)

AXAF eff-area file 1111

Parameter=AXAF_VIGNET_FILE_0001 (string default=CALDB)

AXAF vignet file 0001

These parameters specify the off-axis vignetting curves for the mirror shells, as described above. The off-axis HRMA effective area is represented as the product of an on-axis effective area with the off-axis vignetting function.

Parameter=AXAF_VIGNET_FILE_0010 (string default=CALDB)

AXAF vignet file 0010

Parameter=AXAF_VIGNET_FILE_0100 (string default=CALDB)

AXAF vignet file 0100

Parameter=AXAF_VIGNET_FILE_1000 (string default=CALDB)

AXAF vignet file 1000

Parameter=AXAF_VIGNET_FILE_1111 (string default=CALDB)

AXAF vignet file 1111

Parameter=AXAF_ACIS0_QE_FILE (string default=CALDB)

ACIS-0 Mean QE File

These parameters specify the ACIS mean QE files for each of the 10 ACIS chips. The QE is given as the product of a mean QE with the uniformity function. The values represented in these files must include the filters.

Parameter=AXAF_ACIS1_QE_FILE (string default=CALDB)

ACIS-1 Mean QE File

Parameter=AXAF_ACIS2_QE_FILE (string default=CALDB)

ACIS-2 Mean QE File

Parameter=AXAF_ACIS3_QE_FILE (string default=CALDB)

ACIS-3 Mean QE File

Parameter=AXAF_ACIS4_QE_FILE (string default=CALDB)

ACIS-4 Mean QE File

Parameter=AXAF_ACIS5_QE_FILE (string default=CALDB)

ACIS-5 Mean QE File

Parameter=AXAF_ACIS6_QE_FILE (string default=CALDB)

ACIS-6 Mean QE File

Parameter=AXAF_ACIS7_QE_FILE (string default=CALDB)

ACIS-7 Mean QE File

Parameter=AXAF_ACIS8_QE_FILE (string default=CALDB)

ACIS-8 Mean QE File

Parameter=AXAF_ACIS9_QE_FILE (string default=CALDB)

ACIS-9 Mean QE File

Parameter=AXAF_ACIS0_QEU_FILE (string default=CALDB)

ACIS-0 Uniformity file

These parameters specify the ACIS detector uniformity files for each of the 10 ACIS chips.

Parameter=AXAF_ACIS1_QEU_FILE (string default=CALDB)

ACIS-1 Uniformity file

Parameter=AXAF_ACIS2_QEU_FILE (string default=CALDB)

ACIS-2 Uniformity file

Parameter=AXAF_ACIS3_QEU_FILE (string default=CALDB)

ACIS-3 Uniformity file

Parameter=AXAF_ACIS4_QEU_FILE (string default=CALDB)

ACIS-4 Uniformity file

Parameter=AXAF_ACIS5_QEU_FILE (string default=CALDB)

ACIS-5 Uniformity file

Parameter=AXAF_ACIS6_QEU_FILE (string default=CALDB)

ACIS-6 Uniformity file

Parameter=AXAF_ACIS7_QEU_FILE (string default=CALDB)

ACIS-7 Uniformity file

Parameter=AXAF_ACIS8_QEU_FILE (string default=CALDB)

ACIS-8 Uniformity file

Parameter=AXAF_ACIS9_QEU_FILE (string default=CALDB)

ACIS-9 Uniformity file

Parameter=AXAF_ACIS0_BADPIX_FILE (string default=CALDB)

ACIS-0 Bad Pixel File

These parameters specify the bad pixel files for each of the 10 ACIS chips. A value of "NONE" may be used if no data is available.

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.

Parameter=AXAF_ACIS1_BADPIX_FILE (string default=CALDB)

ACIS-1 Bad Pixel File

Parameter=AXAF_ACIS2_BADPIX_FILE (string default=CALDB)

ACIS-2 Bad Pixel File

Parameter=AXAF_ACIS3_BADPIX_FILE (string default=CALDB)

ACIS-3 Bad Pixel File

Parameter=AXAF_ACIS4_BADPIX_FILE (string default=CALDB)

ACIS-4 Bad Pixel File

Parameter=AXAF_ACIS5_BADPIX_FILE (string default=CALDB)

ACIS-5 Bad Pixel File

Parameter=AXAF_ACIS6_BADPIX_FILE (string default=CALDB)

ACIS-6 Bad Pixel File

Parameter=AXAF_ACIS7_BADPIX_FILE (string default=CALDB)

ACIS-7 Bad Pixel File

Parameter=AXAF_ACIS8_BADPIX_FILE (string default=CALDB)

ACIS-8 Bad Pixel File

Parameter=AXAF_ACIS9_BADPIX_FILE (string default=CALDB)

ACIS-9 Bad Pixel File

Parameter=AXAF_ACIS0_CONTAM_FILE (string default=CALDB)

ACIS-0 Contamination File

Parameter=AXAF_ACIS1_CONTAM_FILE (string default=CALDB)

ACIS-1 Contamination File

Parameter=AXAF_ACIS2_CONTAM_FILE (string default=CALDB)

ACIS-2 Contamination File

Parameter=AXAF_ACIS3_CONTAM_FILE (string default=CALDB)

ACIS-3 Contamination File

Parameter=AXAF_ACIS4_CONTAM_FILE (string default=CALDB)

ACIS-4 Contamination File

Parameter=AXAF_ACIS5_CONTAM_FILE (string default=CALDB)

ACIS-5 Contamination File

Parameter=AXAF_ACIS6_CONTAM_FILE (string default=CALDB)

ACIS-6 Contamination File

Parameter=AXAF_ACIS7_CONTAM_FILE (string default=CALDB)

ACIS-7 Contamination File

Parameter=AXAF_ACIS8_CONTAM_FILE (string default=CALDB)

ACIS-8 Contamination File

Parameter=AXAF_ACIS9_CONTAM_FILE (string default=CALDB)

ACIS-9 Contamination File

Parameter=AXAF_HRC-I_QE_FILE (string default=CALDB)

HRC-I Mean QE file

The HRC-I mean detector efficiency file.

Parameter=AXAF_HRC-I_QEU_FILE (string default=CALDB)

HRC-I QE Uniformity file

The HRC-I QE Uniformity file.

Parameter=AXAF_HRC-I_BADPIX_FILE (string default=NONE)

HRC-I Bad Pixel File

Parameter=AXAF_HRC-S1_QE_FILE (string default=CALDB)

HRC-S1 Mean QE file

These parameters specify the HRC-S mean QE files for each MCP.

Parameter=AXAF_HRC-S2_QE_FILE (string default=CALDB)

HRC-S2 Mean QE file

Parameter=AXAF_HRC-S3_QE_FILE (string default=CALDB)

HRC-S3 Mean QE file

Parameter=AXAF_HRC-S1_QEU_FILE (string default=CALDB)

HRC-S1 QE Uniformity file

These parameters specify the HRC-S uniformity files for each MCP.

Parameter=AXAF_HRC-S2_QEU_FILE (string default=CALDB)

HRC-S2 QE Uniformity file

Parameter=AXAF_HRC-S3_QEU_FILE (string default=CALDB)

HRC-S3 QE Uniformity file

Parameter=AXAF_HRC-S_BADPIX_FILE (string default=NONE)

HRC-S Bad Pixel File

Parameter=AXAF_HETG_1000_FILE (string default=CALDB)

HETG 1000 efficiency file

These parameters specify the HETG grating efficiency files for the specified mirror shell bitmap.

Parameter=AXAF_HETG_0100_FILE (string default=CALDB)

HETG 0100 efficiency file

Parameter=AXAF_HETG_0010_FILE (string default=CALDB)

HETG 0010 efficiency file

Parameter=AXAF_HETG_0001_FILE (string default=CALDB)

HETG 0001 efficiency file

Parameter=AXAF_LETG_1000_FILE (string default=CALDB)

LETG 1000 efficiency file

These parameters specify the LETG grating efficiency files for the specified mirror shell bitmap.

Parameter=AXAF_LETG_0100_FILE (string default=CALDB)

LETG 0100 efficiency file

Parameter=AXAF_LETG_0010_FILE (string default=CALDB)

LETG 0010 efficiency file

Parameter=AXAF_LETG_0001_FILE (string default=CALDB)

LETG 0001 efficiency file

Parameter=AXAF_HETG_1100_LSF_FILE (string default=CALDB)

MEG LSFPARM file

Parameter=AXAF_HETG_0011_LSF_FILE (string default=CALDB)

HEG LSFPARM file

Parameter=AXAF_LETG_1111_LSF_FILE (string default=CALDB)

LEG LSFPARM file

Parameter=AXAF_RMF_FILE (string default=CALDB)

CCD RMF p3resp file

Parameter=AXAF_GAIN_FILE (string default=CALDB)

Gain File


Bugs

There are no known bugs for this tool.

See Also

calibration
caldb
psf
psf
tools::aspect
asphist, dither_region
tools::background
acis_bkgrnd_lookup, hrc_bkgrnd_lookup, readout_bkg
tools::caldb
calindex, calmerge, calquiz, calvalid
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, mkinstmap, mkpsfmap, mkrmf, mkwarf, psf_project_ray, rmfimg
tools::statistics
aprates