Step-by-Step APT Guide for NIRISS WFSS and NIRCam Parallel Imaging of Galaxies in Lensing Clusters

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.

On this page

See also: NIRISS Wide Field Slitless Spectroscopy, NIRISS WFSS Template APT Guide, APT Coordinated Parallel Observations, JWST APT 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 accessed via the menu options FileJWST Example Science Proposals → NIRISS33 NIRISS WFSS and NIRCam Parallel Imaging of Galaxies in Lensing Clusters in APT. The APT file was created with version 27.2. There may be inconsistencies or additional warnings or errors with other versions of APT.

Fill out proposal information

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

See also: 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. 

Enter proposed targets

See also: 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.


See also:: APT Observations, 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

See also: NIRISS WFSS Template APT Guide, NIRISS WFSS Dithers, NIRISS WFSS Recommended StrategiesJWST Coordinated Parallels Custom Dithers

As discussed in the parent article and the step-by-step ETC guide, a set of observations will be taken through 3 filters: F115W, F150W, and F200W. Both the GR150C and GR150R grisms are used, with an 9-step custom dither pattern for coordinated parallel observations. 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 → 9 × GR150C → Direct Image

Direct Image → 9 × GR150R → Direct Image

In the Science Observation panel, we selected 9-POINT-MEDIUM-NIRCam from the Dithers pull-down menu. We clicked the Add button to add an entry to the Sequences dialog. 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 Sequences dialog, 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 panel automatically adds a blank entry in the Direct Image Exposure Parameters panel, where the filter will automatically match that of the WFSS exposure. In the All Exposures Display panel, the order of exposures is listed. The entries of these fields cannot be edited directly. Instead, any updates made in the Science Observation and Direct Imaging Exposure Parameters panels are propagated to All Exposures Display.

In the Direct Image Exposure Parameters panel, we entered 13 in the Groups/Int field and 1 in the Integrations/Exp field ("Direct Images" #1). We do not change the Two Extra Dithers default of "NO" (introduced in APT v2020.2), since that option is only recommended for the GRISM = BOTH selection in the Sequences dialog.  As shown in the step-by-step ETC guide, 4 coadded exposures from one NIRISS filter will produce the desired SNR for the imaging observation. The All Exposures Display panel shows the first exposure sequence in "Exposures" #1: Direct Image → 9 × GR150C → Direct Image.

To enter the exposure parameters for the GR150R Grism for the F115W filter, we highlighted "Sequences" 1 in the Science Observation panel, clicked Duplicate, and updated the Grism pull-down of this new entry to GR150R. The Direct Images panel 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 panel 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

See also: NIRCam Imaging, NIRCam Imaging APT Template, 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 3 exposure specifications (Direct Image → 9 × 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, 6 in the short wavelength channel (F090W, F115W, F150W, F182M, F210M, F140M) and 6 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 9 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 3 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 → 9 × 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.

Latest updates
    Added sentence in paragraph about Direct Image Exposure Parameters panel to address new Two Extra Dithers option implemented in APT 2020.2.

    Updated APT screenshots to be compatible with APT v. 26.1
Originally Published