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 2 of the primary tools that proposers must use in constructing viable JWST proposals. The tools must 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 continuous development and subject to future updates. Current documentation has been updated and is current as of ETC 1.6.1 and APT 2021.1.

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 the 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 allowed number of groups and the number of integrations can 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 error text if Groups per integration is set to 1 and will prevent the ETC calculation from being run. 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 the 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 2 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 the 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.

Support for NGROUPS=1For near-infrared detectors, APT allows 1 group per integration, but the ETC does not because the magnitude of systematic errors will not be known until measurements are made on-orbit.

NIRCam interface issues 

Nomenclature inconsistencies: In APT, there are separate NIRCam imaging and 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 2 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 2 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 the ETC:  Since MIRI can have multiple exposures per dither, one must use 2 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 the 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 2 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 the 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 2 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 the APT and ETC may be somewhat different in the 2 tools. For the low resolution spectroscopy (LRS) slitless and coronagraphic imaging modes, the ETC allows the user to choose FASTR1 or SLOWR1 readout, while APT only allows FASTR1. 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 General Observers.

MIRI MRS: Each observation specification in the APT corresponds to 4 separate calculations in the ETC (Channels 1-4 for the specified Wavelength Range). To cover the full MRS wavelength range, 3 separate observations must be specified in the APT, one for each Wavelength Range: SHORT(A), MEDIUM(B), and LONG(C). This corresponds to 12 separate calculations in the ETC. Additionally, simultaneous imaging calculations must be specified separately in the ETC using a MIRI Imaging calculation.

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. Dithers are handled as individual exposures in the ETC.

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 (FS) and bright object time series (BOTS) spectroscopy.  As of ETC 1.6, the fixed slit/BOTS mode has been separated into fixed slit mode and bright object time-series mode.

NIRSpec nods:  For each of the NIRSpec modes, the SNR for the nodding strategies offered in APT can be calculated from the SNR computed by the ETC for a single non-dithered exposure, by applying various correction factors.  However, the ETC allows only nodded strategies. The SNR estimated by the ETC is accurate without correction for the 2-point nod strategies presented there, but the SNR for a 4-point dither must be computed from that of the two-point SNR, with a correction factor. Refer to the NIRSpec Background Recommended Strategies article for details.

NIRSpec IFU "Nod in Scene" positions in the ETC: The default background subtraction in the Strategy tab in the NIRSpec IFU ETC is for 2-point nodding in-scene. This option has default offsets 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 can be edited by the user to agree with the APT 2-point nod positions. (See the strategy article.) 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 recommended. For Nod Off Scene the exposure time is half that of the Nod In Scene case, since background observations are not included in the Nod Off Scene scenario. When filling in the APT proposal form for Nod Off Scene, separate observations of the same exposure duration will need to be included to account for background observations.

NIRSpec imaging calculations: As of ETC 1.5, there is the 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 include "Verify_Only" pointing verification images, and NIRSpec MOS "Confirmation Images". The former is modeled in the ETC using the MOS Verification Imaging and IFU Verification Imaging options in the NIRSpec pull-down menu. MOS Confirmation images are specified in the ETC using that selection in the NIRSpec pulldown menu. The NIRSpec "Target Acquisition" (TA) ETC calculation mode delivers signal-to-noise in the fixed exposure time set by the detector readout pattern NRSRAPID1, NRSRAPIDD2, or NRSRAPIDD6 (traditional readout) used for the Groups=3 image acquired for TA.  As of ETC 1.6, the shutter grid size for MOS_VER and the MSATA has been increased to 11 x 7 from the previous value of 5 x 5, whereas APT assumes a 13x7 grid size.

NIRSpec IRS2 detector readout patterns and subarraysThe noise reducing IRS2 detector readout patterns (NRSIRS2 and NRSIRS2RAPID) 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. (IRS2 readout patterns must be used with FULL readout of the array.)  Likewise, the ETC will not allow the IRS2 readout patterns when a subarray is specifiedIn the ETC, this happens only for the FS and BOTS calculations since the subarrays are not available for use in the IFU and MOS science modes.

NIRSpec BOTS integrations: For BOTS science mode in the ETC, 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. The number of groups per integration should be chosen to suit both the desired S/N and the exposure cadence.

* Bold italics style indicates words that are also parameters or buttons in software tools (like the APT and ETC). Similarly, a bold style represents menu items and panels.

NIRISS interface issues

SOSS GR700XD/F277W combination: As of APT v. 2020.1, users have the option to include an exposure using the F277W filter crossed with the GR700XD grism. As of ETC v. 1.5.1, the ETC does not yet offer the GR700XD/F277W combination. The throughput of the F277W filter is about 90% that of the CLEAR filter, so users can estimate the SNR for the GR700XD/F277W exposure by multiplying the SNR of a GR700XD/CLEAR calculation in the ETC by a factor sqrt(0.9) ~ 0.95 for wavelengths from about 2.4 microns to the long wavelength limit of SOSS order 1.

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 x Number of frames/group + 1) x Number of integrations x frame time, while the total photon collecting time is Number of groups x Number of integrations x Number of frames/group x frame time. The +1 factor in the total exposure time reflects the frame reset time, when the pixel is not read out.

Latest updates
    Updated for ETC 1.6.1

  • Updated for ETC 1.6

  • Updates to NIRSpec section for compatibility with new tool releases.

    Updated for Cycle 1 APT 2020.1.1 and ETC 1.5.1.

    Updated NIRISS section to be consistent with ETC v.1.3 and APT v. 27.0

Originally published