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. 


Main article: JWST Astronomers Proposal Tool Overview
See also: 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 ImagingMIRI 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 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 software calculates 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.  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 to the JWST TAC panels as part of the proposal assessment process.

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 selection from 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.

Figure 1. Example of APT Observation folders

Example of APT Observation folders

This is a way for users to organize and annotate their observations as they craft their proposal. The figure shows the main Observations folder in the APT tree editor for an example proposal in the JWST APT Simple Mosaic Example page. The main Observations folder contains 2 additional folders created for organizational purposes. The first folder contains 2 observations of the galaxy M83, and the second folder contains a single observation of M82. Each folder and observation title was made by entering descriptive information in the label field in the relevant GUI.

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: Reviewing APT Errors and Warnings help file, (prepared for HST but useful for JWST proposers as well).  There is also video help on this topic: .

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, when a target is selected, on the line labeled Visit Splitting are two gray boxes: 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 is 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.

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.

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 four 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. Once an observation template is cleared of errors, it can be run through the Visit Planner to check its schedulability.

Figure 2. NIRCam time series template with science parameters panel

A NIRCam time series observation template with the science parameter panel at the lower half of the page. Contents of the NIRCam Time Series form are displayed, showing sections for target acquisition and time series parameters. Note that there are no dither parameters because it's not allowed for this time series mode. The Mosaic Properties tab is not there because it's not relevant to time series observations. The last two tabs, Special Requirements and Comments are present in all science parameter panels.

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.


JWST technical documents

Block has been set to pdf-hide. Contact Shireen if you enter references

Last updated

Updated November 2, 2018

  • Minor updates and links added for Nov. 5, 2018 update.

Updated November 21, 2017

  • Minor updates and links added for Nov. 30 release support.

Updated June 14, 2017

  • New figure 2 added

Updated May 12, 2017

  • Figures 1 and 2 modified

Published March 30, 2016

The format for 'Last updated' is shown below. Enter updates above this internal"Comment" box. Only enter major updates (not typos or formatting changes).

Updated April 5, 2017

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam fermentum vestibulum est. Cras rhoncus. 
  • Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed quis tortor. 

Published March 2, 2017