Astronomers Proposal Tool

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.1, and may be revised with future APT releases.

See also: JWST APT Help Features and Master List of Help Videos

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.




On this page



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. 

Figure 1. The annotated front page of a new JWST APT proposal

Appearance of a new JWST proposal in APT. The 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, we label several portions of the APT GUI.  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 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 Functionality

See also:  JWST Cycle 1 Proposal Opportunities and JWST Cycle 1 Proposal Checklist and Resources

APT allows JWST users to perform a number of key functions of 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 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.

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, one can view and save target confirmation charts using the icon on the Top Tool Bar. 

Observations

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.

Observation templates

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.

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

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

Total time accounting

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.

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

JWST proposal submission 

See also: JWST Cycle 1 Proposal Checklist and Resources

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 ServiceNow 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 Training Examples and Video Tutorials and JWST APT Help Features

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.


Related Links

JWST Cycle 1 Proposal OpportunitiesJWST General Science Policies

JWST Observing Overheads and Time Accounting Overview

JWST Observatory and Instrumentation Documentation

Acronyms and Abbreviations




Published

 

Latest updates
  • 16 Aug 2019
    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