An APT observation is the basic proposal design element, consisting of one astronomical target and one JWST observing mode using a corresponding APT observation template. 

See also: JWST APT Observation Templates

Observations are the basic proposal element specified by a user to request new JWST data. Each observation uses a single APT template corresponding to an instrument observing mode (e.g., NIRCam imaging, MIRI MRS, etc.) to observe a single astronomical target. Any number of observations involving one or more instruments can be entered into a given proposal, as required by the proposed science. Multiple observations may be linked together in time and/or position angle if necessary, using special requirements. In APT, multiple observations can also be grouped into observation folders to keep the proposal organized.

Each observation will contain one or more visits, with each visit requiring a guide star acquisition. The user defines observations, and APT will determine if the observations need to be broken into multiple visits, based on various operational constraints. One common example is that of an imaging mosaic: the user defines an observation with the mosaic tile pattern, and APT defines the visits within that observation based on the separation of the tiles, with knowledge of the visit splitting distance at the target position.

In turn, each visit is defined as a group of exposures of the same astronomical field, with the same guide star, and with the same instrument observing mode (and template form). Multiple dithered exposures (offset from one another on the sky) may be obtained in a single visit if the same guide star can be used for all exposures.

---

Observations versus visits

Users specify observations of a target using instrument-specific observation templates, which appear when choices are made for instrument and mode in the active GUI window. Based on the inputs from the user, APT decides whether an observation needs to be broken into multiple pieces called visits, and each visit may involve one or more exposures on a target. Details are controlled by the exposure specification provided by the user.  

Visits are the scheduling units used by the downstream scheduling system and have implicit overheads applied, but observations are what the user specifies in APT by filling out an observation template. The number of assumed visits and information about the assumed visit splitting distance for each observation are reported in the template GUI.

APT uses a timing model to calculate the statistical and fixed observational overheads for each set of observations in order to compute the total time allocation request for the proposal. The accounting for each observation is reported in the individual observation templates in APT. Insight into these overheads can be obtained by viewing the observation in the APT graphical Timeline tool. A procedure called Smart Accounting is ultimately run on the entire proposal to update the proposal-level accounting prior to submission. APT's computed total time allocation request for the entire proposal is reported on the cover page and is available to the JWST TAC panels as part of the proposal assessment process. Estimated total data volume is also reported for information.

Observations and observation folders  

Observations in APT reside in one or more observation folders under the main Observations folder in the tree editor panel that's to the left of the APT display. An example is shown in Figure 1.

To view existing folders, click on the arrow to the left of Observations. Click on the arrow next to an Observation Folder to see the observations filed in that location.

To create a new folder, click on Observations. A tab called New Observation Folder will appear in the main GUI. Clicking on that button creates a new observation folder and a new blank observation form inside that folder.

You can add more folders, and add more observations in those folders, all under Observations in the tree editor. These folders and observations can be rearranged simply by dragging them. Using the Form Editor tool in the top tool bar, each folder and observation can be given a unique name (see Figure 1) by entering its name in the Label field.  

It's easy to use the form editor to create or edit an observation. First, click on the Form Editor button in the top tool bar. Then click on an Observation in a folder. The observation form will appear in the GUI. If it's a new observation, you'll select an instrument, a template and a target. When the template is selected, fields associated with that instrument mode appear in the active GUI window—for example, if the instrument mode requires target acquisition information, a section about it will appear in the template. You can also specify offsets such as dithering and mosaicking in most templates.

Folders are provided as a convenience for users to help organize their observations. If you are requesting observations of the same target with multiple instruments, you may use the folder structure to keep all observations of a given target together. Another user might be requesting multiple epochs of data for a target, and may organize observations into their respective folders by epoch. A user requesting a sequence of coronagraphic observations may want to gather the relevant observations into the same folder.

The only exception to this concept of folder organization is if/when one or more tiles must be split off from a mosaic due to guide star restrictions. The tool that does tile splitting for problem mosaic cases creates a mosaic folder containing both the main mosaic and the separate tile observations. In this case, this special folder keeps the separate tiles associated for data processing purposes (so a single mosaic data product can be created).

---

The observation GUI

See also: Visit Splitting, Overheads, Data Volume, APT Errors and Warnings (prepared for HST but useful for JWST proposers as well).  

There is also video help on this topic: APT Errors and Warnings.

As with other parts of APT, user interaction with the GUI is fairly straightforward and self-explanatory. Pull-down menus show the options for various parameters, and buttons like Add will display pop-up menus with selectable choices.

Dark gray boxes in the GUI cannot be edited; they are there to report information back to the user. For instance, as shown in Figure 2, when a target is selected, 2 gray boxes on the line labeled Visit Splitting are filled in:

• the box labelled Splitting Distance displays the value that APT will use for that target when deciding whether it needs to split the observations into multiple visits, based on the dither steps, mosaic tile separation or other parameters. This value is determined as a function of Galactic latitude, which is related to the expected availability of guide stars, and cannot be changed by the user.
• Likewise, as appropriate observation specifications are entered into the template, APT will report the Number of Visits it has determined in the labeled box. Gray boxes (including the Duration boxes) will update automatically as the proposal is developed.

APT also reports the Science time and Total Charged time (including overheads) for your observation on the line labeled Duration. Note that this is an observation-level assessment, and only includes overheads internal to the observation. You will see these fields update as you enter and change parameters in the observation specification. Finally, although it is not in a gray box, APT reports the Data Volume it ascribes to the observation. This is for information only and also updates as changes are made to the observation specification. A roll-up of the proposal's total data volume is reported on the Proposal Information page.

For observing modes that require information for a target acquisition, the observation template contains a labeled section for this information (see Figure 2). The observation specifications for the target acquisition should be brought forward from an appropriate ETC calculation. See JWST APT-ETC Connectivity for how to annotate this information in APT.

Various science parameters in an observing template are entered in a panel in the lower half of the observation form in the active GUI window. This section usually has up to 4 tabs; 

1. The first tab’s name is usually the same as the selected template’s name. Clicking on it opens a view containing parameters for that template’s observing specifications. Exposure information entered here should generally be based on ETC calculations. Depending on the selected template, target acquisition and dither parameter values are entered in this portion of the template. 
2. If the template allows mosaicking, clicking on the Mosaic Properties tab opens a view for specifying mosaic control parameters for the observations.
3. The Special Requirements view provides access to the controls for adding any special requirements that may be needed to constrain the scheduling of this observation, including constraints relative to other observations if needed.
4. The final tab called Comments opens a window for users to document details they wish to keep track of for their own purposes, or to provide information to technical staff who may review the proposal information. (There are several different comment areas within APT; this one is for describing observational details or strategies that may not be obvious from the template entries by themselves.)

Users can leave and return to a given observation template as many times as needed as they iterate various options in their proposal preparation. Red X's indicate errors, which might indicate something as simple as missing information or improperly specified parameters that need to be corrected. Hover the cursor over any items with red X's for a tip on what the problem is. Once an observation template is cleared of errors, it can be run through the Visit Planner to check its schedulability.

---

Observation numbers and labels

Each observation in your proposal is assigned a number when it is created, starting with Observation 1. If you would like to assign a different number to an observation, it can be changed in the Number field of your observation template using the Form Editor. Observation numbers can range from 1–999, and must not be duplicated within your proposal.

You may also choose to give your observation a descriptive label. When created, the first observation in your proposal will simply be labeled "Observation 1". Using the Label field, you can assign it a name that is more meaningful. You might label each observation after the particular science target, or, for multiple observations of the same target, the particular filter used for each.

If you give an observation a label, the observation number will be shown after the label in parentheses, like (Obs 7). Depending on the size of your screen or the APT window, this may not be visible without enlarging the width of the tree editor or using the horizontal scrollbar. As a convenience, the option is available to put the number of the observation in front of your label. To do so, go to APT → Preferences...→ General and put a check in the box next to Number First in Hierarchy.

---

Observation links

In the APT tree editor, there's an item called Observation Links. It contains an overall summary of any and all special requirements specified for linking observations in the proposal. This provides a way to quickly verify whether the links have been set as intended, and is particularly useful if you have specified repeated observations that should be similar to each other.

---

---