Step-by-Step APT Guide for NIRISS SOSS Time-Series Observations of WASP-39

Instructions are provided for filling out the APT observing template for the JWST NIRISS SOSS Time-Series Observations of WASP-39b Example Science Program.

On this page

See also: NIRISS Single Object Slitless SpectroscopyNIRISS SOSS Template APT Guide, 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 "NIRISS SOSS Time-Series Observations of WASP-39b" Example Science Program

A filled out APT file can be accessed after Aug. 24, '23 via the menu options FileJWST Example Science Proposals → NIRISS 31 NIRISS SOSS Time-Series Observations of WASP-39 in APT. The APT file was created with version 2023.5 (release date: Aug. 24, '23). 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 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 Fixed Target Resolver button and entered WASP-39b in the Object Name search box of the pop-up window. By clicking Select Object as Target, the target name and coordinates were imported to the APT observation template. 

We selected this target in the left-hand tree editor to enable us to provide additional information in the target GUI. In both the Name in the Proposal and Name for the Archive fields, we updated the name of the object to the more familiar WASP-39b. In the Category drop-down menu, we selected Star. In the Description menu, we selected Exoplanets. The proper motion of the source is, in this case, automatically extracted from SIMBAD.


See also: APT Observations

Selecting Observations in the tree editor, we clicked on the New Observation Folder, and in the Label field, we entered WASP-39b NIRISS SOSS.

We next clicked Observation 1 in the tree editor to open the observation template in the active GUI window. In the Instrument pull-down menu, we selected NIRISS, and then selected the NIRISS Single-Object Slitless Spectroscopy template in the Template pull-down menu.  Note that only parameters of interest to NIRISS SOSS are shown in the GUI.  In the Target pull-down menu, we selected WASP-39b which we defined above.

Complete APT observation template for NIRISS SOSS

See also: NIRISS SOSS APT Template

Target acquisition

A target acquisition (TA) is required when using a subarray with SOSS to ensure the target is placed on the "sweet spot" on the detector. As described in the step-by-step ETC guide, a SNR ≥ 30 is required to ensure the TA will succeed, otherwise the observation fails.

For this science program, we perform the TA on the target, so we kept the acquisition target in the Target ACQ pull-down menu at its default value of SAME TARGET AS OBSERVATION. Using the results from the ETC calculations, we selected SOSSFAINT for Acq Mode, NISRAPID for Acq Readout Pattern, and 19 Acq Groups/Int. For your own tracking purposes, it is recommended you include the ETC workbook and calculation ID number in the Acq ETC Wkbk Calc ID field so the TA SNR calculations can be verified by Instrument Scientists during technical reviews after the proposal is accepted.  In this example, we do not include an ETC workbook ID number in the provided APT file since a unique ID number is generated when an example workbook is added to a user's list of workbooks.

SOSS parameters

We populated the SOSS parameters portion of the SOSS observation template with the exposure parameters determined from the step-by-step ETC guide. We selected SUBSTRIP256 from the Subarray pull-down menu. The only permitted Readout Pattern when using a subarray in the SOSS observing mode is NISRAPID, and is the only option thus available in the APT template. Also from the Step-by-Step ETC guide, we calculated that we needed 8 Groups/Int and 535 Integrations/Exp for this observing program.

The yellow exclamation point indicates a warning for this exposure, which alerts the user that, due to the long exposure (> 10,000 s), a high gain antenna move may be performed during the exposure which can induce jitter that affects the science observation. This is an informational warning, and no action is required.

Since we are not taking an optional exposure with the F277W filter that is sometimes used to model contamination in the overlap between the 1st and 2nd orders, we do not click the box next to Include Short First Exposure and F277W exposure.

Define special requirements

See also: APT Special Requirements

To observe the transit of the exoplanet, phase constraints need to be applied to the proposal, which are specified in the Special Requirements tab of the observation template. Two special requirements were already added by APT: Time Series Observation, which signals the pipeline how to process the data and causes APT to give a warning rather than an error about the exposure duration exceeding 10,000 s, and No Parallel Attachments, which prohibits a parallel observation from being scheduled simultaneously with this program.

In the Special Requirements dialog, we clicked Add to specify the phase special requirement for this observation. The phase range of the transit needs to be specified, where APT accepts values from -1 to 1. By convention, the transit occurs at phase = 0.0. The phase is specified relative to the period of WASP-39 (PWASP39), which is 4.055259 days.

To compute the phase-constraints, we can use the ExoCTK Phase Constraint tool. By querying the properties of WASP-39, we obtain that the phase-range to target the Primary Transit of WASP-39b is from 0.9532171270277271 to 0.96349185095206. According to the results, the transit center is at 2456401.39763 — which we enter as the Zero phase (HJD) and the period of the orbit is 4.055259 days, which we entered as Period in APT.

Run Visit Planner

See also: APT Visit Planner

The APT Visit Planner tool checks the schedulability of an observation and whether guide stars can be found to support the observation. To check the schedulability of this observation as specified, we made sure the observation was selected in the tree editor and clicked on the Visit Planner icon in the top tool bar. We then selected Update Display in the resulting active GUI window. After a few moments, the Visit Planner returned with a confirmation that the observation is schedulable (green check on the selected observation).

Because JWST has time-variable observational constraints—related to the position of the sun relative to the observatory's orbiteach target's RA and Dec has a specific set of ranges of days that targets can be observed.  We can "zoom in" on one of those ranges: using the zoom slider bar above the figure and manually adjusting the grey box to the right of that slider bar, we can isolate a the leftmost range of observing windows. By zooming in on specific windows, we can see the specific calendar dates when this target can be observed by JWST, given the phase constraint. It is good practice to confirm future dates of an estimated transit opportunity.

Run Smart Accounting

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


SIMBAD Astronomical Database

Latest updates
Originally published