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 is under continuous development and improvement, and subject to updates. Current documentation is based on APT v2020.4 and v2020.4.1, and may be revised with future APT releases.
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
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.
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.
* Bold italics style indicates words that are also parameters or buttons in software tools (like the APT and ETC). Similarly, a bold style represents menu items and panels.
APT allows JWST users to perform a number of key functions in the proposal process:
- specify general proposal information (e.g., Title, Abstract, PI, Co-Is, etc.);
- specify 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 against existing and planned JWST observations for possible duplications;
- submit JWST proposals (including archival/theory proposals) to STScI for review.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 cleared1, 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 Tool 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.
1 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.
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.