Step-by-Step APT Guide for NIRISS SOSS Time-Series Observations of HAT-P-1

Instructions are provided for filling out the APT observing template for the JWST NIRISS SOSS Time-Series Observations of HAT-P-1 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: 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 HAT-P-1" Example Science Program

A filled out APT file can be accessed via the menu options FileJWST Example Science Proposals → NIRISS 31 NIRISS SOSS Time-Series Observations of HAT-P-1 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 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 HAT-P-1in the Object Name search box of the pop-up window. The result 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 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 HAT-P-1. In the Category drop-down menu, we selected Star. In the Description menu, we selected Exoplanets. We entered 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, we entered 2000.


See also: APT Observations

Selecting Observations in the tree editor, we clicked on the New Observation Folder, and in the Label field, we entered HAT-P-1 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 HAT-P-1 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 3Acq 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 3 Groups/Int and 1198 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.

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 theSpecial 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, 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 0 to 1. By convention, the transit occurs at phase = 0.0. The phase is specified relative to the period of HAT-P-1 (PHATP1), which is 4.4652934 days.

To minimize loss of coverage, we want the observation to start no later than  tstart = 0.75 + T14, where T14 is 2.784 hours. Thus, tstart = 3.534 hours. Our starting phase is then pstart = 1 - (tstart + 1 hour)/PHATP1 and our ending phase is pend = 1-tstart/PHATP1. The phase range for HAT-P-1 is thus from 0.95769221 to 0.96702343.

In the "Phase" window that pops up after adding a phase special requirement in APT, we thus entered  0.95769221 and 0.96702343 in phase range and 4.4652934 as the period. According to the discovery paper, the transit center is 2454363.94656 (HJD), so we entered this value for zero phase.

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