Step-by-Step APT Guide for NIRSpec BOTS Observations of WASP-79b

Step-by-step APT observation definition instructions for the NIRSpec BOTS Observations of WASP-79b Example Science Program are presented and discussed.

Dated material

This example was created pre-launch, and the APT has been updated since its creation. You may see differences in the appearance of the APT GUI and/or the warnings and errors in APT from what is shown herein.

Please refer to JWST Example Science Programs for more information.

On this page

See also: NIRSpec Bright Object Time-Series SpectroscopyNIRSpec Bright Object Time-Series APT Template, 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 "NIRSpec BOTS Observations of WASP-79b" example science program

A filled out APT file can be accessed via the menu options File → JWST Example Science Proposals → NIRCam → 32 NIRSpec BOTS Observations of WASP-79b in APT. The APT file was created with version 27.3. 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 pane, 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 New Fixed Target option and entered WASP-79b in the Name in Proposal and Name for the Archive boxes. We inputted the coordinates and proper motion from the Gaia archive: RA: 04 25 29.0167 and Dec: -30 36 01.5669 and proper motion RA: -0.36925175163647633 and proper motion Dec: 2.622874920934259 mas/yr. The Epoch is 2000. In the Category drop-down menu, we selected Exoplanets and F stars.

We created another target to input the information for the offset source to be used for target acquisition. Using New Fixed Targetwe entered 2MASXJ04253078-3035541 in the Name in Proposal and Name for the Archive boxes. We inputted the coordinates and proper motion from the Gaia archive: RA: 04 25 30.7764 and Dec: -30 35 53.8902. The Epoch is 2000. In the Category drop-down menu, we selected Galaxy. In the Description menu, we selected Compact galaxies.


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-79b NIRSpec BOTS.

We next clicked "Observation 1" in the Tree editor to open the observation template in the Active GUI window. We entered "WASP-79b - G395H" in the Label field. In the Instrument pull-down menu, we selected NIRSpec, and then selected the NIRSpec Bright Object Time Series template in the Template pull-down menu. Note that only parameters of interest to NIRSpec BOTS are shown in the GUI. In the Target pull-down menu, we selected WASP-79B, which we defined above.

Complete APT observation template for NIRSpec BOTS

See also: NIRSpec Bright Object Time-Series APT Template

Target acquisition parameters

Fill out the target acquisition (TA) parameters following the findings on signal-to-noise from the  ETC calculation: TA option is “WATA” (wide aperture TA). The target for TA is 2MASXJ04253078-3035541, which we defined above.  We thus select 2MASXJ04253078-3035541 in the Acq Target pull-down menu. We select the SUB32 subarray and the F110W filter, and the NRSRAPID readout, consistent with parameters found in the ETC TA sensitivity calculation for this offset star.  In NRSRAPID, the exposure time will be 0.08 seconds for the TA. 

Science parameters

We populated the Science Parameters portion of the observation template with the exposure parameters determined from the Step-by-Step ETC Guide. We chose the SUB2048 Subarray, G395H/F290LP Grating/Filter option,  and 1 Exposures/Dith. We chose the NRSRAPID readout pattern with 19 Groups/Int and 950 Integrations/Exp to cover the transit window plus the padding time before and after the transit, which gives an exposure time of ~17160 seconds (4.767 hrs).

A warning is added to the Exposure time definition. Hovering the computer mouse over the warning icon shows: “Warning: Exposure duration exceeds the limit of 10000 seconds. Above this limit it is possible that a High Gain Antenna move may move during the exposure”.

Observations in the NIRSpec BOTS template are allowed to have individual exposure times beyond the 10000 second limit, thus exposing right through the repoints of the High Gain Antenna (HGA). When the HGA moves to repoint for ground communication contact, the guide star drops out of fine lock. This results in movement of the guide star and hence the science source within the NIRSpec aperture. After the HGA repoints, the FGS re-establishes lock and the guide star (and science source) are repositioned to within less than 5 milli-arcsec of their previous location. 

The observation described here requests an exposure time of ~17160 seconds, and it is likely that the HGA will repoint during the course of the exposure time. The HGA repoints last approximately 60 seconds, and the source position and thus the position of the spectra will slightly change during the HGA movement, resulting in short excursions in the flux in the science spectra. The integrations affected by HGA repoints can be removed from the measured time series during data processing and analysis.

Define special requirements

Timing special requirement

The timing special requirements are needed to define when the transit observation of WASP-79b should start. The phase range of the transit needs to be specified, where APT accepts values from 0 to 1. By convention, the transit occurs at phase = 0.0. The phase is specified relative to the period which for WASP-79b is 3.66238 days, or 87.897118 hours (PW79). 

To cover the transit window, we define a start time of tstart = T14 + 0.75 hours (where T14 is the transit duration of 1.0152 hours1) to be consistent with Tdwell which we defined for the total exposure time. Thus, tstart = 1.7652 hours. Our starting phase is then pstart = 1 - (tstart + 1 hour)/PW79 and our ending phase is pend =  1 - tstart/PW79. The phase range for WASP-79b is thus 0.96854 and 0.9799.

To add these values, we clicked "Add" in the "Special Requirements" tab and selecting Timing → Phase. We entered 0.96854 and 0.9799 into the Phase range, 3.66238 for the Period (with Days as the units), and set Zero phase (HJD) to 2455545.2348, the center time of the primary transit. (Note that any transit following the initial one defined by the phase special requirement could also be selected for the execution window.) 

1: Note this value for T14 might be incorrect. This does not change the logic (but would change the final numbers) of this example program. See this program's landing page for details.

Time-series observation special requirement

The NIRSpec BOTS mode observation will automatically have a Time Series Observation Special Requirement added. This shows up as an implicit special requirement for all NIRSpec BOTS mode observations in APT. The purpose of this special requirement is to ensure that the NIRSpec BOTS data gets processed through a particular pipeline calibration workflow specific for time series exposures. Users do not need to add this special requirement, but it's useful to take note that it is automatically set.

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.

Latest updates
    Added warning about the transit duration of WASP-79b.
Originally published