Example Science Program #33 APT Guide

Instructions are provided for filling out the JWST APT observing template for the Galaxies in Lensing Clusters Example Science Program, where NIRISS WFSS is a prime observing mode and NIRCam Imaging is executed as a coordinated parallel observation.


Main articles: NIRISS Wide Field Slitless Spectroscopy, NIRISS WFSS Template APT Guide, JWST APT Coordinated Parallel Observations
See also: JWST APT Training Examples and Video Tutorials

The Astronomer's Proposal Tool (APT) is used for submitting JWST proposals. There are multiple components to an APT submission: generic proposal information, target information, and exposure specifications for the proposed program. This guide discusses how to fill out the APT observing template for the "Using NIRISS WFSS and NIRCam Imaging to Observe Galaxies Within Lensing Clusters" Example Science Program.

A filled out APT file can be downloaded here for reference. The APT file was created with version 27.1. There may be inconsistencies or additional warnings or errors with other versions of APT.

Fill Out Proposal information

Main article: JWST Astronomers Proposal Tool Overview

After opening APT, we selected "New JWST Proposal" under the "New Document" pull-down menu. On the Proposal Information page, we entered Title, Abstract, and Category of the proposal and kept Cycle number at its default value. We updated Scientific Category to Cosmology and added the following Science Keywords: Clusters of Galaxies, Cosmological Parameters and Distance Scale, Extragalactic Legacy and Deep Fields, Gravitational Lensing, and Reionization. In Alternate Category, we entered Galaxies and the IGM.

Note that APT issues errors in the Proposal Information page since Category is set to GTO (which is reserved for GTO proposers whose programs should already be marked as approved in the proposal database) and a PDF science justification is not uploaded. For the purposes of this tutorial, it is fine to ignore these warnings. However, for proposals submitted in response to the Call for Proposals, ensure the Category field is correctly set and that you upload a PDF of your science justification prior to submission.

Enter Proposed Targets

Main article: APT Targets

Target information is entered by selecting Targets in the Tree Editor, which provides options in the Active GUI window. In our case, we chose the New Fixed Target button, entered MACSJ0416.1–2403 in the field for Name in the Proposal, and selected Clusters of Galaxies for Category. We entered the coordinates for this source: RA = 04 16 9.40, Dec = -24 04 04.00. Near the Description field, we clicked the "+/-" button which opens a list of approved keywords and selected Rich Clusters.


Main articles: APT Observations, JWST APT Coordinated Parallel Observations

Selecting Observations in the Tree editor, we clicked on the New Observation Folder. In the Label field, we entered MACSJ01416.1–2403 NIRISS WFSS Prime NIRCam Imaging ParallelNote that while this label is not required, setting it is useful for visually organizing your observation folders when potentially many targets and/or instrument setups are used.

We clicked "Observation 1" in the Tree Editor to open the observation template to be filled out. In the Prime Instrument pull-down menu, we selected NIRISS, and then selected the NIRISS Wide Field Slitless Spectroscopy template in the Template pull-down menu. We checked the Coordinated Parallel checkbox and selected NIRISS WFSS-NIRCam Imaging in the pull-down menu. In the Target pull-down menu, we selected the target we defined above, MACSJ01416.1–2403.

Complete APT Observation Template for NIRISS WFSS

Main article: NIRISS WFSS Template APT Guide
See also: NIRISS WFSS Dithers, NIRISS WFSS Recommended Strategies

As discussed in the parent article and the Step-by-Step ETC Guide, a set of observations will be taken through three filters: F115W, F150W, and F200W. Both the GR150C and GR150R grisms are used, with an 8-step dither pattern. In the NIRISS WFSS template, a direct image is automatically taken before and after each set of dithered grism exposures. An exposure sequence through a NIRISS filter is thus:

Direct Image → 8 × GR150C → Direct Image

Direct Image → 8 × GR150R → Direct Image

In the "Science Observation" window, we updated the number of Dithers in the pull-down menu to 8, and kept Pattern Size at the default value of Medium (see NIRISS WFSS Recommended Strategies for a discussion about the trade-offs of different dither sizes and number of dither steps). We clicked the "Add" button to add an entry to the "Sequences" window. We selected GR150C in the Grism field and F115W in the Filter field and keep the default Readout Pattern of NIS. We entered 23 in the Groups/Int field and 1 in the Integrations/Exp field ("Sequence" #1). As discussed in the Step-by-Step ETC Guide, these exposure specifications will provide the desired signal to noise ratio (SNR) for the WFSS observation.

Though an option exists in APT to select BOTH grisms when specifying parameters in the Science Observation window, this would result in a single sequence in which we would have to specify the NIRCam setup in parallel.  As the CANUCS program wishes to observe in two separate short-wavelength/long-wavelength pairs of NIRCam filters for each NIRISS blocking filter, we must specify separate GR150C and GR150R exposure sequences.

Note that entering a grism exposure in the "Science Observation" window automatically adds a blank entry in the "Direct Image Exposure Parameters" window, where the filter will automatically match that of the WFSS exposure. In the "All Exposures Display" field, the order of exposures is listed. The entries of these fields cannot be edited directly. Instead, any updates made in the "Science Observation" field and "Direct Imaging Exposure Parameters" field are propagated to "All Exposures Display."

In the "Direct Image Exposure Parameters" field, we entered 13 in the Groups/Int field and 1 in the Integrations/Exp field ("Direct Images" #1). As shown in the Step-by-Step ETC Guide, four coadded exposures from one NIRISS filter will produce the desired SNR for the imaging observation. The "All Exposures Display" shows the first exposure sequence in "Exposures" #1: Direct Image → 8 × GR150C → Direct Image.

To enter the exposure parameters for the GR150R Grism for the F115W filter, we highlighted "Sequences" 1 in the "Science Observation" window, clicked "Duplicate", and updated the Grism pull-down of this new entry to GR150R. The "Direct Images" window was automatically updated to have the same exposure specifications of the direct image of the duplicated exposure ("Direct Images" #2), requiring no additional edits. Exposure 2 in the "All Exposures Display" window shows the exposure sequence for this set of direct image and WFSS exposures.

We repeated this procedure for the F150W filter (Exposures #3 - 4)  and F200W filter (Exposures #5 - 6), using the same exposure specifications for these filters (23 Groups/Int and 1 Integrations/Exp).

Complete APT Template for Parallel NIRCam Imaging Observation

Main article: NIRCam Imaging, NIRCam Imaging APT Template
See also: JWST Parallel Observations, NIRCam Detector Readout Patterns

NIRCam Imaging exposures will be observed in parallel with the WFSS observations as part of the CANUCS program. Since each WFSS observation consists of three exposure specifications (Direct Image → 8 × GR150 → Direct Image), the associated NIRCam Imaging observation has to also be specified as three exposures. Since the primary instrument determines the total integration time per exposure, the exposure time for the NIRCam observations (specified by readout pattern, the number of groups and number of integrations) must not exceed that of the NIRISS exposure. APT will issue an error if the exposure time exceeds that of the prime exposure. For each WFSS observation, NIRCam imaging observations are taken in the short wavelength channel and long wavelength channel. 

To specify the exposure parameters for these parallel observations, we clicked on the "NIRCam Imaging" tab. In the Module pull-down menu, we selected ALL and ensured that FULL is selected in the Subarray pull-down menu.

In this program, NIRCam images are obtained for 12 filters, six in the short wavelength channel (F090W, F115W, F150W, F182M, F210M, F140M) and six in the long wavelength channel (F277W, F250M, F300M, F335M, F360M, F410M). The NIRCam images taken in parallel with the NIRISS direct images are shorter exposures and use the MEDIUM8 Readout Pattern. The NIRCam images taken in parallel with the NIRISS grism exposures are longer and use the DEEP8 Readout Pattern and follow the same dither pattern as the NIRISS grism exposures.

We clicked "Add" to add an entry to the observing template. We then selected F090W for the Short Filter and F227W for the Long Filter. Since this exposure will be observed simultaneously with the NIRISS direct image, we selected MEDIUM8 for Readout Pattern, 5 Groups/Int, and 1 Integrations/Exp (Exposure #1). 

We clicked "Duplicate" to add an entry that will be observed simultaneously as the set of WFSS dithered exposures. Since this exposure is longer, we selected DEEP8 for Readout Pattern. Notice that the number of dithers is set to 8 by default, matching the dithering of the prime observing mode. This field can not be updated. We kept the number of groups set to 5 and number of integrations set to 1 (Exposure #2).

We clicked "Duplicate" to add an entry that corresponds to the direct image after the first set of dithered WFSS exposures. We updated the Readout Pattern to MEDIUM8, so that this entry matches the first entry in the NIRCam sequence (Exposure #3). The set of three NIRCam Imaging exposures that are to be observed in parallel to the first set of the NIRISS WFSS exposure sequence in the F115W filter (Direct Image → 8 × GR150C → Direct Image) are now fully specified in Exposures #1 - 3.

We repeated the procedures above to create a set of NIRCam Imaging observations for the remaining sets of NIRSS WFSS observations, using the following NIRCam filter combination in the short/long filters: F115W/F250M (Exposures #4-6), F150W/F300M (Exposures #7-9), F182M/F335M (Exposures #10-12), F210M/F360M (Exposures #13-15), and F140M/F410M (Exposures #16-18).

Define Special Requirements

We defined an APT Special Requirement to restrict the position angle of the observation to avoid observing nearby bright stars which would adversely affect data quality.

Run Visit Planner

To determine the visibility window of our proposed observation and ensure that guide stars can be found, we ran the Visit Planner Tool, by clicking the Visit Planner icon in the Top Tool Bar. We then selected Update Display in the resulting Active GUI Window.  The Visit Planner returned with a confirmation that the observation is schedulable (green check on the selected observation) and shows us the observing window(s) for this target over the next ~19 months. 

Run Smart Accounting

To minimize excessive overheads, we ran Smart Accounting from the Visit Planner page by selecting the Run Smart Accounting option. The charged time for the observing program, including exposure time and overheads, is now accurately calculated.

APT Warning

In addition to the APT issued errors about proposal category and science justification PDF discussed above, APT issues a warning that the data volume for the JWST visit exceeds more than half of the maximum allowance. Since this program uses NIRISS WFSS and NIRCam Imaging in parallel, it is expected that the data volume for the program will be large. However, the visit does not exceed the data volume limit, and the observation can be scheduled as is.

Last updated

Updated September 28, 2018

  • Updated APT screenshots to be compatible with APT v. 26.1

Published January 5, 2018

The format for 'Last updated' is shown below. Enter updates above this internal"Comment" box. Only enter major updates (not typos or formatting changes).

Updated April 5, 2017

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam fermentum vestibulum est. Cras rhoncus. 
  • Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed quis tortor. 

Published March 2, 2017