JWST Astronomers Proposal Tool Overview
The Astronomer's Proposal Tool (APT) is a stand-alone GUI-based software package proposers use to write, validate, and submit proposals for the James Webb Space Telescope. This article provides a high level overview into the documentation available to support users in learning and using the APT software.
The JWST Astronomer's Proposal Tool is under development and subject to updates. Current documentation is based on APT v27.2, and may be revised with future APT releases.
APT GUI Overview Video Tutorial
APT is the official submission tool for all categories JWST proposals, including archival and other proposals that do not entail specifying new observations. All proposals except GTO proposals go through a selection process prior to acceptance.
APT has many years of heritage from the HST project, and a separate branch of APT is used for proposing to HST. However, the JWST 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, 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 views are active links to context-sensitive help within the JWST documentation. 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 for that item.
APT allows JWST users to perform a number of key functions of the proposal process:
- 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 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 by choosing the form editor tool on the Top Tool Bar and then "Proposal Information" in the Tree Editor at 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 categories, and so forth. Red X icons indicate errors in APT, but can also simply indicate required fields for which no relevant data have 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, one can view and save target confirmation charts using the icon on the Top Tool Bar.
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. At the user's discretion, observations can be grouped into observation folders to help organize your proposal.
Standard observing templates exist for each observing mode for each of the JWST science instruments. 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.
Separate 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 two 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 VP 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.
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 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. 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 being 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 even before getting serious with 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.
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 on 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. 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.
A number of Example Science Programs are also available within JDox. These worked examples have accompanying ETC Workbooks and APT files users will find instructive.