JWST ETC to APT Interface Support Information

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

On this page

See also: JWST Exposure Time Calculator OverviewJWST Astronomers Proposal Tool Overview, 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 3.0 and APT 2023.3.4.

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 the JWST Astronomer's Proposal Tool (APT) and the 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 Groups per integration, Integrations per exposure, and the Total Dithers 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 extremely challenging 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: 

Dithering can affect the number of exposures to assume in the ETC. 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, one should match the value in the Total Dithers box in the ETC to the number of dithers given in APT. By doing so, you are approximating the noise calculation fairly well. However, there can be exceptions to this general rule that need to be considered. For instance, there are some ETC modes that do not have a selection for the number of exposures, in which case the number of integrations may be used. These cases are called out in the sections below, as appropriate.

Support for Ngroups = 1

For near-infrared detectors, APT allows 1 group per integration, but the ETC currently does not. Work is ongoing to understand the full scope of the systematic errors for 1-group integrations based on inflight measurements.

NIRCam interface issues 

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

Nomenclature inconsistencies: In APT, there are separate NIRCam imaging and NIRCam time-series imaging calculations, which each include both the short wavelength (SW) and long wavelength (LW) detector setups. In the 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 calculations in the ETC include subarrays meant only for use in grism mode. See the NIRCam Detector Subarrays article for more information. Running an imaging calculation with a grism subarray will produce a warning message.

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 the 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 total dithers 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 Total Dithers 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 total dithers 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 Total Dithers = 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 multiply the Integrations/Exp and Exposures/Dith fields in APT to get the correct number of integrations. The Total Dithers quantities in the APT and the ETC are equivalent.

Backgrounds in the ETC: In the ETC, the IFU On-Target 2-Point Nod strategy is equivalent to an APT dither, while the IFU On-Target + Off-Target Pointing 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 the 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 the ETC to estimate the expected S/N that will be achieved. Dithers are handled as individual exposures in the ETC, and they represent the total number of integrations at a particular pointing. Starting from ETC 3.0, the former Detector Setup tab field Exposures per specification is now named Total Dithers

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 2-point SNR, with a correction factor. Refer to the NIRSpec Background Recommended Strategies article for details.

NIRSpec IFU Aperture Photometry: A new feature starting with ETC 3.0 is the strategy IFU Aperture Photometry. It is the default IFU strategy upon entry into the IFU mode of the ETC. This strategy for the IFU is set up in the same manner as aperture photometry strategies in the ETC for the other NIRSpec observing modes (FS, IFU, MOS). This is a useful ETC feature for estimating background subtraction, which does not have a comparable dither strategy in the APT.

NIRSpec IFU On-Target 2-Point Nod positions in the ETC: This option found in the Strategy tab has default offset positions, which can be edited by the user. The default offsets are not the same as the 2-point nod positions that are available as observing options in the APT. However, the values can be edited to agree with the APT 2-point nod positions. (See the strategy article.) Nodding in-scene (IFU On-Target 2-Point Nod strategy in the ETC) should only be used for very compact (<0.3") science sources. For sensitivity calculations on all spatially extended science sources, the IFU On-Target + Off-Target Pointing option in the Strategy tab is recommended. For IFU On-Target + Off-Target Pointing the exposure time is half that of the IFU On-Target 2-Point Nod case, since background observations are not included in the IFU On-Target + Off-Target Pointing scenario. When filling in the APT proposal form for IFU On-Target + Off-Target Pointing, separate observations of the same exposure duration will need to be included to account for background observations.

NIRSpec imaging calculations: There is the option to calculate signal-to-noise with user-selected exposure times in NIRSpec imaging data acquired with the mirror in the grating wheel assembly. In APT, 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 pull-down menu. The NIRSpec Target Acquisition (TA) ETC calculation mode delivers signal-to-noise in the fixed exposure time set by the detector readout pattern NRSRAPID, NRSRAPID1, NRSRAPIDD2, or NRSRAPIDD6 (traditional readout) used for the Groups 3 image acquired for TA. The shutter grid size for MOS_VER and the MSATA is 11 × 7, whereas APT assumes a 13 × 7 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. The Total Dithers field in the ETC Detectors Setup tab should be kept at 1. Dithering is not done in BOTS mode (see NIRSpec Bright Object Time-Series Spectroscopy). 

NIRISS interface issues

Detector readout pattern inconsistencies (SOSS): For the single object slitless spectroscopy (SOSS) mode, only the NISRAPID readout pattern is supported when using the SUBSTRIP96 and SUBSTRIP256 subarrays. The ETC presents the NIS readout pattern in the dropdown even when a SOSS subarray is selected, but will prevent calculations from running 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.

Detector readout pattern inconsistencies (AMI): For the NIRISS Aperture Masking Interferometry mode, only the NISRAPID readout pattern is supported in APT when using the SUB80 subarray. The ETC presents the NIS readout pattern in the dropdown menu and provides a warning on the Detector Setup tab, but still allows the calculation to proceed. 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 the 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 × Number of frames/group + 1) × Number of integrations × frame time, while the total photon collecting time is Number of groups × Number of integrations × Number of frames/group × 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 3.0.

    Updated for ETC 2.0.

    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 1.3 and APT 27.0

Originally published