Step-by-Step APT Guide for NIRCam Grism Time-Series of GJ 436b

Instructions are provided for filling out the APT observing template for the JWST  NIRCam Grism Time-Series Observations of GJ 436b Example Science Program.

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:  NIRCam Grism Time-SeriesNIRCam Grism 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 "NIRCam Grism Time-Series Observations of GJ 436b" Example Science Program.

A filled out APT file can be accessed via the menu options File → JWST Example Science Proposals → NIRCam → 30 NIRCam Grism Time-Series Observations of GJ 436b 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

See also: JWST Astronomers Proposal Tool Overview

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

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 GJ436 which is the host star for the planet GJ436in the Object Name search box of the pop-up window. An entry for the selected object appears in the pop-up window (note that the different name, ROSS 905, identifies the same object). By clicking Select Object as Target, the target name and coordinates were imported to the APT observation template. Before importing the selected target, a pop-up informs us that proper motions were detected for this object and imported in 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 the Name in the Proposal and Name in the Archive menu, we changed the name of the object from ROSS 905 to GJ-436. In the In the Category drop-down menu, we selected Star. In the Description menu, we selected Exoplanets, M dwarfs, M stars. The J200 Coordinates are filled automatically with the values RA: 11 42 12.1287 and Dec: +26 42 11.04. In the Uncertainty field we added 0.01 arcsec both for RA and Dec. The Proper Motion menu is filled automatically with the following information: proper motion in RA = 0.06679 sec of time/year, proper motion in Dec = -0.81403 arcsec/year, and the Epoch box, with 2015.5. In the Annual Parallax field we add 0.1025015 (arcsec).


See also: APT Observations

Selecting Observations in the tree editor, we clicked on the New Observation Folder, and in the Label field, we entered GJ-436b.

We next clicked Observation 1 in the tree editor to open the observation template in the active GUI window. Since we will create more than one observation in this proposal (i.e., one for the filter F332W2 and one for the filter F444W) we add in the Label field F332W2 Sec Eclipse, to avoid confusion.

In the Instrument pull-down menu, we selected NIRCam, and then selected the NIRCam Grism Time Series template in the Template pull-down menu.  Note that only parameters of interest to NIRCam Grism Time-Series are shown in the GUI.  In the Target pull-down menu, we selected GJ-436 which we defined above.

Complete APT Observation Template for NIRCam Grism Time-Series

See also: NIRCam Grism Time-Series APT Template, NIRCam Grism Time-Series Target Acquisition

Target acquisition

A target acquisition (TA) is required for all the NIRCam time-series observations 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 RAPID for Acq Readout Pattern, and 3 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.

Grism time-series parameters

We selected SUBGRISM64 from the Subarray pull-down menu and from the No. of Output Channels pull-down menu. Exposure/dith is left to the default value of 1. From the Short Pupil+Filter pull-down menu, we select CLEAR+WLP4, whereas for the long wavelength filter, we selected GRISMR+F322W2 from the Long Pupil+Filter pull-down menu. This observation is labeled F322W2 Sec Eclipse (Obs 1) in the accompanying APT file. From the Step-by-Step ETC guide, we found that we need Groups/Int and 8381 Integrations/Exp (F332W2 Sec Eclipse (Obs 1)). 

We propagated these parameters to the F444W Sec Eclipse (Obs 2) observation by right-clicking in the Tree editor on  F322W2 Sec Eclipse (Obs 1) and selecting Duplicate. This created a second observation identical to the previous one. 

In this observation folder, we changed the following parameters:

  • Label field: F444W Sec Eclipse
  • Long Pupil+Filterpull-down menu: GRISMR+F444W
  • Groups/Int field: 10 (derived in the Step-by-Step ETC Guide)
  • Integrations/Exp field: 4577 (also derived in the Step-by-Step ETC Guide)

The yellow exclamation point indicates a warning for this exposure, which alerts the user that, due to the long exposure (> 10,000 seconds), 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.

When clicking on the arrow, we expanded the "F322W2 Sec Eclipse (Obs 1)" observation in the Tree editor, we note that there is a second warning at the "visit" level. This warning alerts the user that the Data Volume for this visit exceeds half the maximum allowed of 58000.0 MB. This is an informational warning that notifies, during planning and schedulability, that observations must be executed after a downlink in order to not fill the Solid State Recorder (see also JWST Data Volume and Data Excess). No action is required. 

Define Special Requirements

See also: APT Special Requirements

To observe the transit of 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,000s, and No Parallel, which prohibits a parallel observation from being scheduled simultaneously with this program.

We also specify here the phase constraints for the transit observation, to ensure the observation is scheduled at the correct time. For this we use the Phase requirement, listed under Timing. In the phase constraints box that appears, we enter:

  • Phase = 0.53496 to 0.55073,
  • Period = 2.64388312 days
  • Zero-Phase = 2454510.80162 HJD.

GJ 436has only 1 nearby bright star (ΔK < 7 mag), but will not contaminate the F322W2 grism spectrum if we specify an Aperture PA Range constrain. To do so, we use the PA Range requirements, listed under Position Angle. In the pop-up window we enter the following values 177 and 151 Degrees (F322W2 Sec Eclipse (Obs 1)). 

For the F444W grism observation (F444W Sec Eclipse (Obs 2)),  we modify the Aperture PA Range constrain in the Special Requirements tab to prevent spectral contamination from nearby stars:

  • Aperture PA Range 177 to 331 Degrees
  • Aperture PA Range 357 to 151 Degrees

Each of the above observations should be duplicated twice to create a total of 3 secondary eclipse observations in each filter to achieve the desired SNR on the final spectrum. 

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 orbit – each 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

Notable updates
Originally published