JWST ETC Creating a New Calculation

JDox will be unavailable from Friday, April 12th, starting at noon through Sunday, April 14th, due to a planned outage. We apologize for any inconvenience.

In the JWST Exposure Time Calculator (ETC) a new calculation can be initiated by choosing an instrument and mode, or copying and modifying an existing calculation. The calculation requires an existing library of scenes and sources.

On this page

Video Tutorials:  ETC General OverviewETC Backgrounds

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

The JWST Exposure Time Calculator (ETC) calculation is performed from the Calculations page where the user chooses the input parameters which include:

  1. instrument and mode,
  2. scene containing one or more sources,
  3. background model parameters,
  4. instrument configuration,
  5. detector setup, and
  6. the strategy for calculation of the signal to noise.

The location of the tabs where the input parameters can be provided on the Calculations page is shown in Figure 1 by the numbers in red. 

Video Tutorial

The video tutorial ETC General Overview provides a walk-through of setting up a calculation in ETC.

Create a new ETC calculation

A new calculation may be created by 2 methods: selecting an instrument and mode, or copying and modifying an existing calculation. The Calculations page has instrument buttons for each of the 4 JWST science instruments, and each instrument button has a drop-down menu with all the modes offered for that instrument. Selecting an instrument and the mode immediately initiates a calculation using the default scene with default source. The new calculation can then be edited for the desired input parameters as described in the following sections. If the user wants to copy and modify an existing calculation, this is accomplished by using the Copy Calculation option from the Copy/Delete drop-down menu at the topmost left corner. This creates an exact copy of the calculation and the user can modify the calculation by changing the input parameters as described below.

Editing an ETC calculation

To edit a calculation, select it by clicking on the row corresponding to that calculation so that it is highlighted. The "Calculation Editor" pane (in the top right) is activated and the input parameters can now be modified to change the scene, backgrounds, instrument setup, detector setup, and strategy.


In the "Calculation Editor" pane, click on the Scene tab. This offers a drop-down menu of all the scenes available in the scene library, which is used to specify which scene should be used for the existing calculation. Often, this is the only thing users need to manipulate on the Scene tab. 

Choosing a scene automatically populates the Source tab with all the sources present in that scene. The "Calculation Editor" pane provides all the same input parameters offered under the Source editor of the Scenes and Sources page and can be directly modified on this pane in the Calculation page.

Remember that when a change is made to the source properties from the "Calculation Editor" pane, it modifies the source in the source library on the Scenes and Sources page and affects all the calculations that use that particular source. If you are not sure you want to change the property of a given source and affect all the calculations involving that source, then go to the Scenes and Sources page, copy and modify the source, and use it in the desired scene before performing the calculation.


The ETC calculations can include Background from the expected in-field zodiacal light (within the FOV) and stray light (scattered into the FOV), which is the total input sky background for a given set of celestial coordinates and optionally a specified date.

The ETC can use and report a dated sky background or a non-dated sky background. When a date is specified, the ETC will use the background model generator to generate the background for the specified sky position (RA, Dec) for that date. The non-dated background offers a choice of Low, Medium, or High which correspond to the 10th, 50th, or 90th percentile of the sky background over the period of visibility for that sky position, respectively. 

Instrument setup

The Instrument Setup tab offers the choice of filters, grisms, dispersers, and slits for the different JWST instruments. For imaging modes, the Instrument Setup has a drop-down menu with the choice of filters that can be used for the imaging calculation. For wide-field slitless spectroscopy modes—available with NIRISS and NIRCam—there are two drop-down menus, one for the grisms and the other for the blocking filters that are used in combination with the grism. The MIRI MRS and MIRI MRS Time Series modes have options for choosing the channel and disperser. NIRSpec IFU calculations require the grating/filter pair to be selected. The NIRSpec MSA setup is specified by choosing the grating/filter pair, slitlet shape, and MSA location. The NIRSpec Fixed Slit and NIRSpec Bright Object Time Series modes require the grating/filter pair and slit to be selected. For spectroscopy modes that do not require a blocking filter, only a menu for the disperser is provided (e.g., NIRISS SOSSMIRI LRS).

Detector setup

The Detector Setup allows the user to specify the following parameters: Subarray, Readout pattern, Groups per integration, Integrations per exposure, and Total Dithers. All of these parameters control the exposure time and photon-collecting duration.

Helpful Tips

All JWST detectors integrate using MULTIACCUM readout, which consists of "up-the-ramp" sampling.

  • Groups per integration = number of groups in an integration (each group can have a number of frames that may be averaged, depending on readout pattern)

    A GROUP consists of one or more consecutively read FRAMES with no intervening resets. A FRAME is the result of sequentially clocking and digitizing all pixels in a rectangular area of a sensor chip assembly (SCA). 

  • Integrations per exposure = number of integrations in a single exposure

    An INTEGRATION is the end result of resetting the detector and then non-destructively sampling it one or more times over a finite period of time before resetting the detector again. This is a unit of data for which signal is proportional to intensity, and it consists of one or more GROUPS.

  • Total Dithers = number of dithers

    The end result of one or more INTEGRATIONS in a particular pointing.

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.

For subtle interface differences, please visit the JWST ETC to APT Interface Support article.


The Strategy tab is where the user defines the extraction parameters for the source flux and for the background region to be used for background subtraction. There are different strategies implemented depending on the mode, for example, imaging, slit spectroscopy, slitless spectroscopy, and coronagraphy.

In general terms, the strategy defines the location of the aperture for extracting the source flux and the size of the aperture. There is also an option to define a region for extracting the background flux if background subtraction is required. The background in the region defined for background flux extraction will include the sky background as well as any other flux from nearby overlapping sources that contribute to the defined background region. For the IFU modes the background is estimated by using the IFU On-Target + Off-Target Pointing scene option.

If a background region is not specified, then a noiseless sky background is subtracted from the source aperture. The total sky background includes the contribution to the FOV from the in-field zodiacal light and the stray light from outside that is scattered into the FOV. 


Running the edited ETC calculation

After all the above mentioned parameters have been set, the calculation is performed by clicking on the CALCULATE button. If the sources used in the newly created calculation are included in other existing calculations, then all of those calculations will be run simultaneously. Once the calculation is completed the results may be viewed in the Images pane, Plots pane, and the Reports pane. If the user wants to delete a calculation, there is a Delete Calculation option available in the Copy/Delete drop-down menu in the top left corner. There is also an option to delete multiple calculations at once by choosing Delete Marked Calculations.


Go to the on-line JWST Exposure Time Calculator Tool

Pontoppidan, K. M., et al., 2016, Proc. SPIE 9910, Observatory Operations: Strategies, Processes, and Systems VI, 991016
Pandeia: a multi-mission exposure time calculator for JWST and WFIRST

Latest updates
    Updated for ETC 3.0.

    Updated for ETC 2.0.

    Updated for ETC 1.6.

  • Updated for ETC 1.5. Video links added.

  • Updated for ETC 1.3. Many links to other articles added.

    Updated definitions of exposure parameters in the Helpful Tips box. Added information about ETC and APT interface between exposure parameters.

    Updated to include in-line links to relevant articles for ETC v1.3 upgrade.

Originally published