JWST ETC to APT Interface Support Information

There are a number of subtle differences at the interface of the JWST Exposure Time Calculator and the Astronomer's Proposal Tool about which users should be aware. 

On this page

See also: JWST Exposure Time Calculator OverviewJWST Astronomers Proposal Tool Overview
See also: JWST APT-ETC Connectivity

The JWST Exposure Time Calculator (ETC) and Astronomer's Proposal Tool (APT) are two of the primary tools that proposers must use in constructing viable JWST proposals. For JWST Cycle 1, the tools will be used separately, with relevant information transferred from ETC to the appropriate APT templates by the user. Significant effort has been expended in development of these tools to coordinate the interface, but there are a number of subtle differences between the tools  that remain.  This article provides a vehicle for highlighting these interface issues while providing links to more information where it is needed.

The JWST Astronomer's Proposal Tool and Exposure Time Calculator are under development and subject to future updates. Current documentation is best effort based on ETC v1.5 and APT v27.3.

Tracking ETC assumptions in APT

In the APT observation templates, the exposure specification sections for both target acquisitions (if present), and science exposures contain a box where you can enter, for future reference, the ETC workbook and specific calculation ID that was used to determine the entered exposure specifications. The use of this box on your science observations is entirely optional, but entering this information may help you to track the assumptions used in specifying your APT observations by tying them back to your ETC workbook.  Because the use of the ETC for specifying target acquisition information is particularly important to the success of your observations, APT places a warning on this field if no entry is provided.  For accepted proposals, technical reviewers may contact you for more details about your assumptions.

Details on the use of these boxes and handy examples are provided in JWST APT-ETC Connectivity.

General interface issues

APT warnings and errors are not always reflected in ETC: The ETC needs to be able to support engineering users as well as astronomers. Hence, it was developed to allow a user to choose values for various parameters that are not available by default, but can be accessed for engineering purposes. APT contains numerous warnings and errors that alert users when they are attempting to select options that are not available by default. Unfortunately, those errors and warnings are not always reflected directly in the ETC. That is, the ETC may let you select options that will be considered invalid when the information is transferred to the appropriate APT template.The number of groups and the number of integrations vary by instrument, and users are advised to consult the documentation on JWST Astronomer's Proposal Tool (APT) and JWST instruments for more information on the allowed range of values for these detector parameters. The ETC does not support NGROUPS=1 and will alert the user with red color if Groups per integration is set to 1 and will prevent the ETC calculation to be completed. The detector parameters available for the different instruments and modes are set to be consistent with that offered by the APT. However there are cases in which ETC allows the number of groups, the number of integrations and the number of exposures to exceed the limits imposed by APT, so it is important for users to check with APT to ensure what the limits are while planning observations.The instrument sections below highlight some of the more obvious and significant examples that may occur for normal users.

ETC-APT nomenclature differences: A significant effort has been made to standardize the use of keywords and parameter names between the two tools. However, there are many details involved, with some depending on context, that have made it impossible to be entirely consistent. While further improvements are being made, users should just be aware that there may be some minor differences, usually understandable with the help of the documentation below and the links provided.

Handling of dithered observations:  The templates of nearly all modes in APT allow the user to select various dither patterns, and sub-dithers in some cases, that are not handled explicitly in ETC.  To first order, if one assumes the total number of exposures to be made in the full dither pattern in APT and uses that number of exposures in the ETC, you are approximating the situation fairly well.  But there can be exceptions to this general rule that need to be considered.  These cases are also called out in the sections below, as appropriate.

ETC improvements

 NOTE: Beginning in ETC version 1.2.2, released Mar. 14, 2018, the ETC now handles improved S/N from multiple exposures as an approximation to dithering. Users may see some increase in S/N in their calculations when compared with earlier versions of ETC.

NIRCam interface issues 

Nomenclature inconsistencies:

  • In APT, there are separate NIRCam imaging and a NIRCam Time Series imaging templates, which each include both the short-wavelength (SW) and long-wavelength (LW) detector setups. In ETC, however, these are split in two modes: SW imaging (SW Time Series) and LW Imaging (LW Time Series).

Subarray inconsistencies between APT and ETC: The imaging templates in the ETC include subarrays meant only for use in grism mode. These will be labeled as unavailable for imaging in future ETC versions. See the NIRCam Detector Subarrays article for more information. As of ETC 1.2, a warning message is generated that the grism subarrays may not be supported in NIRCAM imaging.

Neutral density squares: In ETC, neutral density (ND) squares are listed as options for coronagraphy. ND squares should only be used for target acquisition. This is specified in APT when choosing Acq Target Brightness = BRIGHT.  As of ETC 1.2, a warning message is generated that this is an unsupported option and ND squares are for TA only.

Readout output channels: 

  • In the APT grism time-series template, users can choose to use either 1 or 4 output channels when reading out the detector, with more channels resulting in shorter exposure times. In ETC, users will be able to choose between two options for a given subarray, e.g., "SUBGRISM64" or "SUBGRISM64 (noutputs=1)". Choosing the option that does not specify the number of outputs results in noutputs = 4, which is the default.

Uneven spatial coverage with primary NIRCam dithers in the ETC: In general, dithers are approximated in the ETC by increasing the number of exposures in the Detector Setup tab. Since most dither options only move the position by a small number of pixels, putting the number of total dither steps in the Exposures box is sufficient for estimating the total S/N over the majority of the spatial coverage in most cases. 

However, NIRCam primary dither patterns are designed to cover detector and module gaps, and therefore take large steps (≈1′ for some patterns). These steps result in uneven depth across the mapped coverage. Users should carefully consider what to enter as the number of exposures in the ETC based on the coverage maps of the implemented dither pattern.  In the case of the FULL patterns, the average frame depth is ≈70% of the number of dithers such that including 3 dithers results in a depth of 2 frames across most of the spatial coverage.  In this example, users should specify Exposures = 2 in the ETC to avoid over-estimating the S/N.  In the case of the INTRAMODULE and INTRASCA patterns, the depth is decreased in the center of the SW coverage.

Note also the message above about the actual S/N being higher than the ETC estimates when flat fielding is accounted for.

MIRI interface issues

Potential confusion regarding exposures in ETC:  Since MIRI can have multiple exposures per dither, one must use two fields in APT (exposures/dither and Total Number of Dithers) to get the right number of exposures to use in the ETC calculation.

Backgrounds in ETC:  In the ETC, the "IFU Nod In Scene" strategy is equivalent to an APT dither, while the "IFU Nod Off Scene" strategy indicates a separate background pointing. The latter would actually be two separate observations in APT.

Observing modes vs. subarrays: The MIRI Low Resolution Spectroscopy (LRS) observing mode allows users the option of using a Slit or observing in Slitless mode. In APT, the user selects "MIRI Low Resolution Spectroscopy" from the "Template" drop-down menu and is given the option under "LRS Parameters" for a "Subarray" of either "FULL" or "SLITLESSPRISM." The "FULL" subarray is for LRS Slit observations. In the ETC, there are two separate options in the MIRI drop-down menu for "Low Resolution Spectroscopy (LRS) Slit" and "Low Resolution Spectroscopy (LRS) Slitless" calculations.

Readout patterns:  The READOUT PATTERN options in APT and ETC may be somewhat different in the two tools. For the Low Resolution Spectroscopy (LRS) Slitless and Coronagraphic Imaing modes, the ETC allows the user to choose FAST or SLOW readout, while APT only allows FAST. This is to accommodate engineering users of ETC, as described in the general section above. Refer to APT and the relevant template, which shows the correct readout patterns allowed for Cycle 1 General Observers.

NIRSpec interface issues

As with other instruments, one needs to understand the total number of exposures (including dither steps) to use in ETC to estimate the expected S/N that will be achieved.

NIRSpec available science modes in the ETC:  The NIRSpec instrument observing mode options within the ETC include: Multi-Object Spectroscopy (MOS), IFU spectroscopy, and Fixed Slit and Bright Object Time Series (FS/BOTS) spectroscopy.  There is no mode that is specified only for NIRSpec Bright Object Time Series (BOTS) observing.  Sensitivity calculations for the BOTS observing mode are carried out using the FS/BOTS spectroscopy option in the ETC, using the S1600A1 slit, which is the 1."6 x 1."6 square aperture that is designed for the time series observations in BOTS.  All of the available science subarrays for BOTS mode observations are accessible and labeled as such in the ETC detector Subarray pull-down menu in the Detector Setup tab.

NIRSpec dithers:  In general, for all modes, dithers are mimicked in ETC by the number of exposures in the Detector Setup tab.  For example, in the NIRSpec IFU Nod in Scene mode, if you wish to use a 4 point observing dither pattern, the number of integrations per exposures should be 2. Each integration accounts for 2 dither positions in the ETC.

NIRSpec imaging calculations:  There is presently no option to calculate signal-to-noise in user-selected exposure times in NIRSpec imaging data acquired with the mirror in the grating wheel assembly.   NIRSpec imaging observations that might require different exposure times include "Verify_Only" pointing verification exposures, as well as NIRSpec MSA "Confirmation Images" that acquire images of science sources through configured open MOS spectral slits.  The NIRSpec "Target Acquisition" (TA) ETC calculation mode delivers signal-to-noise in the fixed exposure time set by the detector readout pattern NRS or NRSRAPID (traditional readout) used for the ngroups=3 image acquired for TA (limits are set by 3 groups for saturation limits, and 1 group for faint sensitivity).  Once imaging calculations are properly incorporated into the ETC in the future, exposure times for sensitivity in these NIRSpec imaging observations will need to be updated to correspond to signal-to-noise requirements on the observations.

NIRSpec IFU 'Nod in Scene' in the ETC:   The default background subtraction in the Strategy tab in the NIRSpec IFU ETC is for two-point nodding in-scene.   This option uses an offset pattern of x=0."5, y=0.5", which is not the same as the 2-point nod positions that are available as observing options in the APT.  However, the values are editable by the user to agree with the 2-point nod positions. Nodding in-scene should only be used for very compact (<0."3) science sources.  For sensitivity calculations on all spatially extended science sources, the 'Nod Off Scene' option in the Strategy tab is encouraged for use.

NIRSpec IRS2 detector readout patterns and subarrays:  The noise reducing IRS2 detector readout patterns (NRSIRS2RAPID and NRSIRS2) cannot be used with subarray readouts of the detector.  APT will give an error if these IRS2 readouts are selected with subarray detector patterns in FS mode.  As of ETC 1.2, the detector setup does not allow to choose IRS2 detector readout patterns with subarray readouts.  This is only an issue for the FS science mode of NIRSpec because subarrays are not permitted in MOS or IFU science modes, and the BOTS mode cannot use IRS2 readout patterns.

NIRSpec BOTS integrations: A single integration should be specified to compute the S/N. Otherwise, the ETC will calculate the S/N over all integrations, averaging as it does for a FS calculation. Multiple integrations should not be averaged for S/N, as the scene is changing during a time series observation.

NIRISS interface issues

Detector readout pattern inconsistencies: For the single object slitless spectroscopy (SOSS) mode, only the NISRAPID readout pattern is supported when using the SUBSTRIP96 and SUBSTRIP256 subarrays. ETC allows the use of the NIS readout pattern for SOSS subarrays when performing calculations, but will issue a warning if the NIS readout pattern is selected when using a subarray. The NIS option is not allowed in the SOSS APT template when using a subarray. Both NIS and NISRAPID readout patterns are supported for full frame readout.

Direct imaging in  wide field slitless spectroscopy (WFSS) and aperture masking interferometry (AMI) modes: The APT template for WFSS includes a required field for direct imaging, before and after a set of dithered grism observations. The APT template for AMI includes an optional field for direct imaging. ETC calculations for these modes do not include a direct imaging component. To run calculations for direct imaging, use the NIRISS imaging mode in ETC. If the direct imaging for AMI requires use of a subarray it is okay to use the subarrays marked as engineering mode only in ETC.

Exposure times in APT and ETC include reset frames: For science cases where the aim is to detect a total number of photons (e.g., to achieve a specific contrast ratio when observing with AMI), recall that the total exposure time is (Number of groups + 1) x Number of integrations x frame time, while the total photon collecting time is Number of groups x Number of integrations x frame time. The +1 factor in the total exposure time reflects the frame reset time, when no photons are detected.



Latest updates

  • Updated NIRISS section to be consistent with ETC v.1.3 and APT v. 27.9
    Updated for ETC v1.3

    Added information about ETC and APT interface between exposure parameters. Updated the first paragraph under NIRISS interface issues.

    Updated the third paragraph under NIRISS interface issues.

    Article updated for release of ETC patch release 1.2.2.

    Article has been updated for consistency with capabilities of ETC 1.2 and APT 25.4.2.