7.3 General Parameters

Most AE tools and stages described in the sections below explicitly or implicitly use the master source list (all.srclist) maintained by ae_source_manager. Several other parameters that are explicitly or implicitly used by these tools are described below.

obsname:

a string that identifies an observation (usually an ObsId e.g. ``1875''); it will name a sub-directory created for each source.

EXTRACTION_NAME

an optional string or string array that identifies a set of extraction parameters. If supplied, the AE output files are structured with an extra directory level using the specified name(s). For example, if the observer wished to perform the extraction twice, with two different sets of PSF fractions, then EXTRACTION_NAME could be used to put the output from the two extractions in separate directories. Similarly, data products produced by merging multiple extractions can be named via the MERGE_NAME parameter to the MERGE_OBSERVATIONS Stage (§7.8).

obsdata_filename:

the file name of the single-observation event list you wish to use for extraction. This manual will not attempt to discuss the various recipes observers use to prepare ACIS data for spectral extraction. The only event list columns used by AE are TIME, CCD_ID, CHIPX, CHIPY, DETX, DETY, X, Y, PI, ENERGY, and STATUS; discarding the other columns will reduce AE run times. We recommend that the event list should NOT be strongly filtered by energy; the data can be more correctly band-limited later during spectral analysis. The event data must be in the tangent plane coordinate system of the observation, not ``reprojected'' to some other observation (§7.13).

ACIS event lists contain a boolean flag column named STATUS that CIAO uses to record various data cleaning criteria that are commonly used to remove events likely to arise from the instrumental background. Two of those cleaning criteria--``afterglow'' identification and ``5x5 background'' identification--produce false positives for sources with high count rates. Thus, low-rate sources are optimally extracted by applying these cleaning criteria and high-rate sources are optimally extracted by ignoring these cleaning criteria (Broos et al., 2010).

AE supports the optimal extraction of both groups of sources by applying a STATUS=0 filter to the source and background extractions of low-rate sources, and ignoring the STATUS column for high-rate sources. To take advantage of this capability, the observer should clean Level 2 event data using only the ``safe'' STATUS bits--those not associated with the ``afterglow'' and ``5x5 background'' criteria.

emap_filename:

the file name of a single-observation exposure map that is aligned with the event data, that represents any masking done to the event data, and that has a field of view corresponding to the event data you're extracting. The CXC provides threads and scripts for constructing exposure maps. We use the tool ae_make_emap (§7.14). It's unclear whether the energy band used in computing the exposure map has any significant effect on the results. AE requires that the exposure map has units of $s \times cm^2 \times count/photon$ (i.e. the normalize="no" option was supplied to mkexpmap). Note that the exposure maps supplied to the EXTRACT_SPECTRA and EXTRACT_BACKGROUNDS stages of AE are integrated over the source and background extraction regions in order to derive appropriate scaling for the background spectrum. The integrals alone determine the scaling; the EXPOSURE keywords in the two event lists are ignored.

There is no specific binning requirement for the exposure map, however keep in mind that both point source masks and background regions in AE are ultimately defined as regions corresponding to sets of exposure map pixels rather than as geometric regions (e.g. DS9 region files). We recommend an exposure map pixel size of 1 sky pixel or smaller, particularly if the tools ae_better_masking (§7.6.3) or ae_better_backgrounds (§7.6.1) are to be used.

We recommend that you examine your exposure maps to ensure that they are reasonably cropped. Very large borders of zeros around your exposure maps will needlessly slow the execution of many data analysis steps.