JWST Astronomers Proposal Tool Overview

The Astronomer's Proposal Tool (APT) is a stand-alone GUI-based software package used by proposers to write, validate, and submit proposals for the James Webb Space Telescope. 

The JWST Astronomer's Proposal Tool, APT 2023.5, will be available for Cycle 3 proposers on August 24, 2023.


The JWST Astronomer's Proposal Tool is under continuous development and improvement, and subject to updates.  Minor differences between the tool appearance and documentation may occur. Please report any problems to the JWST Help Desk.

On this page

See also: JWST APT Help and Table of additional video tutorial help with APT

 APT GUI Overview Video Tutorial

APT is the official submission tool for all JWST proposals, including archival and other proposals that do not entail specifying new observations. All proposals, except Guaranteed Time Observer (GTO) proposals, go through a selection process prior to acceptance.

APT has had a long history with the HST project; a separate branch of APT is used for HST proposals. However, the JWST APT branch has many differences that are specific to the requirements and restrictions imposed by JWST and its instruments.



Basics of the APT GUI

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

APT runs on your local machine, but accesses various tools and databases over the internet for performing certain tasks. 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 of the window, just below the top tool bar that extends across the GUI as shown in Figure 1. After that, the user will only see the JWST-related options in APT. 
Figure 1. The annotated front page of a new JWST APT proposal

Appearance of a new JWST proposal in APT. When APT is first opened, a pull-down menu from the New Document tab (upper left, under the top tool bar) allows a user to choose a new HST or JWST proposal in APT. Here, New JWST Proposal has been selected, so HST-only functions such as the Orbit Planner and "BOT" (Bright Object Tool) are grayed out and unavailable on the top tool bar. Selecting different icons from the top tool bar menu or a different element from the tree editor changes the contents of the active GUI window.
In Figure 1, several portions of the APT GUI are labeled. In this and other APT articles in the JWST documentation, we will refer to these areas of the APT GUI using these names.  

The tree editor is basically a navigation tool, allowing you to jump at will from one section of a proposal to another. The top tool bar controls whether you are in a data entry mode (especially the Form Editor tool) or whether you are using one of a number of tools within APT to perform various tasks. The active GUI window is the place where various data are entered or selections are made for your proposal. The active GUI window changes based on your selection from the tree editor in conjunction with a selection from the top tool bar. Additionally, certain tasks within APT will open a separate pop-up window to supply additional functionality.

Context Sensitive Help in APT

 Note: many of the parameters on the left side of the active GUI window are links to context sensitive help in the JWST documentation—they have a dark blue color and hovering your mouse over them will display a question mark icon. Clicking on these items will take you directly to an article about that item.



APT functionality

See also:  JWST Cycle 1 Proposal Opportunities and Getting Started with JWST Proposing

APT allows JWST users to perform a number of key functions in the proposal process:

Each short section below will point you to more detailed information on that topic. (Note: topic headings are clickable.) In addition, there are several ways to get help with APT, including a number of short training videos on various topics.

Proposal Information  

Supporting information is entered in the proposal information GUI; click on the Form Editor tool in the top tool bar, then click on Proposal Information in the tree editor on the left, as shown in Figure 1. The JWST APT proposal information form contains entry areas for required information about each JWST proposal, such as Title, Abstract, proposal Category, and so forth. Red X icons indicate errors in APT, but can also simply indicate required fields for which relevant data have not yet been entered.

Targets

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). To verify positions on the sky, you can view and save target confirmation charts using the icon on the top tool bar. 

Observations

Users can specify observations for a target using instrument-specific observation templates; these appear in the Template parameter pull-down menu after an Instrument selection is made in the active GUI window.

Based on parameter values entered by the user, APT will decide 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. At the user's discretion, observations can be grouped into Observation Folders to help organize your proposal.

Observation templates

Standard observing templates are available for each science instrument observing mode. Each template is tailored to a specific instrument and mode of operation and only includes information needed in that mode. For example, if a target acquisition is allowed for a given mode, supporting information will be requested; otherwise, no target acquisition information is shown.

Additional tabs in the lower half of the observing template GUIs allow the user to design mosaics with identical observation specifications, to specify special requirements for the observation timing, position angle, and background, or enter other template-specific options. Certain observation templates allow selection of coordinated science parallel observations that use 2 JWST instruments simultaneously. 

Because each template is unique to an instrument and mode of use, template guide articles are available in the JWST documentation for each template. Remember that context sensitive help is available directly from within APT that points you to the relevant item in each guide article.

Visualization of observations in Aladin

See also: video help Aladin Overview in APT

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. This tool includes a control GUI within the active GUI wIndow and a separate pop-up window for the actual Aladin display.

Visit planner

See also: video help 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 tool bar. This step opens a tool in the active GUI window that can be run to verify the schedulability of your proposed observations and provide diagnostics (in the case of problems). The JWST VP capabilities are more extensive compared to that used for HST. For instance, it includes a check not only of target visibility as a function of time, but also an assessment of whether guide stars are available as a function of time. 

Separate Target Visibility Tools

For certain cases, the user may find it valuable to perform preliminary checks of a target's visibility with JWST using one of the JWST target visibility tools. Note, however, that these tools do not include guide star availability checks.

Total time accounting

Once all 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 major observatory slews. Most users will find that this step reduces their overheads, as APT assesses what observations can potentially be scheduled together. The results of Smart Accounting are automatically updated on the proposal information (cover) page.

If you are interested in understanding more about the overheads ascribed to each observation, APT contains a Timeline Tool that shows this information in a handy graphical format.

Duplication checking

See also: Identifying Potential Duplicate Observations for JWST and Policies about what constitutes a duplication.

You may find it beneficial to check for possible duplications before getting serious about your APT proposal, but once you have all the details in hand, you may need to double check that you have not specified an observation that duplicates a previously obtained or planned opbservation. (If a duplication is being proposed for scientific reasons, such as target variability, you must discuss this in your PDF attachment.)  

Eventually, observers will be able to access a duplication checking tool from an interface within APT. Until that interface is ready, users can query the Mikulski Archive for Space Telescopes (MAST) directly for existing and approved but not yet executed JWST programs. 

JWST proposal submission 

See also: Getting Started with JWST Proposing

When you have a clean run of the VP and Smart Accounting and any errors and/or warnings have been cleared, you are ready to submit your JWST proposal!  Make sure you attach the science and technical description PDF file in the Proposal Information GUI, and select the Submission icon from the top tool menu. The GUI and pop-up menus will guide you.

If desired, you can obtain a full PDF of the proposal (including the APT pages and the science PDF) prior to (or after) submission. 

If you are unable to resolve APT errors, you should contact the JWST Help Desk for assistance. If the error cannot be resolved prior to the JWST proposal deadline, fill out the "explain errors" pop-up box on the proposal submission GUI prior to submitting your proposal. 



Getting help

See also:  JWST APT Video Tutorials and JWST APT Help

See also: video help with APT Errors and Warnings

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. You 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.

A number of Example Science Programs are also available within JDox. These worked examples have accompanying ETC workbooks and APT files that users will find instructive.


Related articles

JWST APT Observation Templates



Latest updates

  • Final updates for APT 2020.1.1.

  •   Updated video links for cycle 1.

  •  
    APT Overview article elevated to the landing page position and updated.  Old overview page deprecated.


  • Updated for APT 27.1 release, including figures.


  • Article significantly streamlined and redundancy removed where possible.


  • Updated Figure 1

  •   
    Made everything compatible with APT 25.4.1 release to the extent possible.
    Added sentences regarding the ETC workbook and calc ID box on target acq and science exposure specs.

  •  
    Figure 3 updated

  •  
    Significant changes to text
Originally published