APT Exposure Map

For several classes of observations, for example mosaics or programs that repeatedly cover the same region of sky, it is sometimes useful to make an exposure map to determine the amount of exposure time for a particular position in the region observed. APT has the capability of providing data that will allow the user to create such a map (outside of APT) via the Export Exposure Coverage option.

Once you have created the proposal, under the File menu, go to Export/Export Exposure Coverage data. This will export the exposure information for the entire proposal into the directory you last saved your proposal into. There will be 2 files.

PropID_coverage_catalog.csv file

This file provides a breakdown of the region covered by each exposure in the proposal, by recording all the positions of the corners of the detectors within each exposure. Each line corresponds to a reference point within a detector, thus one exposure will be represented by several consecutive lines.

The first field in each line is a unique "Name". The last five characters of the Name constitute the point identifier, which specify the shape point under consideration. Specifically, the point identifier has the form sh-vn, where 'sh' is the shape descriptor (a number followed by P for polygon and C for circle), and 'vn' is the vertex identifier (a V followed by the vertex number (origin 0)). For example, for a ACS/WFC exposure, you would have 2P-V0 for the first vertex of the second polygon (the WFC2 chip)

The correspondence between exposures and lines is as follows:

ACS/SBC, STIS: Each exposure corresponds to four lines, one for each vertex of the detector. The point identifiers are 1P-V0 through 1P-V3.
ACS/WFC, WFC3/UVIS: Each exposure corresponds to eight lines, four for Chip 1 and four for Chip 2. The point identifiers are 1P-V0 through 1P-V3 and 2P-V0 through 2P-V3.
WFC3/IR: Each exposure corresponds to five lines. The first four describe the vertices of the detector, with point identifiers P1-V0 through P1-V3. The fifth line is labeled 2C-V0, and it refers to the center of the so-called "death star" region, a circle where the detector does not collect valid data. The position given in this line is the center of the death star circle.

Each line in this file contains the following comma-separated fields:

Name:A unique identifier for the position. It is of the form vv.eee-c.s.pp.sp-sh-vn where:
- vv is the Visit Number.
- eee is the Exposure ID number.
- c is the Copy.
- s is the Split.
- pp is Primart Pattern Position.
- sp is the Secondary Pattern Position.
- sh is the shape number followed by a suffix of P or C for polygon or circle respectively.
- vn is the vertex number within the shape. A quadrilateral would have values of V0 through V3.
RA: The right ascension (in degrees) of the vertex (or circle center).
DEC: The declination (in degrees) of the vertex (or circle center).
Exp ID: A string of the format vv.eee where vv is the visit number, and eee is the exposure number.
Copy: An integer indicating which copy of Exp ID this line is. It can range from 1 to the Number of Iterations for the exposure.
Split: An integer indicating which CR-SPLIT of Exp ID this line is. It is always 1 for exposures without CR-SPLITs.
Primary Pattern Position: An integer indicating which pattern point in the primary pattern specification this line is. It is always 1 for exposures not in a pattern.
Secondary Pattern Position: An integer indicating which pattern point in the secondary pattern specification this line is. It is always 1 for exposures that don't have secondary patterns.
Config: The Configuration specified for the exposure.
Mode: The Operating Mode specified for the exposure.
Aperture: The Aperture specified for the exposure.
Spec Elt 1:The first Spectral Element specified for the exposure.
Spec Elt 2: The second Spectral Element (if any) specified for the exposure.
Exp Time: The exposure time (in seconds) specified for the exposure.
- MULTIACCUM exposures do not have an expsure time specified. For those exposures, this column will be blank, and the SAMP-SEQ and NSAMP columns will be filled.
- For exposure copies that have an Actual Duration value (possibly populated by the Orbit Planner Auto-Adjust feature), that value will be used.
- For CR-SPLIT exposures that don't have an Actual Duration specified, this value will be an appropriate fraction of the exposure time specified on the exposure.
NSAMP: The value of the NSAMP optional parameter, if present. Otherwise blank.
SAMP-SEQ: The value of the SAMP-SEQ optional parameter, if present. Otherwise blank.
Prime/Parallel: A string value of either Parallel or Prime depending on whether the exposure is a coordinated parallel or not.
Target: The name of the target used by the exposure.
Orient Used: The spacecraft U3 orientation (in degrees) used in calculating the aperture position. For executed visits, this will be the executed orientation. For visits with a fixed orient specified (or a Same Orient As a fixed orient visit), the fixed orient will be used. For other visits with Orient Range(s) specified, the center of the first specified range will be used. Otherwise 0 will be used.
RA Center Rot: The Right Ascension (in degrees) of the center of rotation of the exposure. This is typically the RA of the Target, but can be different for exposures in a pattern with a Coordinate Frame of "Celestial".
Dec Center Rot: The Declination (in degrees) of the center of rotation of the exposure. This is typically the Dec of the Target, but can be different for exposures in a pattern with a Coordinate Frame of "Celestial".
STC-S Coverage: This field is blank.

This file is formatted such that it can be loaded into Aladin after replacing the commas with Tabs. Aladin will plot the vertices in a plane as if each vertex were a star in a catalog. When vertices are selected in the Aladin display, the column data is displayed at the bottom.

PropID_exposure_coverage.csv file

This file provides detailed exposure information in a more compact format, one line per exposure, and is recommended as the starting point to obtain an exposure map. The columns are the same as for the coverage_catalog.csv file, with the following exceptions:

The first three columns (Name, RA, and Dec) are not included.
The file cannot be read into Aladin.
The column STC-S Coverage is populated and contains a Space Time Coordinate (STC) string defining one or more shapes on the sky, which together describe the celestial coverage of the exposure. A shape can be either a Polygon or a Circle. For a Polygon, an RA and Dec (in degrees) is given for each vertex. For a Circle, the RA and Dec (in degrees) of the center point is given followed by the radius of the circle (also in degrees). The STC-S format is discussed http://www.ivoa.net/Documents/Notes/STC-S/ .

In general, the coverage for an exposure is the union of the coverage for all shapes in the STC descriptor. The exception is the circle for WFC3/IR, which denotes an exclusion region and therefore must be *removed* from the coverage.

Using the APT Exposure Map files

In order to obtain the exposure time at a given location from the exposure-coverage file, users will need to carry out the following steps:

Identify the lines corresponding to exposures of interest. For example, an exposure map may be desired only for a specific instrument-filter combination, or only for Prime exposures, and so on.
Determine the exposure time corresponding to each line. This is given explicitly for optical/UV imagers, and implicitly from NSAMP and SAMP-SEQ for IR imagers.
Use the information in the STC-S Coverage descriptor to determine whether the desired location is inside the detector coverage, taking into account the exclusion circle for WFC3/IR images.
Add up the exposure time for all images that qualify.

If an exposure map is desired, users will need to write a module capable of repeating the steps above for a grid of positions.