The Astronomer’s Proposal Tool (APT) is a stand-alone software package used by astronomers for specifying proposed JWST observations and submitting JWST proposals for review.
The JWST Astronomer's Proposal Tool is subject to ongoing updates. The current documentation is based on APT v25.4, and will be revised as needed for future APT releases.
The Astronomer’s Proposal Tool (APT) is a stand-alone software package used by astronomers to design JWST observations and submit JWST proposals for review. APT has many years of heritage from the HST project, and much of the look and feel of APT will be familiar to users who have proposed for HST.
However, there are some important differences between the HST and JWST missions, and these differences drive many of the features users will see in JWST APT. HST is an earth-orbiting mission and allocations are given in spacecraft orbits. In contrast, the JWST orbit will allow event-driven operations, and time will be allocated in wall-clock time, which consists of both science exposure time plus an accounting of overheads. Hence, for JWST, it is important for proposals to be specified in sufficient detail so that accurate resource estimates can be made at the time of submission. Furthermore, JWST is a limited lifetime mission, and therefore a rapid turn-around time between proposal submission and JWST observations is key to maximizing the science return from the mission.
Both of these considerations drive the JWST proposal process toward a single-stream proposal process where complete (or nearly complete) proposals are created and submitted at the initial proposal deadline. It is the goal of the JWST APT to enable this single-stream submission process by making it straightforward for users to enter complete or nearly complete observing specifications at the time of the initial submission.
APT is the official submission tool for all JWST proposals, including (1) proposals from Guaranteed Time Observers (GTOs), (2) early release science (ERS) proposals, (3) general observer proposals, including survey and pure parallel proposals, (4) archival proposals, (5) theory proposals, and (6) proposals for director's discretionary time. All of these except the GTO proposals go through a selection process prior to acceptance.
APT allows JWST users to perform a number of key functions:
- specify the general proposal information (e.g., title, abstract, PI, Co-Is, etc.);
- specify the proposed targets;
- enter detailed observation specifications including instrument observing modes, mosaics, and special requirements;
- visualize the field of view on the sky for planned JWST observations;
- check the schedulability of observations using the APT visit planner;
- calculate the total science time and total time allocation request including overheads;
- check for duplicate observations against existing and planned JWST observations1;
- submit JWST proposals (including archival/theory proposals) to STScI for review.
See also: JWST Cycle 1 Proposal Opportunities
Constructing a JWST observing proposal
After opening APT, a new JWST proposal is created by selecting the "JWST Proposal" option from the “New Document” pull down menu at upper left, just below the tool bar that extends across the top of the GUI, as shown in Figure 1. After that, the user will only see the JWST-related options in APT.
Context Sensitive Help in APT
Note: Many of the item labels on the left side of the active GUI window are active links to content-sensitive help. Items with supporting information are dark blue in color, and scrolling your mouse over them pops up a question mark icon. Clicking on these items will take you directly to help with entering correct information for that item.
Proposal cover page
Supporting information is entered on the Proposal cover page by choosing the form editor on the top menu bar and then "Proposal Information" in the tree editor at left. Selecting the small arrow to the left of items in the tree editor will show subordinate sections that can be selected to enter information. The JWST APT proposal information form contains entry areas for required information about each JWST proposal. Required parameters are:
- Proposal category (GO, GTO, DD, ERS)
- Proposal cycle
- Requested proprietary period
- Science category/keywords
- PDF attachment (science justification/description of observations)
- PI and CoI information
As proposed observations are entered (see below), APT calculates the science time request and total time request (including overheads) for all observations specified, and displays these values on the proposal information page. These values are used by the JWST time allocation committee review to evaluate the proposal.
Proposers may optionally edit the following additional parameters:
- explain unschedulable observations; may be used to explain any unresolved APT errors or warnings at the time of submission. In most cases, proposers are expected to resolve errors prior to submission, but if an unanticipated situation is encountered and an STScI exception is obtained, this text section can be used to provide the relevant information.
- request custom time allocation; if the requested time allocation is different from that calculated by APT, proposers may enter a "custom time allocation." However, an explanation is required for a custom time allocation (e.g., target of opportunity observation). The APT-calculated times cannot be modified and remain visible in addition to the custom request.
- request time in future cycles; such requests must be scientifically justified.
- request coordinated observations with other facilities; see the current JWST Call for Proposals for a description of available coordinated observing opportunities with other facilities.
See also: the APT Targets article for more information.
JWST proposers must specify a list of targets, and in most cases, the target positions for each proposed JWST target. Targets may be fixed targets, solar system (moving) targets, or generic targets (e.g., ToO—target of opportunity).
Fixed targets and related information can be entered manually, from a separately created list, or can be looked up and entered from a database like the NASA/IPAC Extragalactic Database (NED) or the Set of Identifications, Measurements and Bibliography for Astronomical Data (SIMBAD) using the target name resolver within APT. To verify positions against the sky, one can view and save target confirmation charts that show target positions projected onto the sky. Generic targets (e.g., targets of opportunity with unknown coordinates) and solar system targets can also be entered. Additional targets can be added to the proposal at any time before the deadline.
Duplicate observations of previously observed or planned targets with similar observing specifications must be justified in the text of the science justification/technical description portion of the proposal, which is prepared separately and attached as a PDF prior to submission.
Observations and visits
See also: the JWST APT Observations.
Users specify observations of a target using instrument-specific observation templates. 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, but observations are what the user specifies in APT by filling out an observation template. 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. A procedure called Smart Accounting is 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 to the JWST TAC panels as part of the proposal assessment process.
See also: the JWST APT Observation Templates.
Standard observing templates exist for each observing mode for each of the JWST science instruments. These templates specify (1) the target of the observation, (2) instrument, (3) observing mode, (4) dither pattern, (5) filters/gratings, (6) exposures/readout patterns, and (7) target acquisition parameters (if applicable). As of APT 25.4.1, the exposure specifications for both target acquisition and science observations include an optional box in which you can annotate an ETC workbook identifier number and calculation number that was used to derive the exposure information. (Adding a value is strongly encouraged for target acquisitions to verify a valid specification, and APT highlights this with a warning if no ETC entry is provided.) As an example, if your ETC workbook number is 1234 and you want to reference calculation number 9 in that workbook, enter 1234.9. (No leading zeroes and a decimal separator.)
As appropriate for each template, separate tabs in the lower half of the observing template forms allow the user to design mosaics with identical observation specifications, and to specify special requirements for the observation timing, position angle, and background. The science time and total time charged for the observation (including all dither pointings, mosaic tiles, and observing overheads such as guide star acquisitions and slews) are displayed on this upper half of this form. Certain observation templates allow selection of coordinated science parallel observations that use two JWST instruments simultaneously. NIRSpec multi-object spectroscopy observations should also make use of the MSA Planning Tool, launched from the appropriate template.
At the discretion of the user, groups of observations can be placed in one or more observation folders to help organize a proposal. For example, one could create an observation folder and collect all of the observations for that target in one folder, even if different instruments are used, or a coronagraphy proposer might collect all observations of a coronagraphic sequence into a folder, and so forth. Observation folders are basically organizational tools within APT and generally do not have any direct impact on schedulability or APT operation. For certain mosaic cases, APT may create an observation folder to keep a primary mosaic associated with an individual tile or tiles that may be split out into separate observations for schedulability reasons.
The observation links selection in the tree editor changes the view in the active GUI window to show an overall summary of observations in your proposal with timing or position angle links (before/after/between).
Visualization of observations in Aladin
The Aladin tool within APT may be used to visualize proposed JWST observations as they are developed. Aladin is useful for verifying coordinates with respect to the Digitized Sky Survey (DSS) or other images, viewing dither patterns, displaying mosaic coverage and tile overlaps, and verifying the effects of fixed position angles.
See also: APT visit planner.
After one or more observations are specified in APT, the user can select an observation (or observation folder) and activate the APT visit planner (VP) from the top icon menu. The visit planner is much more extensive than for HST, including (for example) a check not only of visibility by the observatory as a function of time, but also an assessment of whether guide stars are available as a function of time. Preliminary checks of a target's visibility with JWST (not including guide star checking) may be performed using one of the JWST target visibility tools.
After running the APT VP, green checks appear on the selected observations that are considered schedulable as proposed. Bar plots versus time to the right of each observation show the specifics of the windows found by APT. If a given observation or visit within an observation is determined to be unschedulable, errors (red X’s) appear. There are a number of diagnostic plots and reports that the user can peruse to understand why the VP failed and what corrective actions they can take to correct the situation. Special requirements such as fixed position angles and timing constraints may reduce the likelihood of a schedulable observation, and should only be requested if scientifically required.
Total time accounting
See also: JWST APT Smart Accounting.
The VP can be run on individual observations or groups of observations any number of times. However, once all of the observations in a proposal have been specified, the VP needs to be run on the entire set of observations and green checks must appear on all observations for the proposal to be considered ready for submission. At this point, the user must execute the smart accounting tool to produce the final proposal-level assessment of science time and total wall-clock time needed for the program, including all the JWST major observatory slews.
As a proposal is being built, APT uses its various rules and assumptions about fixed and statistical overheads to estimate resource usage. The running of smart accounting looks at the specified targets and observations, and identifies those targets and observations that will likely be scheduled together, and reduces the resource estimates (number of JWST major slews) appropriately as it can. Thus, users may see some reduction in the overall wall clock time ascribed to their program after executing the smart accounting step. The results of smart accounting are automatically updated on the proposal information (cover) page.
Eventually, observers will be able to access a duplication checking tool from within APT1. Until that interface is ready, users can query the Mikulski Archive for Space Telescopes (MAST) for existing and approved but not yet executed JWST programs. It this check indicates potential JWST observations for your target, you should dig further by reviewing the APT files of the previously accepted program or programs using the Proposal Information Tool interface. It is the proposer's responsibility to check their final proposed observations against this listing. See also the Duplication Policy page for the definition of a duplicate observation. Any proposed duplications must be justified in the science PDF attached to your final proposal.
JWST proposal submission
See also: JWST APT Submitting Your JWST Proposal.
The final steps prior to submitting a JWST proposal with APT are:
- to run APT's visit planner and smart accounting to determine the final time allocation request for the full proposal
- to attach the science and technical description PDF file
- to resolve any APT errors and warnings; if the user is unable to resolve APT errors prior to the JWST proposal deadline, they must contact the STScI Help desk and fill out the "explain unschedulable observations" box on the proposal information form prior to submitting their proposal.
- to submit the proposal using the submission icon in the upper APT menu bar and follow the pop-up instructions.
If desired, the user can view target confirmation charts and/or obtain a full PDF of their proposal (including the APT pages and the science PDF) prior to (or after) submission. Re-submission of a proposal is allowed up to the official proposal deadline.
Proposers are encouraged to review the JWST Cycle 1 Proposal Checklist and Resources article prior to submission.
Warnings (yellow caution icons) and error messages (red X’s) generated by APT are intended to help users identify and resolve the easiest problems or inconsistencies. Hover the cursor over these icons for pop-up help with a short description. One can also get summaries of these messages by clicking the "Errors and Warnings" icon on the top tool bar or the “Errors and Warnings” box at bottom right in the GUI.
The articles linked above contain a wealth of help for using APT, including short video tutorials (usually a few minutes each) that will help you become comfortable with using the APT GUI and tools.
Astronomer's Proposal Tool