Step-by-Step APT Guide for NIRCam Time-Series Imaging of HAT-P-18 b

Instructions are provided for filling out the APT observing template for the JWST NIRCam Time-Series Imaging of HAT-P-18 b 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 Time-Series ImagingNIRCam Time-Series APT Template, 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 "NIRCam Time-Series Imaging of HAT-P-18 b" Example Science Program.

A filled out APT file can be accessed via the menu options File → JWST Example Science Proposals → NIRCam → 29 NIRCam Time-Series Imaging of HAT-P-18 b 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.

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-18 which is the host star for the planet HAT-P-18 b 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. 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 Category drop-down menu, we selected Star. In the Description menu, we selected Exoplanets. The Proper Motion menu is filled automatically with the following information: proper motion in RA = -0.0011 sec of time/year, proper motion in Dec = -0.0366 arcsec/year, and the Epoch box, with 2015.5


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-18b.

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 NIRCam, and then selected the NIRCam Time Series template in the Template pull-down menu.  Note that only parameters of interest to NIRCam time-series are shown in the GUI.  In the Target pull-down menu, we selected HAT-P-18b which we defined above.

Complete APT observation template for NIRCam time series

See also: NIRCam Time-Series APT Template, NIRCam Time-Series Imaging 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 (with a centroid accuracy of < 0.15 pixel), otherwise the observation fails. We chose exposure parameters for a SNR ≥ 100 so that the centroid accuracy will be ≤ 0.05 pixel.

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 9 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.

Time-series parameters

We populated the tim-series parameters portion of the Time Series template with the exposure parameters determined from the Step-by-Step ETC guide. We note that the only Module option permitted for NIRCam imaging time series observation is module B, and since we take only 1 exposure per observation, we leave Exposures/Dith at the default value of 1. 

We selected SUB64P from the Subarray pull-down menu. From the Short Wavelength pull-down menu, we selected CLEAR for the Pupil and F210M for the Filter, whereas from the Long Wavelength pull-down menu, we selected CLEAR for the Pupil and F444W for the Filter

Then, for the Exposure Time we selected RAPID in the Readout Pattern pull-down menu, we entered 10 for Groups/Int and 60000 for Integration/Exp (from the Step-by-Step ETC guide). 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, 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.

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.43854 to 0.43927,
  • Period = 5.508023 days
  • Zero-Phase = 2454715.02174 HJD.

These parameters are obtained from the literature. For HAT-P-18 b, Hartman et al. (2011), predict that the secondary eclipse will come 2.63 days after transit, at an equivalent 0 eccentricity PHASE of 0.4772, given its 5.508 days period. We will center the schedule of the exposure to start 5.07 hours before the predicted secondary eclipse time, allowing for 1 hour of detector settling and one transit time before the predicted time of the secondary eclipse start (see JWST Time-Series Observations Noise Sources). This corresponds to PHASE 0.4385 and will allow us to catch the secondary eclipse if it occurs within ±1 transit time (2.71 hours) of the predicted value. We thus set the special requirement to start the exposure at PHASE 0.4385 to 0.4392 with period 5.508023 days and zero-phase 2454715.02174 HJD, just outside of the minimum allowed 5 minute tolerance.

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

Hartman, J. D., Bakos, G. A., Sato B., et al. 2011, ApJ, 726, 1 (arXiv)
HAT-P-18b and HAT-P-19b: Two Low-Density Saturn-Mass Planets Transiting Metal-Rich K Stars

Latest updates

Originally published