eObservation Specifications are part of all JWST observation templates. The Astronomer’s Proposal Tool (APT) is used to fill out the template and schedule Observations.
Purple text indicates the parameter is Limited Access.
Boldface italics type indicates the name of an APT parameter or a value for a parameter.
Red text indicates restrictions on a parameter.
Black text indicates an important note.
Brown text indicates notes for the developers.
Green text indicates the name of the parameter used by Commanding.
Items in brackets - <value> - are required values.
Items in square brackets - [<value>] - are optional.
The Observation Specifications are used to define the proposed sequence of events that will execute on JWST to obtain the desired data. Before proceeding further, it is useful to define more carefully what is meant by a template, a group, a readout pattern, an integration, an exposure, a visit, and an observation.
Template - Unlike HST proposals, where individual exposures are defined, JWST proposals are similar to Spitzer proposals, where individual observations are defined. An Observation Template is completed which provides the necessary information for the internal scheduling software to generate the observing sequence (integrations, exposures, and visits) to execute on the telescope. The templates are selected based on an observing strategy (e.g. MIRI imaging, MIRI low resolution spectrocopy) required for your observations (note that there are a limited number of coordinated parallel template pairings available).
Group – This is a set of non-destructive read samples (also often called “frames”) that is grouped together for co-adding by the detector readout electronics. A group is the smallest collection of data within an exposure that is saved as an entity onto the data recorder.
Readout Pattern – This defines the way individual read samples (or frames) are co-added into a group (see above). It sets the number of samples to be co-added and the number of samples to be skipped (or ignored) within a group.
Integration – This is a single set of groups. An integration (sometimes called a ramp) is bounded by destructive readouts of the detector.
Exposure – This is a set of one or more integrations. The proposer will specify a set of parameters (readout pattern, number of groups, and number of integrations) which will result in the total exposure duration.
Visit – This is a set of exposures (with overheads) obtained on the same Guide Star without scheduled interruption. A Visit consists of the following parts:
- Slew to the guide star acquisition attitude
- Guide star acquisition (to point JWST at the target)
- Target acquisition (to place the target in an instrument aperture, if necessary)
- Science exposure(s) (to obtain the data)
- Instrument overheads (to set up the instrument and read out the data)
- Instrument calibrations (if more than the standard calibration is required)
There are several situations that limit the amount of science that can be done in a single Visit:
- When the total pointing change is large enough that it is no longer feasible to use a single guide star for all exposures. For moving targets, this distance is 38”. For fixed targets, see Table 1. When PCS MODE COARSE is used, the distance for all objects will be 180”. If a visit is forced to contain a position that is greater than the splitting distance, such as a Target Acquisition position, then an error will be generated. This visit can not be executed as it is.
- When the total duration of the Visit exceeds a maximum of 24 hours; but Time Series Observations can be longer. This limit is imposed for efficiency (because very long visits are hard to schedule efficiently) and to preserve flexibility to insert engineering Visits where needed.
- If different instrument templates are used, separate Visits and Observations will be necessary (see below).
Table 1. Pointing Change Requiring a New Visit for Fixed Targets
|0° ≤ |b| < 10°
45° ≤ |b| < 50°
10° ≤ |b| < 15°
50° ≤ |b| < 60°
15° ≤ |b| < 20°
60° ≤ |b| < 65°
20° ≤ |b| < 25°
65° ≤ |b| < 70°
25° ≤ |b| < 35°
70° ≤ |b| < 80°
35° ≤ |b| < 45°
|b| ≥ 80°
Observation – This is a set of one or more visits to be obtained of one astronomical field that can in principle be made at the same time. However, since a visit is the scheduling unit, there is no guarantee that all visits will execute together. For long observations, it may be necessary to break for observatory maintenance or other reasons imposed by the scheduling system. Observations are independent of each other unless specifically linked by the observer. Any special requirements (e.g. APERTURE PA) placed on an Observation will apply to all Visits in that Observation.
Note that not all of the fields described below are available for all instrument templates.
The following policies and constraints apply to Observations:
- The estimated spacecraft time for an Observation will include a statistical estimate based on the average time to slew to the attitude of the first Visit from an unknown attitude (30 minutes; this number is documented in the Project Reference Database ). This is referred to as a major slew. If the Observation contains multiple Visits, each Visit after the first will incur additional slew time. The time for these minor slews – from the pointing of the previous Visit to the current Visit – is a function of the distance between the visits.
Note that observations which are determined to be candidates to be scheduled back to back, will generally incur the minor slew rather than the major slew. This analysis is part of what is included in "Smart Accounting".
- Observations are designed for a single astronomical field that allows back-to-back Visit scheduling. There is no hard limit on the total pointing change within an Observation, but there are practical limits imposed to limit the complexity of managing Observations and to preserve flexibility in planning and scheduling.
All Visits within an Observation are implicitly SAME APERTURE PA. Executing each Visit at the same position angle ensures they can be scheduled at the same time, consistent with the assumptions used for slew time estimates. SAME APERTURE PA also facilitates creation of a uniform mosaic.
Visits within a multi-visit Observation are implicitly GROUP VISITS WITHIN 53 DAYS. This is interpreted in the same manner as GROUP OBSERVATIONS WITHIN across observations : the last Visit to be scheduled will start within 53 days of the start of the first. This restriction forces the Visits into the same target visibility window. Except near the ecliptic, the span of the observation is limited by the SAME APERTURE PA constraint (to a minimum of ~10 days at the ecliptic poles).
If it is necessary to further restrict the total duration of an observation, a GROUP VISITS WITHIN <duration> Special Requirement may be placed on the Observation. The specified <duration> may not exceed 53 days.
- The total duration of an Observation is subject to limitations in order to preserve scheduling flexibility.
- APT limits the total number of frames in any one exposure to 196608 frames per detector. The total number of frames in an exposure is:
NUMBER OF INTEGRATIONS/EXPOSURE * NUMBER OF GROUPS/INTEGRATION * NFRAME
where NFRAME is number of frames per group, and is a property of the readout pattern. For more information see Understanding Exposure Times.
Note for developer: The value of NFRAME for each readout pattern is provided in the PRD Datamode table. The value for maximum frames in an exposure is also provided in the PRD in Observing_Limitations.max_total_frame frames per detector.
By default, STScI may interrupt an (multi-visit) Observation to insert other science or engineering Visits. If it is important for an Observation to be executed without interruption, a GROUP or SEQUENCE NON-INTERRUPTIBLE Special Requirement should be placed on the Observation. Because long non-interruptible observations create the same scheduling problems as long Visits, the total duration of a non-interruptible observation may not exceed 24 hours .
Observation Folder - Observation Folders allow you to keep related Observations in one place. You can organize and even label your multi-observation science program in ways that are helpful to you and your Co-Is, such as by target, instrument, or science mode (e.g. coronagraphy sequence). For more on Folders, see APT Observations.
These folders are for convenience, and in general do not imply any scheduling constraints or data reduction implications. Note that the structure and folder labels are not passed to TAC's view of the proposal, nor to the archive after execution. However, in the case of a mosaic that must be split into separate Observations, APT will create an Observation Folder to keep the primary mosaic associated with an individual tile or tiles that have been split off. In this case the Observation Folder does imply an association to the data reduction pipeline.
There are 2 option fields associated with Observation Folders:
Observation Folder Label
You can assign a label to each Observation Folder. This allows you to call each Observation Folder by a name that has some scientific meaning. For example, if an Observation Folder is to perform coronagraphy of Beta Pic, you could label the Observation Folder "Beta Pic Coron".
Observation Folder Comments
The comments field should be used to record observing notes to yourself and your Co-Is. It should generally not be used to specify scheduling requirements because comments are not interpreted by the software. An example of an Observation Folder Comments is:
- Epoch 2 observations of Target X
You must assign each Observation a unique observation number ranging from 1-999.
This keyword should be selected when the observation duplicates, or might be perceived to duplicate, previous or upcoming GO and/or GTO exposures; see JWST Observation Duplication Checking for more details.
You can assign a label to each Observation. This allows you to call each Observation by a name that has more meaning than just the observation number.
For example, if an Observation is to mosaic M57, you could label the Observation “Ring Nebula”.
Select the desired science instrument (MIRI, NIRCam, NIRSpec, or NIRISS).
Instrument Mode Templates
Choose a target from the Target List you previously entered. In the case of certain internal and external calibration sources, a special code must be used (see Special Target Names).
(available only when CATEGORY=SURVEY)
Enter the number of fixed targets which will be supplied to be observed according to the given observation specification. The full target list will be supplied after the proposal is accepted. Both the Abstract and the Scientific Justification must provide details characterizing the target list. For more details. see Survey Programs.
The target name should be selected from the Target List (see Fixed Targets, Solar System Targets, or Generic Targets ). The Name in the Proposal is used only in the proposal, while the Name for the Archive is used for the archive.
If a calibration observation is requested, one of the specific “target” names in Table 2 must be chosen. The calibration source should not be inserted in the Target List; these sources will be available by default.
Table 2. Special Target Names
for pure parallel observations. The target will be wherever the parallel aperture happens to point.
for spacecraft mode observations
Specific astronomical objects used as external calibrators (e.g., standard stars) should be inserted in the Target List as normal targets.
ETC Wkbk. Calc ID
You can include the name of the ETC Workbook Calculation ID for each target acquisition and science exposure. This field is optional for science exposures, but you will get a warning if you do not populate it for target acquisition exposures.The format is: Your ETC workbook number followed by a decimal point, then the Calculation ID. Example: 1234.9.
Special Requirements for Scheduling JWST Observations
A variety of Observation-level Special Requirements may be chosen; these requirements apply to all Visits in the Observation. These requirements will be interpreted by the software that is used to schedule the observations. If none of the allowed Special Requirements appears to be sufficient, you can describe the requirements with a text explanation in Observation Comments . You should contact the JWST Help Desk at jwsthelp.stsci.edu prior to entering such a comment in your proposal.
Several of these Special Requirements require the use of limited resources or may impose serious constraints on the scheduling system (e.g., APERTURE POSITION ANGLE , AFTER OBS BY , BETWEEN ). Use these Special Requirements with care.
The observation-level Special Requirements are of 4 types:
- General Special Requirements
- Timing Special Requirements
- Aperture Position Angle Special Requirements
- Solar System Special Requirements
On Hold Comments
If you have requested, via the Special Requirement ON HOLD , that a given Observation be placed “on hold” (which means that the Observation will not be scheduled until you have cleared the hold), then indicate why the Observation is on hold, and how the hold is to be released. Examples of On Hold Comments are:
- Waiting for Early Acquisition data from Observation <number>
- Waiting for non-JWST data [to be obtained <date>]
- Waiting for Position Angle assignment for NIRSpec MSA observations
- Conditional if <text>
- Conditional on <observation-list> if <text>
- Select <number> of <observation-list>
Some observations with JWST will be obtained as mosaics of large objects; see Table 3 and Table 4 to determine if a science or engineering template supports mosaicking. Choose the mosaic pattern to be used.
Table 3. Mosaic Support for Science Templates
MIRI Low Resolution Spectroscopy
MIRI Medium Resolution Spectroscopy
MIRI Coronagraphic Imaging
NIRCam Coronagraphic Imaging
NIRCam Time Series
NIRCam GRISM Time Series
NIRCam GRISM Spectroscopy
NIRSpec Multi-Object Spectroscopy
NIRSpec Fixed Slit Spectroscopy
NIRSpec Integral Field Unit Spectroscopy
NIRSpec Bright Object Time Series
NIRISS Wide Field Slitless Spectroscopy
NIRISS Single Object Slitless Spectroscopy
NIRISS Aperture Masking Interferometry
Table 4. Engineering Templates that Support Mosaics
MIRI Imager Flat
MIRI MRS Flat
MIRI Coronagraphic Photometric Calibration
MIRI MRS Cross-Grating Engineering
NIRCam External Flat
NIRISS Internal Flat
NIRISS External Calibration
FGS External Calibration
Yes (Imaging only)
The comments field should be used only to record observing notes; it should generally not be used to specify scheduling requirements. Comments are not interpreted by the software, but are maintained in the database and do appear on printouts of the proposals. An example of an Observation Comments is:
- Mid-IR observation of Target X
Maximum Exposure/Visit Duration
Solar System Targets Scheduling Duration
See also: Moving Target Acquisition and Tracking
Maximum Number of Dithers
Although it is quite high, there is a maximum number of dither points allowed per visit which APT will enforce.
APT issues an error or warning for visits that generate data volume in excess of certain thresholds (see JWST Data Volume and Data Excess). For observations linked by a NON-INTERRUPTIBLE special requirement, data volume is summed and is also subject to data excess limitations. Excess data thresholds are specified in the observing_limitations table of the PRD.
- PROPINSTJWST-91607 Added Targets Requested section.
- PROPINSTJWST-91600 Added Solar System Targets Scheduling Duration section.
Version 12 (October 19, 2021)
- PROPINSTJWST-91489 Added Data Excess section
Version 11 (June 30, 2011)
- PROPINSTJWST-91472 Added restriction on maximum frames in the Observation section.
Version 10 (April 16, 2019)
- Editorial change (moved change log to main article)
Version 9 (October 2, 2018)
- PR 89731 - Added explanation of parameter format to ETC Wkbk.CalcID section.
Version 8 (February 8, 2018)
- Added Coordinated Parallel parameter.
Version 7 (November 24, 2017)
- PR 87895 - updated Exposure field labels to Groups/Integration and Integrations/Exposure
- PR 86461, PR 87906 - noted limit on time series observations
- PR 88984 - noted limit on number of dither points
- PR 86725 - added Duplication flag
- PR 89343 - updated moving target visit splitting distance
- PR 85692 - added ETC ID field for science exposures
Version 6 (March 30, 2017)
- Removed/updated several TBD/TBR notes per meeting with Matt Lewis.
- Revised description of integrations, groups, etc. based on feedback from Paul Goudfrooij.
- Added On Hold example for NIRSpec MSA observations.
Version 5 (September 12, 2016)
PR 85563 - added definition of Observation Folder to the Introduction
Version 4 (August 23, 2016)
PR 85188 - updated restriction on pointing change (Visit definition, first bullet under amount of science time in a visit)
Version 3 (June 29, 2016)
Editorial - removed SEQ VISITS notes from Observation bullet 5
Editorial - revised special requirement name for NON-INTERRUPTIBLE in Observation bullet 7
Version 2 (May 30, 2016)
PR 81679 - replaced "program" with "proposal"
Version 1 (March 21, 2016)
This is the converted Word File from Chapter 5.