Exposure Times
APT: Planning
You Need to Know ...
Software, Mock Catalog

You need to lay out all of your program in the Astronomer's Proposal Tool.

The proposal procedure is more like that for Spitzer than for HST: you need to complete the detailed observation planning as part of the initial submission.

To get started with the Astronomer's Proposal Tool (APT), download it from http://www.stsci.edu/hst/proposing/apt and install it. Follow the instructions to bring it up on your computer.

Those who have used the HST APT will find the JWST one familiar.

Once you have the APT available on your computer, follow this guide for a general workflow for creating an Astronomerís Proposal Tool (APT) file for JWST observations using APTv25.4.2.  Click here for information on the current release and instructions for downloading and installing the APT. 

 The JWST Helpdesk is here.  APT Training Examples can be found here.

 To begin, bring up APT and select New Document -> New JWST Proposal: 

 or load a demonstration proposal (File -> JWST Demonstration Proposals) or an existing proposal on your computer (File -> Open) or from the STScI servers (File -> Retrieve from STScI).

 A JWST proposal contains the parts (Proposal Information, Targets, Observations, Observation Links) outlined in the Tree structure on the left.  To enter proposal information--such as the proposal title, description, investigators, etc.--make sure the Form Editor is highlighted on the top panel and select the relevant sub-pages. 

 You can see that we have red x's next to a lot of fields.  This indicates an error, in this case due to missing information.  A "!" in a yellow triangle indicates a warning.  You can hover your cursor over these errors and warnings to get more information. 

Next, enter targets.  The fixed target resolver will find populate the information on known targets from databases such as NED or SIMBAD.  To enter the information for a target by hand, select New Fixed Target. 

 Top panel: Required fields are Name in the Proposal, Category, Description (keywords), and RA/Dec.  Optionally, you can specify the uncertainty in RA/Dec, and whether the source is extended (this is flagged for later when it goes through the standard reduction pipeline).  Middle panel: If this target requires a dedicated background observation, you can check the box, which will open a panel where you can link this target to its background observation, which you will create later.  Bottom panel: specify if your source has a proper motion.


 Next, create an observation.  Create an Observation Folder by clicking on Observations and then selecting New Observation Folder in the main window (alternatively, right click on Observations and select New Observation Folder).  You can have multiple observation folders and an observation folder can contain multiple observation setups using multiple instruments.  Organize as you see fit. 

Click on your new Observation Folder in the Tree.  Here you find a summary of your observations and the Micro-Shutter Array (MSA) Planning Tool (MPT).  If you are planning a NIRSpec MSA observation, you will need to generate an Observation using the MPT.  This process will not be described in this guide, instead we direct you to the JWST documentation on the MPT.  For any other observation, click on Observation 1 and select your instrument template.  We'll look at a simple case of MIRI imaging.  Guides for all the APT observing templates can be found here.  If you are doing coordinated parallels, head here.



 Select your target and define your exposure setup (dithers, filters, detector setup).

  If you want to mosaic, click on Mosaic Properties and add tiles.  You can see their overlap, if you want them offset relative to each other, and remove tiles by hand under Tile State. 

 There are two fields that are automatically populated by the template as you set up your observation.  First is the visit splitting distance and number of visits.   A new visit is required when JWST needs to (re-)acquire guide stars and each new visit incurs significant overheads.  The visit splitting distance, which varies from 30-80" and depends on the Galactic latitude of your target, is how far JWST can move before APT creates a new visit.  In this example, creating a 2x1 mosaic triggered a second visit. 

 If you have multiple targets within the visit splitting distance (for example, multiple IFU pointings on an extended target) that will have the same exposure setup, you can save overheads by grouping your targets in a Target Group under Targets -> Create Target Group.  This will minimize the number of visits in your program.

 Also automatically populated is the duration in seconds of your science time and total charged time.  Note also the data volume, particularly if you are doing coordinated parallels.

  A more detailed explanation of your science and overhead charged times can be found by going to File -> Export, and exporting the .times file.  This text file can be useful for visualizing your entire program and checking where your biggest inefficiencies are if you are concerned with the total charged time of your program.   


 Finally under Observation 1, in the last two sub-menus, you can define special requirements, such as scheduling constraints, and add comments.

Visualize your program using Aladin by highlighting a Target, Observation, Observation Folder, or the top of your proposal Tree to see everything and clicking View in Aladin in the top panel.  This will open up a separate window Aladin window where you can load background images, etc.


 Back in the main window, you will see the Aladin control panel where you can toggle on and off different options (like Orient Ranges so that you can visualize and manipulate the position angle [PA]).  Changes you make to your observations (changing the PA, dragging a target) via Aladin will also appear in this panel and you will need to "commit" changes in order to have them saved in the proposal proper.

  To get out of Aladin and continue modifying your proposal, click back over to Form Editor. You can leave the Aladin window open to go back to it later most of the time, though it can be buggy. 

You can also visualize your targets by running Target Confirmation.  This will generate a PDF that shows your target position on a DSS image.

 Once you are happy with your observation setup (or if you have given up on improvements), run the visit planner.  Select Observations in the Tree and then click on Visit Planner.  Click Update Display on the bottom.

  A green check indicates that your observation is schedulable and you can see the potential windows for Cycle 1.  If you do not get a green checkmark, click on the arrow to expand the menu and see what factors are limiting the scheduling of your observation. 

 It is also useful to click on Reports to see the Guide Star Availability and Roll Analysis for your visits.  This opens a new window that shows you information on your visits and the PA ranges associates with certain dates.


 The Visit Planner will need to be re-run as you change your proposal.  Additionally, APT needs to run Smart Accounting.  Smart Accounting minimizes your program overheads by looking at all your observations and optimizing how they can be scheduled to avoid, for example, charging you unnecessarily for two full (1800 s) slews (at this time, all programs are charged one full slew at the beginning of their observation(s)).   Smart Accounting usually runs automatically when you update the visit planner, but occasionally you will need to run it manually.  You can do so from the Visit Planner page and the menu (Visit Planner -> Force Run Smart Accounting). 

 When you are done in the Visit Planner, click back over to the Form Editor.

 The last sub-menu in the Tree is Observation Links.  Here you can link observations across your proposal in order to i.e. constrain them all to be at the same PA, require that they are done in some order, etc.  Some of these are redundant with options in the Special Requirements sub-page in the individual Observations, but probably good just to set it in both places.

  Once you are happy with your proposal, go back to the Proposal Information page where you will see that the Science Time and Charged Time has been automatically populated.  If Smart Accounting hasnít been run recently, you will see an option to run it pop up here.  Also check now for any remaining Errors or Warnings.


If you can't solve your remaining errors or warnings, ask the helpdesk.  Occasionally you will have warnings that you cannot remove because of bugs or work in progress on the APT.  You can still submit with these and will be asked to explain why they are not a problem at the submission stage.

To submit, you will need to run Target Confirmation, then click Submission, which will bring up a page with a place for submission comments and a submission log which tracks resubmissions.