Getting Started with APT for JWST


This document provides a high-level description of the basic structure of APT, and shows you how to create a new proposal, fill in the information, and process the proposal (click here to see the movie). APT provides a graphical and interactive means for developing a proposal. To assist users in learning APT, short (typically 5 minutes) movies will be available to describe detail of tools such as the Visit Planner; see below for more details.

Screen Layout and Tools

The APT display window and basic capabilities are described in (click Introduction to the APT Interface).


APT is an interactive tool, so written documentation (with snapshots of the screen) is not the clearest way to explain how to use APT. We will therefore be generating short (typically about 5 minute) movies, which will be available over time. Written document (such as this file) are currently available at JWST APT Training Examples and Video Tutorials.

Using Context Sensitive Help

Context Sensitive Help is available in APT for the Form Editor. To use this feature, put your cursor on the parameter of interest. If that parameter is blue, you will see the cursor change to . If you then click on the parameter, the relevant sections of the documentation will then be displayed in your browser.

Other Help

- HST What's New/Roadmap - these are for HST only

- JWST What's New - provides a description of major new features or changes for the cycle

- Under the File Menu, there are several JWST Demonstration Proposals to help you get oriented with APT.

- The Help menu currently points to HST-specific documentation, and should not generally be used for JWST. Eventually, the equivalent types of documentation will be available.


Diagnostics are shown with either a (error) or a (warning). Errors are either missing information, incomplete or illegal information, or a problem reported by the Visit Planner. There are four ways that diagnostics are reported in APT. Note that in the spreadsheets, red highlighting replaces the in marking incomplete or incorrectly specified values.

Saving Proposal Information

It is advisable to save your proposal (by selecting the Save or Save As option from the File menu) frequently to avoid any potential loss of data. Backup files are also generated each time you load or save the proposal. Note that results from running the Visit Planner are stored in the proposal file. Therefore, even though you have made no edits to the proposal, new information may be present which will cause APT to prompt you to save prior to exiting.

Step-by-Step Procedure

The APT is very flexible about the order in which you enter information. You can work on a proposal element (e.g., a target) by clicking on it in the Tree Editor and selecting a tool to operate on that element. Below is one process for creating a proposal.

  1. Start APT and load a proposal. Under the New Document menu, select New JWST Proposal. If you want to read in an existing proposal, then under the File menu, select Open or Open Recent and browse to where your file is.

  2. Start the Form Editor by clicking on this tool in the toolbar; if you opened a New JWST Proposal, you will be in the Form Editor by default. Click on Proposal Information in the Tree Editor, and fill in the Title and Abstract, and if the default values are not appropriate, the Category and Cycle. You will also need to select the Scientific Category and Science Keywords, as well as provide a file name for the PDF attachment.

    Those items marked with a in with the Form or Tree Editor are either incomplete or have incorrect values. A finished proposal should have no (and few, if any, warnings) present on any page or in the tree editor. The diagnostics may suggest what is missing.

  3. Navigation. At the bottom of the form are buttons that can be used to navigate through the various proposal forms in a suggested order. The left arrow button goes to an earlier form, the New button allows for the creation of appropriate proposal elements, and the right button goes to the next form in the suggested sequence. Alternatively, the Tree Editor can be used to select any proposal element at any time.

  4. Fill in the Proposal Description. Click on the navigation button below the form to go to the next form, the Proposal Description. This page includes only the Observing Description.
  5. Fill in the PI and Co-I information. Click on the navigation button below the form to go to the next form, the Principal Investigator Form. Alternatively, click on the PI element in the Tree Editor. If you are on-line, enter your last name (or the first few characters of your last name) and either tab or hit return. APT will do an address lookup from the STScI address database. If you locate your name, select your record in the Lookup window and hit Select, which will populate the required address fields. If you are unable to find your information then hit the Add New Investigator button, which will take you to the ProPer tool so that you can add the new person to the database. If you are in the database, but the address information is wrong, then click on the Update This Address button, which will again take you to ProPer so you can update the information. See the address FAQ for more information.

    Navigate to the Co-I page and enter your Co-I information. Use the New pulldown under the toolbar to add more Co-Is. To delete an unused Co-I template, select the item in the Tree Editor, go to the File menu, and select Delete.

  6. Target Form. Continue to the Target form. There are several options - a fixed target (manual entry or a target resolver), Target Group, a solar system target, and a generic target; NIRSpec reference stars are included in the MSA configuration. There is also a fixed target import capability).

  7. For a fixed target, specify the Name, Category, Description, and Coordinates. If relevant, also supply the Extended keyword, background observation request, proper motion, and/or parallax values. For Solar System targets, detailed ephemeris information is required, while for Generic targets, on the general criteria (e.g. the next supernova) is required,

  8. Create an Observation Folder. After completing the target specification, you can start specifying your Observations. Select Observations, and then New Observation Folder. Select the MSA Planning Tool tab if you want to use the MSA tool. If you want to label the observation folder, or include a comment, fill in those fields. The Observation Folders can be used to organize your Observations (for example, a separate folder for each instrument, and separate folder for each epoch, etc.), or you can include all Observations in one folder.

    The table will give a summary of your observations once you have populated the observing templates.

  9. Edit an Observation. To edit an Observation, either select it in the Tree Editor, use the navigation button, on click in the continuing editing box. This form is where you will you select your observing template, and fill in the details. You should fill in the label (if desired), select the instrument, template, and target. Note that when you select a template, the template parameters appear in APT. The next lines provide information on Visit Splitting, accounting, and Data volume (and will be updated as the template is completed).

  10. Populate a Template. Enter the required information into the template. Once the readout parameters are completed, the Total Dithers, Total Integrations and Total Exposure Time will be populated. As the individual filter lines are completed, the accounting information is populated.

    If you were doing a mosaic, you would go into the mosaic tab (document, movie). If you had any special requirements, you would go into the Special Requirements tab (document, movie)

  11. Create other Observations as required, by clicking on the New/New Observation button above the form. If other Observations are similar to an existing one, it may be expedient to duplicate the Observation by clicking on it in the Tree Editor and selecting Duplicate (or Multiple Duplicate) from the Edit menu. An alternate method for copying exposures is to use the Copy and Paste option in the Edit menu; see the movie on Editting with the Tree Editor .
  12. Visit Planner. Now run the Visit Planner and adjust parameters to increase schedulability, if necessary. See the Visit Planner document and movie for more information.

  13. Save your work. Throughout the above process, it is advisable to save your proposal by clicking on Save (or Save As) in the File menu.
  14. Create another Observation Folder if required, by clicking on Observations in the Tree Editor and then clicking on the New Observation Folder button. Alternatively, if subsequent folders are similar to an existing folder, it may be expedient to copy/duplicate that visit by using the Copy/Duplicate menu item in the Edit menu. Note that it is possible to copy/duplicate multiple visits at a time (by clicking on the first visit in the Tree Editor, shift-clicking on the last visit, and the selecting Copy/Duplicate from the Edit menu).
  15. Process the new Observations.
  16. Use the Aladin tool. Optionally, look at your exposures in the Aladin tool. See the Aladin help and movies for more information.
  17. Run Smart Accounting. After you have completed all your observations and run them through the Visit Planner, you should run Smart Accounting.
  18. View the proposal in PDF format by selecting the PDF Preview tool. You can select either the TAC view or the detailed operational view; the operational view is shown below.

  19. Submit the proposal by selecting the Submission tool. Type in any comments that you have, and click on the Submit button. In the Submission Log window you will see a message giving the time of the submission, the assigned proposal ID (if a new proposal), and the submission status. The PI and all CoIs will receive an automatic email acknowledgment that the merged PDF submission was received successfully.

Last modified: December 4, 2017.