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. 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 continuous development and subject to future updates. Current documentation is best effort based on ETC v1.5.1 and APT v2020.1.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 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 from being 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 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 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.

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

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.

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 (Fixed Slit/BOTS) spectroscopy.  There is no mode in the ETC 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, dithering strategies are mimicked in ETC by the number of exposures in the Detector Setup tab. For example, in the NIRSpec IFU Nod in Scene strategy, if you wish to use a 4-point observing dither pattern, the number of integrations per exposure should be specified as 2, since each integration in this mode accounts for 2 dither positions in the ETC.

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 that might require different exposure times include "Verify_Only" pointing verification exposures, as present in the ETC as modes “IFU Verification Imaging” and “MOS Verification Imaging”, as well as NIRSpec MOS "Confirmation Images", which is specified using the “MOS Confirmation Imaging” mode. The NIRSpec "Target Acquisition" (TA) ETC calculation mode delivers signal-to-noise in the fixed exposure time set by the detector readout pattern NRS, NRSRAPID1, NRSRAPIDD2, or NRSRAPIDD6 (traditional readout) used for the ngroups=3 image acquired for TA.  

NIRSpec IFU "Nod in Scene" 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 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 can be edited by the user to agree with the APT 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 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.) 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 in the ETC when distinguishing between the FS science mode and the BOTS mode of NIRSpec because subarrays are not permitted in MOS or IFU science modes. 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.

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

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