% Time-stamp: <98/06/19 14:29:50 dph> % MIT Directory: ~dph/h1/ASC/TG/Flight/Development/Expmap/Specs % CfA Directory: /dev/null % File: expmap_specs.txt % Author: D. Huenemoerder % Original version: 980616 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% IMapcalc: Make an Instrument Map (IMap) stack. The instrument map is the product of the detector QE and the HRMA effective area, vs energy and position, for a given SIM Z-offset: Q(E,s)M(E,s) (where s is detector chip coordinate). It has high spatial resolution. The IMap can be ``on the shelf'' for a set of standard energies and aim-points. If the SIM is at a non-standard (or new) aim-point (defined by the Z-offset), then new IMaps must be computed. Inputs: E - set of energies at which to compute IMaps. Each energy will specify one plane in a stack of IMaps. Z - SIM Z-offset (determines axial location of HRMA vignetting function) MEA - HRMA effective area (function of energy and off-axis angle and azimuth) QE - Detector Quantum efficiency, vs Energy and position. Output: IMap - Instrument Map vs E and detector x,y. Format will be 3D FITS image, with one plane for each energy. Extensions will hold individual chip (or filter region) maps. IMaps should be archived. Given a library, they can be looked up vs SIM-Z, for each detector. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% QEcalc: Calculate the detector quantum efficiency vs position at an arbitrary energy. The QE(E,x,y) calculated from Q_bar and U for arbitrary energy via the definition: Q(E,x,y) = Q_bar(E) U(E;c_i(x_j,y_k) ) where U is a set function of energy and position-dependent coefficients. Inputs: E - energy at which to calculate the QE Q_bar(E) - the mean QE(E) for a device (or region) U(i,x_j,y_k) - A file of uniformity coefficients. The coefficients are tabulated vs position (x_j,y_k) and specify the uniformity, U == Q(E,x,y)/Q_bar(E), as a function of energy at that position. Ouput: QE - The detector element quantum efficiency as a function of position at the specified energy (2D image) Note: In the case of front-illuminated detectors, U may be ==1 and make this function a trivial lookup. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Mapscale: Scale a Map, by applying bad pixels or regions (ACIS or HRC), or accepted windows (if ACIS). Inputs: Map - map (or ``stack'', a 3D image). windows - ACIS BEP windows defining region of accepted events badpix - bad pixel lists or regions Output: SMap - Scaled Map (or stack). This has the same dimensionality as Map, but now has some regions set to zero. This is needed for Effective Area Map calculation, but not after (don't need to archive). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% AIMapcalc: Make an Averaged Instrument Map for nominal aim-point at an arbitrary energy. This is an interpolation utility for deriving an Effective Area Map at an arbitrary energy from the monochromatic set of Effective Area Maps. This is similar to the Instrument Map, but is smoothed over an approximate aspect dither amplitude. It is the product of the mean QE(E,x,y) and mirror area ( ), and transformed to sky coordinates before use with the EAMap. Inputs: IMap - Instrument Map (stack) Aspect Amplitude - A mean dither amplitude, which specifies how big a cell over which to smooth the instrumental calibration data. Output: AIMap - Averaged Instrument Map. The AIMap is a dynamic product, since it is used to generate analysis products, such as ARFs and ExpMaps for arbitrary regions or bandpasses. Notes: To facilitate the dynamic computation of the AIMap, we can pre-compute the smoothed uniformity coefficients, , in order to allow the QE(E,x,y) generating function to generate a smoothed QE. This is under the assumption that the mirror vignetting is invariant over the scale of the dither amplitude, for the purposes of the interpolation routine. We can consider the set of QEcalc, IMapcalc, and AIMapcalc as a library function whose inputs are Energy (and perhaps some control parameters, such as device configuration), and whose output is the Averaged Instrument Map. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% EAMapcalc: Make an Effective Area Map (EAMap) stack, which is the {\em observed} effective area as a function of sky position, integrated over the aspect history, for a set of discrete energies. This is the fundamental product from which ARFs and exposure maps will be rigourously derived. It is computed only for a discrete set of energies, but when combined with the AIMap (function/lookup) and the interpolation scheme, it provides the effective area for arbitrary energy and position. This is the integration of the instrument map with the pointing history (aspect histogram), weighted by the dwell-time. Inputs: sky grid - the region of the sky for which the map will be made, and the spatial resolution. The grid is specified by: min R.A., max R.A. min Dec., max Dec. R.A. bin size Dec. bin size Aspect - the aspect solution (or aspect offsets, which are derived from the solution). GTI - Good Time Intervals (for ACIS, these are chip specific). DTCF - Dead Time Correction Factor SIMap - Scaled Instrument Map Output: EAMap - Effective Area Map, or the effective area as a function of sky pixel (times time) for a set of discrete energies (a 3D image, or stack of 2D images). This will be stored as a FITS 3D image. Extensions will contain detector element image stacks. The EAMap may be a standard data product, since it is used to generate analysis products, such as ARFs and ExpMaps for arbitrary regions or bandpasses via an interpolation routine. Comment: This combined with the AIMap function/lookup and the interpolation scheme (and calibration data) will allow computation of AEMap at arbitrary energy. There will be a library function to provide this capability. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ARFcalc: Integrate the EAMap over position, and interpolate over energy to calculate a traditional ``ARF'', or Auxiliary Response Matrix. This is the one-dimensional effective area function used by such packages as {\sc Xspec}. Inputs: EAMap - Effective Area Map (computed by EAMapcalc) [optional] E_grid - Energy grid for the result. sky_region - spatial region, in sky coordinates, over which to integrate the EAMap. AIMap - the Averaged Instrument Map (function/lookup), which is required by the interpolation scheme. PSFfrac - the fraction of the PSF enclosed in the region, as a function of energy. MODE - specify whether to be precise and read the EAMap set and interpolate with AIMap, or be approximate and use only the AIMap. Output: ARF: Auxilary Response Matrix, the effective area vs energy, averaged over time (aspect) and position, for high-resolution in energy. This is a source-specific product, not necessarily to be computed by a pipeline. Note: The AIMap input may actually be implemented internally as a library call, since it is really a dynamic product of an interpolation routine. (It is too big to pre-compute at full resolution). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ExpMapcalc: Compute an Exposure Map for a specified energy band, pulse height band, and optional spectrum. (If a spectrum is input, the output is not really exposure, but count density.) Inputs: EAMap - Effective Area Map (effective area vs sky position for discrete energies) PI_band - lower and upper limits of detector pulse-heights (in ``Pulse Invariant'' space) for which to calculate the map. E_band - lower and upper energy limits for the resultant map. This generally should be consistent with PI_band (e.g., for a given E_band, compute PI_band), but can be arbitrary (e.g., for all Energies, use PI band for ACIS fluorescence.) RMF - Detector redistribution matrix file. Spectrum- Optional, affects interpretation of results. (Also useful for prediction of background rate.) If omitted, a flat spectrum is assumed (in energy and position). AIMap - Averaged Instrument Map, which is required for the interpolation method from a set of discrete energies to arbitrary energy (or an equivalent library function call), or is the primary data, if MODE is ``approximate''. MODE - specify whether to be precise and read the EAMap set and interpolate with AIMap, or be approximate and use only the AIMap. Output: ExpMap - the exposure map, the effective area (or count-rate per unit flux) vs position, integrated over energy and pulse-height regions. The format will be a FITS 2D image, merged over detector chips, or FITS 3D image, with detector chip maps kept in separate extensions (TBR). This is a very subjective product, highly dependent upon intended use. Pipeline uses may be defined for background maps or source detection. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% RMFcalc: Compute a redistribution matrix, for a given device (or set of chips). Inputs: redist func - redistribution function (coefficients and function). E_grid - energy grid. PI_grid - pulse-height grid. Output: RMF - Redistribution Matrix File (or set) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% PSFfrac: Calculate the fraction of the PSF(E,p) in the specified sky region. Inputs: src_pos - the source position src_type - point or extended? (not that we know what to do, if extended ;-) E_grid - energy grid, for output array. sky_region - region of the sky over which to determine the fraction. Output: PSFfrac - the fraction vs energy of the flux enclosed within the region.