JWST ETC New User Guide

The JWST Exposure Time Calculator (ETC) requires various input parameters and configuration settings. Users can get started quickly with these easy steps. 

On this page

Video Tutorials:  ETC Home Page Overview,  ETC General OverviewETC WorkbooksETC Scenes and Sources  

The JWST Exposure Time Calculator (ETC) allows a user to define sources, place them in scenes, and use the scenes in calculations. Sources may be used in multiple scenes, and scenes may be used by multiple calculations, which will be automatically recalculated to reflect any changes made to the scenes or sources. These calculations are organized and saved in workbooks, along with the library of sources and scenes. Workbooks for users who are logged-in using MyST accounts are automatically saved and will be available in the workbook list upon return. Workbooks created as an anonymous user are not preserved. Workbooks can be further organized into folders.

The recommended workflow is "copy and modify": create a default object (source, scene, or calculation), then modify it, then copy it and modify it further. Calculation results can be over-plotted for easy comparison.

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

Generally speaking, new ETC users have 3 different ways to get started: 

  1. Follow the Quick Start walk-through
  2. Experiment with a copy of a Sample or Example Science Program Workbook
  3. Starting from scratch with an empty workbook

Quick Start mode

The Quick Start mode is an interactive walk-through designed to help new users quickly navigate through the ETC. Access to Quick Start mode is available at the ETC home page and is activated by clicking the quick start button.

In order to keep this workbook, you will need to login or create an account. You may save the workbook once you are logged in as a registered user. Upon completion of the "Quick Start" tutorial, a pop-up box will present information on how to save the workbook.

Even if you are logged in, clicking on the Quick Start button logs you out and makes you an anonymous user. To save your work for future access or access previously saved workbooks, you will need to log in again.

Working with a workbook

Within the Quick Start tutorial, the user is navigated by text and touch-points that introduce the application's features and prompts the user to take compulsory action steps. For example, once the tutorial is launched, the user is greeted by a welcome message and prompted to select an instrument and mode by selecting one of the highlighted Instrument tabs; it is only then that access to the configuration pane is made available. Users are guided through the basics before being encouraged to click the CALCULATE button, at which point the tutorial concludes and the user is left to independently explore the application.

Depending on how you have chosen to proceed—whether by completing the Quick Start tutorial, creating a new empty workbook, or by retrieving a copy of one of the pre-populated sample or example science program workbooks—you will now have access to a workbook with which to edit. What follows is a set of easy steps designed to help users familiarize themselves with the ETC.

On the Scenes and Sources page

  1. Create one or more sources
    A default scene, populated by one default source, is made available when a new empty workbook is created (sample and example science program workbooks contain scenes that are pre-populated with sources). The default source is a point source with a flat continuum spectrum. Sources contain the spatial and spectral information that will be used in the scenes and calculations. For each source, you may specify the Continuum, Renorm (normalization), Redshift, Extinction, emission Lines, and Shape. Be sure to click Save before moving to a different source.
    • Create a new source via the NEW button within the Select a Source pane will result in a new default source (point source, flat spectrum). 
    • Initially, a new source is not associated with any scene and must be explicitly added to a scene. Select the source in the Select a Source pane and a scene from the Select a Scene pane, and click the ADD SOURCE button. The source will be added to the the center of the scene.

  2. Edit one or more sources using the Source Editor pane.
    In order to select a source for editing, click on a row in the Select a Source pane. When a source is selected in the Source table, all scenes containing that source will be highlighted in green in the Scene table. Navigation is done by selecting a tab within the Source Editor pane:
    • Add scene and source identity information into the ID tab.
    • Change the source's shape using the Shape tab and specify any required parameters, depending on the chosen morphology.
    • Position the source in the scene using the offset options in the Offset tab. Spatial offsets are defined with respect to the center of the scene.
      • The offset parameters link the source and the scene; check that the source is added to a scene, in order for the offset parameters and orientation to take effect.
    • Supply information for the source's spectrum in the Continuum tab.
    • To renormalize the source's spectrum, specify the flux at either a particular wavelength, or in a normalization bandpass, in the Renorm tab.
    • To upload your own spectrum, select the Upload Spectra tab. You may upload one or more spectra. When you return to Scenes and Sources, your uploaded spectra will appear in a drop-down menu in the Continuum tab under the Source Editor pane.
    • To add emission lines to a source continuum, select the Lines tab and use the available options to specify the properties of the line. Click the ADD button and the line will be added to the table of lines, which is populated with the input parameters supplied by the user.
      • Use the UPDATE and REMOVE buttons to modify the parameters of an emission line, or to remove it from the line list.

  3. Examine the sources. 
    Sources that are created may be examined in the Scene Sketch and Source Spectrum Plots panes:
    • Examine the morphology of the sources and their location in the scene using the graphical representation displayed in the Scene Sketch.
    • If a source is missing from a scene: select the source in the Select a Source pane. Then, in the Select a Scene pane, select the correct scene and click the ADD SOURCE button. Likewise, to remove a source from the scene use the REMOVE SOURCE button.
    • Select one or more Plot checkboxes in the Select a Source pane to display the source spectrum in the Source Spectrum Plots pane. Use these plots to verify that the source spectrum is correct.
    • Click on a source in the Select a Source pane and determine which calculations it used by looking at the Calculations tab in the pane below the Source Editor.

  4. Create one or more scenes.
    Scenes are idealized representations of spatial (2 angular coordinates) and spectral brightness distributions (prior to being observed by a telescope). The default and maximum scene size depend on the chosen instrument/mode pairing. They may contain the source targets of an observation, and all other nearby sources that could contribute to both the observed target and background fluxes.
    • Click on a row in the Select a Scene pane to select a scene for editing. When a scene is selected in the scene table, all sources contained in that scene will be highlighted in green in the Source table.

      Clicking on a scene in the Scene table will highlight that row in yellow. Any sources in that scene will be highlighted in green in the Source table. Conversely, selecting a source will highlight in green any scenes that source is in. Highlighting a scene and a source within that scene will highlight both in yellow and green striping. To clear scene and source selections, refresh the page.

    • This new scene is empty and sources can be added to it. To associate a source with a scene, select both the scene and source in the Select a Scene and Select a Source panes (causing them to both be highlighted yellow), and click the ADD SOURCE button.
    • Verify that scenes and sources are linked. If you click on the scene, is the "associated" source highlighted green? Does the source appear in the Scene Sketch pane?
    • For each source, specify its offset from the center (and orientation, for extended sources) for the scene. Be sure to click Save in the Source Editor pane before moving on to a different source.
    • Changes will automatically update the Scene Sketch pane.

    • An empty scene (with no sources) can be useful for examining the sky background. Defining the sky background parameters can be done under the Backgrounds tab on the Calculations page.

On the Calculations Page

  1. Create a calculation.
    A new calculation may be created using 2 methods: (1) selecting an instrument and mode or (2) copying and modifying an existing calculation. For each calculation, you may specify the calculation ID, Scene, Backgrounds, Instrument Setup, Detector Setup, and Strategy parameters.
    • To create a new calculation, click on one of the instrument buttons and select a mode.
    • Click on a row in the Calculations table to select a calculation, highlighting it in yellow. This activates a calculation editor pane to the right of the table.
    • Edit the calculation to modify the ID, Scene, Backgrounds, Instrument Setup, Detector Setup, and Strategy.
      • Click on the Scene ★ tab; in Scene for Calculation, select a scene for the calculation. This action populates the Sources in the Scene pull-down parameters with all sources associated with that scene; select one of them for the calculation. Note that the Scene ★ tab provides the same parameters as those in the Source Editor pane in the Scenes and Sources page.

        Note that changes to source properties made in the Calculation Editor pane modify that source in the source library in the Scenes and Sources page, affecting all calculations for that source.

        The recommended workflow for changing the property of a given source is to copy and modify the source in the Scenes and Sources page, and use this "new" source in the desired scene before performing the calculation.

      • Click on the Detector Setup tab to specify the Subarray configuration, Readout patternGroups per integrationIntegrations per exposure, and Exposures per specificationThese parameters control the exposure time (photon-collecting duration). If an invalid value is provided for one of the detector parameters, it will appear in red and the calculation will not be completed.
      • Under the Strategy tab, define the extraction parameters for the source flux. To include background subtraction in the calculation, define a background region for extracting the background flux.
    • After all the above-mentioned parameters are set, click the CALCULATE button to perform the calculation.
    • In the main menu at the top of the page, you can use Copy/Delete for copying and deleting calculations, and Expand for systematic explorations of parameter space.

  2. Examine the output information from a selected calculation.
    Results may be viewed in the Images pane (lower left of the page), Plots pane (lower center), and Reports pane (lower right).
    • Click on a row in the calculations table to view the 2D output images for that calculation. Use the 2D SNR, DetectorSaturation, and Groups Before Saturation tabs to view the images under each of those conditions.
      • The image contains the entire scene used in the calculation.
      • Check saturation levels and the exact locations of saturated pixels, if any, to determine if the data would be useful.
    • Check the Reports pane for saturation warnings in the Warnings tab. If saturation has occurred, the Warnings tab will appear in red. The warning message will indicate the number of pixels with full and partial saturation.
    • Review the summary of the calculation under the Reports pane. It provides a summary of the input parameters and output scalar values associated with the selected calculation.
    • Manually check the checkboxes in the calculation rows to see the plots produced by the calculation.
      • The checkboxes serve dual purposes: to select calculation rows to display plots or to delete marked calculations.
      • Multiple calculations may be over-plotted for easy comparison. Different colors indicate the different calculations.

    • In order to view all calculations in a given workbook, simultaneously over-plotted, click on the checkbox symbol between the ID and Mode columns in the Calculation table and select the All option. Use this feature to compare calculated parameters for different filters/gratings of the same instrument, or for different instruments.

    • Create a batch expansion over one of the Detector Setup parameters (groups or integrations) or over any of the Instrument Setup parameters (dependent on observing mode).

  3. Download the output products and intermediate products from the ETC calculations.
    • Click the link under the Downloads tab in the Reports pane. The tarball contains FITS files of the 3D data cube for the IFU calculation and the 2D images. The extracted flux, backgrounds, contamination, and SNR used for the line plots are available as FITS tables. 
    • Widgets at the top of the Plots pane allow users to download the plots. (To see them, move your cursor over the plot.)
    • To download one of the calculation images, click on the link below the image in the Images pane. (To see them, move your cursor over the image.)

  4. Modify the name and description of the workbook.
    By default, whenever a new workbook is created, it is named "New Workbook" and described as "An Empty Workbook."
    • Notes about the workbook can be entered at the bottom of the Calculations Page.
    • Organize your calculations and save your workbook. A MyST account is required to save the workbook.


JWST Exposure Time Calculator Tool

Pontoppidan, K. M., Pickering, T. E.,  Laidler, V. G.  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 1.5. Video links added.

  • Fixed some formatting issues.

  • Updated for ETC 1.3. Name of article changed.
Originally published