Instructions are provided for filling out the APT observing template for the JWST NIRISS SOSS Time-Series Observations of HAT-P-1 Science Use Case.

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 "NIRISS SOSS Time-Series Observations of HAT-P-1" Science Use Case. A filled out APT file can be downloaded here for reference


Proposal Information

Main article: JWST Astronomers Proposal Tool Overview

After opening APT, select "New JWST Proposal" under the "New Document" pull-down menu. On the Proposal Information page, enter Title, Abstract, and Category of proposal. Keep Cycle number at its default value. Update Scientific Category to Planets and Planet Formation and add the following Science Keywords: Chemical Composition and Extrasolar Planets (see Figure 1).

Figure 1. Generic proposal information filled out for the JWST Observing Template in APT



Main article: APT Targets

Target information is entered on the "Targets" page. When clicking on the "Targets" page, click on the "Fixed Target Resolver" button. In the pop-up window, enter "HAT-P-1" in the "Object Name" search box. The result is returned from querying the SIMBAD database is "BD+37 4734B", which is an alternate name for HAT-P-1. By clicking "Select Object as Target", the target name and coordinates are imported to the APT observation template.  (Figure 2, top).

Select this target in the left-hand page tree to provide additional information in the Targets template. In both the Name in the Proposal and Name for the Archive fields, update the name of the object to the more familiar HAT-P-1. In the Category drop-down menu, select Star. In the Description menu, select Exoplanets. Enter the proper motion of the source in the template. From looking up HAT-P-1 in Simbad, we see that the proper motion in RA is 32.7 mas/year and the proper motion in Dec is -43.2 mas/year. In the Epoch box, enter 2000 (Figure 2, bottom).

Figure 2. Enter target information into APT

Top: Using "Fixed Target Resolver", look up the coordinates of the source by querying the SIMBAD database. The returned object is our target. By clicking "Select Object as Target," the name and coordinates of the targets are transferred into the APT observing template. Bottom: Additional information about the target needs to be added to the Target template: Category, Description, Proper Motion, and Epoch. The name can also be updated from the default name returned from SIMBAD to the more familiar "HAT-P-1."


Main article: APT Observations

On the "Observations" page, click on the "New Observation Folder" button. In the Label field, enter HAT-P-1 NIRISS SOSS (Figure 3, top).

Click "Observation 1" in the left hand page tree to open the observation template to be filled out. In the Instrument pull-down menu, select NIRISS, and then select NIRISS Single-Object Slitless Spectroscopy template in the Template pull-down menu.  In the Target pull-down menu, select HAT-P-1 (Figure 3, bottom).

Figure 3. Select the SOSS observing template

Top: Clicking on the "New Observations" folder will open a summary screen for the first observation. Update the Label field with information to identify this observation, in this case HAT-P-1 NIRISS SOSS. Bottom: Clicking on "Observation 1" in the page tree will open a JWST observing template. Selecting the options as described in the main text (shown here) will bring up an observing template that can be filled out with exposure parameters derived from the ETC Step-by-Step guide (see Figure 4) .

NIRISS SOSS Observation Template

Main article: NIRISS SOSS Template APT Guide
See also: NIRISS APT Target Acquisition

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 use case, we perform the TA on the target, so keep 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, select SOSSFAINT for Acq Mode, NISRAPID for Acq Readout Pattern, and 3 Acq Groups/Int (Figure 4). It is recommended to include the ETC workbook ID number in the Acq ETC Wkbk Calc ID field so the TA SNR calculations can be verified by Instrument Scientists during technical reviews.  

Figure 4. Populate target acquisition parameters in the SOSS observation template


Using the results from the ETC calculation, fill out the target acquisition parameters. Here, we perform TA on the target of the observation to ensure the source is precisely positioned on the detector. Including the ETC workbook ID in the template is highly recommended to ensure the TA specifications input by the user passes a technical review.

SOSS Parameters

Populate the SOSS Parameters portion of the SOSS observation template with the exposure parameters determined from the Step-by-Step ETC guide (Figure 5). Ensure that SUBSTRIP256 is selected in 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.

For Groups/Int, enter 2, and enter 2042 for Integrations/Exp. The ETC Wkbk. Calc ID can also be entered in the template. The yellow exclamation point indicates a warning for this exposure, which alerts the user that the 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.

Figure 5. Populate SOSS parameters in the SOSS observation template


Using the results from the ETC calculation, fill out the SOSS exposure parameters: SUBSTRIP256 subarray, 2 groups per integration, and 2042 integrations per exposure. The only permitted Readout Pattern is NISRAPID since a subarray is being used, so APT does not offer an option other than NISRAPID for the readout pattern. The ETC workbook ID can also be entered.

Special requirements

Main article: 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. 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. 

It is recommended to add 1 hour of "timing window" to the observation, which will allow the observatory scheduling enough leeway to place this transit observation in the normal event driven scheduling. Timing windows of 1 hour or more of margin plus settling time will avoid an extra timing overhead on tight observation execution windows (< 1 hr).  A factor of 2 T14 + 1.5 hr allows for both detector settling and some margin in case the observation execution initiation window is defined to be large or if the primary transit occurs at a slightly different time than predicted. Click "Add" to specify the phase special requirement for this observation (Figure 6, top). 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 of HAT-P-1, which is 4.4652934 days.

To minimize loss of coverage, we want the observation to start no later than 1.5 × T14 + 1.5 hours, where T14 is the exoplanet transit duration of 2.784 hours. The phase, in units of the period of HAT-P-1 in days, is thus 1 - (1.5 × T14 + 1.5 [hrs]) / PHATP1 = 1 - (1.5 × 2.784/(24 × 4.4652934) + 90/(60 × 24 × 4.4652934)) = 0.94704.

In the "Phase" window that pops up after adding a phase special requirement in APT, enter 0.94704 and 0.95637 in phase range and 4.4652934 as the period. According to the discovery paper, the transit center is 2454363.94656 (HJD), so enter this value for zero phase (Figure 6, bottom). Click "OK" to add the phase special requirements to the program.

Figure 6. Specify phase special requirement

Top: To specify a phase window in which HAT-P-1 can be observed, enter the "Special Requirements" template, click "Add", open the "Timing" menu, and select "Phase." Bottom: In the "Phase" window that pops up, enter the phase specifications as derived in the main text.

Data Volume

Main article: JWST Data Rate and Data Volume Limits

The data volume limit for JWST observations is 28.6 GBytes per 12 hour interval, to prevent solid state recorder from running out of space before data are downlinked to Earth. Since NIRISS has only one Hawaii 2RG detector, it is rare for this data volume limit to be reached. Nevertheless, it is prudent to check the data volume for this observation.

In the left-hand page tree, click the triangle next to "Observation 1" to open the Visit pane (Figure 7). Here we see that the data volume for the observation is 4,282 MB, and thus does not violate the data volume limit.

Figure 7. Visit pane for NIRISS SOSS observation of HAT-P-1


The visit pane shows that for the NIRISS SOSS observation of HAT-P-1, the data volume will be 4,282 MB, which is under the data volume limit of 28.6 GBytes per 12 hour interval.


Main article: 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, click on the "Visit Planner" icon in the top tool bar and click "Update Display" (Figure 8). 

Figure 8. Run Visit Planner to check target schedulability

Because JWST has very special 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 "patches" of days that targets can be observed (Figure 9, top).  We can "zoom in" on one of those patches: 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 "patch" of observing windows (Figure 9, bottom). 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.

Figure 9. Inspect results from visit planner


Top: The windows where the the observation of HAT-P-1 can be scheduled over a 19 month period, given the specified phase constraint, is returned from the Visit Planner. Bottom: Using the zoom slide-bar and gray box to the right of the zoom slide-bar to isolate the left-most visibility "patch," the specific UT window can be found.


JWST technical documents

Block has been set to pdf-hide. Contact Shireen if you enter references

Last updated

Published February 06, 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