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:
- Mirrors: HRMA
- Detectors: ACIS-[0-9], ACIS-I[0-3], ACIS-S[0-5], HRC-S[1-3], HRC-I
- Gratings: HEG, MEG, LEG
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
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, mkosip, mkpsfmap, mkrmf, mkrprm, mkwarf, psf_project_ray, rmfimg
- tools::statistics
- aprates