JWST Exposure Time Calculator Overview

The JWST Exposure Time Calculator (ETC) performs signal-to-noise ratio calculations for all JWST observing modes. Scenes, sources, and calculations can be created, copied, and modified by users, and organized in workbooks.

The JWST Exposure Time Calculator, ETC 3.0, will be available for Cycle 3 proposers on August 24, 2023.


On this page

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

JWST's Exposure Time Calculator (ETC) is built on Pandeia, a pixel-based exposure time calculator paired with a modern graphical user interface. While Pandeia was developed for JWST, it is a general framework, data-driven ETC capable of supporting multiple missions. It includes advanced features that go well beyond what has been available in previous ETCs, such as algorithms that accurately model both data acquisition and post-processing of data, and it provides functionality for users to efficiently explore and compare a large volume of parameter space in their calculations.

The JWST implementation of Pandeia supports all JWST observing modes: imaging, spectroscopy (slit, slitless, MOS, and IFU), coronagraphy, and aperture masking interferometry. Its graphical user interface provides enhanced capabilities supporting multiple workflows. For example, users can create workbooks to manage related sets of calculations, create complex astronomical scenes with multiple sources, and compare the results of multiple calculations. The ETC interface is built to encourage a "copy and modify" workflow: users can copy and modify individual calculations, individual sources and scenes, and whole workbooks.



Under the hood: The ETC engine 

The JWST ETC engine uses a pixel-based 3-dimensional approach to perform calculations on small (typically a few arcseconds) 2-dimensional user-created astronomical scenes. It models both the spatial and the wavelength dimensions, using realistic point spread functions (produced using WebbPSF) for each instrument mode. It natively handles correlated read noise, inter-pixel capacitance, and saturation. Since the signal and noise are modeled for individual detector pixels, the ETC is able to replicate many of the steps that observers will perform when calibrating and reducing their JWST data. This simplifies interpretation of the extracted signal-to-noise ratio (SNR) calculated by the ETC.  

While the JWST ETC includes many effects not typically included in other ETCs, it is not an observation simulator. It does not simulate the full detector, nor does it include 2-dimensional effects such as distortion.

Details on the algorithms used to compute signal and noise on the detector and the strategies used to compute the extracted products can be found in Pontoppidan et al. 2016.



Workbooks: organize and save your ETC calculations

ETC calculations are organized and saved in workbooks. Workbooks consist of a library of sources and scenes, calculations based on the source and scene library, as well as any spectra uploaded by users to that workbook. Workbooks can be further organized into folders.

Users who wish to save their work in the workbooks should obtain a single sign-on account using MyST accounts. Upon logging in to the JWST ETC via STScI's single sign-on authentication, users are provided with a list of their existing workbooks, if any, from which to choose. They can choose to create a new workbook from scratch, retrieve copies of sample workbooks that have been designed for tutorials or starter use, or copy and modify an existing workbook. If users choose to begin working anonymously, and later decide they would like to save their work, they can authenticate at any time and their current workbook(s) will be saved under their user account.

Folders are unable to be transferred between users, so anonymous users will receive an error message when trying to create a folder.

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

The name and description of a workbook can be modified after opening the workbook. Workbooks also include a section for writing notes regarding the contents of the workbook: this is found at the bottom of the Calculations page.

Sample and example science program workbooks

Sample workbooks have been designed to aid users in orienting themselves in the JWST ETC. The set of sample workbooks include calculations for all 4 JWST instruments. Calculations are organized into workbooks by topics or categories such as the observing mode (imaging, slit, slitless, IFU spectroscopy, coronagraphy, and target acquisition). Each sample workbook includes pre-defined sources and scenes for use in the calculations. 

Example science program workbooks have been designed to present realistic examples for users to explore the process of creating a proposal. The programs also have associated JDOX articles and JWST Astronomers Proposal Tool Overview files for the full start-to-finish experience.

A more detailed overview can be found on JWST ETC Using the Sample Workbooks

Shared workbooks

Workbooks can be shared with collaborators. Each individual with whom users share a workbook can be given permissions to read, write, grant access to others, and/or revoke access from others. (Note that whole folders cannot be shared with other users.)

To share a workbook or change the permissions for a shared workbook, select a workbook from the list of available workbooks by clicking anywhere on its row. The users with whom the workbook is shared will appear in the User Access Permissions pane below the list of available workbooks, along with their individual permissions. Users can share the notebook with new collaborators by adding the email addresses connected with their MyST accounts.

The system allows multiple users with write access to modify the same workbook simultaneously.

Be aware that an inherent risk of allowing multiple users to edit workbooks simultaneously is "clobbering." If another user is editing the same workbook, and they change something in any editable field, it will overwrite any edits that are in process in that same field by another user. Thus, collaborators are strongly encouraged to communicate and coordinate their work. To reduce this risk, only "read" permissions are set by default when sharing workbooks, and we recommend that users should always coordinate when granting write access.

A more detailed overview can be found on the JWST ETC Sharing Workbooks page

Folders

Folders are available to help you organize your workbooks. A folder can be created by clicking the CREATE NEW FOLDER button. Folders can be created inside other folders, creating a nested folder structure. Navigation through the folder structure is accomplished by clicking Go to enter a folder, Up to move up one level, or Home to return to the top level folder.

Workbooks can be placed in a folder by clicking Move under options, or by creating a new, sample, or example science program workbook when inside a folder. After clicking Move, a pop-up will appear with a drop-down menu with a list of available folders to move the workbook to.



Build your own scenes and sources library

Each new workbook includes a default point source, which is placed in the center of a default scene. If this is adequate, users can proceed from the Calculations page and begin performing calculations. Sample workbooks often include more complex sources and scenes.

The Scenes and Sources page allows users to create multiple, unique sources, each with their own set of individual specifications, and to place those sources within small scenes (typically a few arcseconds). Each scene can include as many sources as required, and sources can overlap within a scene. Individual sources from the source library can be used in multiple scenes. Adding a source to a scene creates an association between the source and scene, so that any future update to that source will result in changes to every scene in which that source is placed. Likewise, the use of sources and scenes in calculations is a dynamic link, and any update to a source or scene will affect all calculations in which that source or scene is used. 

Both sources and scenes can be shared across calculations. When changes to a source or a scene are saved, all calculations that depend on the source or scene will be automatically rerun.

For each new source, users can specify the spectrum (choosing from provided libraries or spectra they have uploaded) and choose whether to redshift the spectrum, apply extinction, add emission lines, or renormalize at a specified wavelength or bandpass. For extended sources, users will specify the shape and flux distribution. Finally, once a new source is added to a scene, users can choose where to place the source within the scene. If users want to mostly duplicate an existing source, making only minor modifications (for example, placing it at a different position in the scene), they can efficiently do so by copying the existing source and modifying the copy.

In addition to tables of existing scenes and sources, and a Source Editor for specifying the properties of a source, the Scenes and Sources page includes several items to aid users in visualizing their sources and scenes, including the interactive Scene Sketch pane, the ability to plot the input spectra of sources, and a list of calculations that will be affected by changes to the selected scene or source.

A more detailed overview can be found on the JWST ETC Scenes and Sources Page Overview.

Uploading spectra

Users can choose to upload their own set of sample spectra for use in the Source Editor. Spectra can be uploaded as either ASCII or binary FITS files, and the accepted formats are described on the JWST ETC User Supplied Spectra page. 



Build a set of calculations

Once users have defined the necessary sources and scenes for their intended calculations, or chosen to proceed with the existing scene(s) and source(s), they will move to the Calculations page.

A new calculation is initialized by choosing the instrument and mode; a set of default values are assigned to parameters upon initialization. In general, users will then need to modify the default values and click the Calculate button to perform their desired calculation.

Users will specify the following parameters for each calculation: a scene from the Scenes pane, background model parameters, instrument and detector setup (e.g., filters, gratings, and exposure specifications), and extraction strategies for the source and background. The scene used in the calculation, and the sources within that scene, can also be modified from the Calculations page, although this does not provide the detailed reporting (including the number of calculations affected by any changes) that is provided on the Scenes and Sources page.

Alternatively, if users have an existing calculation in their workbook for the instrument and mode of interest, they can simply copy and modify an existing calculation. Copying calculations provides an efficient way to explore variations of the observation setup and extraction strategies, or to calculate the SNR on multiple sources or locations in a scene using identical observation and extraction strategies. Batch expansions can be used to automate the process of copying calculations multiple times and systematically varying filters (for imaging modes) or the exposure specifications (number of groups or integrations).

A more detailed overview can be found on the JWST ETC Calculations Page Overview.

The background model

The ETC background model includes celestial sources (zodiacal light, interstellar medium, and cosmic infrared background) as well as telescope thermal and scattered light. Users can choose a dated or dateless background. A dated background utilizes the specified sky position and a date. Alternatively, users can choose a dateless background: a pre-calculated percentile of the range of backgrounds predicted at the specified sky position over the window of visibility. The percentile choices are low (10%), medium (50%), or high (90%). The ETC uses the measured Galactic emission at the input RA and Dec. The effects of additional sources of astrophysical backgrounds (e.g., diffuse nebular emission) can be modeled by adding to the scene a large, spatially flat source that covers the full scene.

 


Analyze the results

Each calculation results in 2-dimensional images, one-dimensional plots, and scalar diagnostics. Users can view 2-dimensional images of per-pixel SNR, count rate at the detector, and saturation of the selected calculation. Users can also view plots of the flux from sources in the scene in the extraction aperture, the extracted flux from the background, and SNR versus wavelength, as well as SNR versus exposure time and contrast versus separation (coronagraphy only). The 2-dimensional images and scalar values are displayed for the selected calculation, while multiple calculations can be simultaneously plotted in the one-dimensional plots.

The Reports pane presents scalar results, warnings, and errors for the selected calculation, as well as a download link. Downloads include all 2- and 1-dimensional products, the 3-dimensional data cube for IFU calculations, and a FITS table of the calculated background spectrum.

A description of the output products is on JWST ETC Images and Plots and JWST ETC Reports.



References

Go to the on-line 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 (arXiv)
Pandeia: a multi-mission exposure time calculator for JWST and WFIRST




Latest updates
  •  
    Updated for ETC 3.0.

  •  
    Updated for ETC 2.0. Added information about folders.

  •  
    Updated for ETC 1.5. Video links added.


  • Updated for ETC 1.3.
Originally published