JWST ETC New User Guide

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

On this page

The JWST Exposure Time Calculator (ETC) allows the 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 and will not be available upon login the next time.

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.

Generally speaking, there are three different approaches in which a new user can introduce themselves to usage of the ETC:  

  1. Following the Quick Start walk-through.
  2. Experimenting 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 which is designed to help new users quickly navigate through the ETC. Access to Quick Start mode is available at the ETC Welcome 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.

Selecting this mode signs the user out if they were originally logged in, so users will not have access to their workbooks in Quick Start mode. To access saved workbooks, the user must 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 prompt 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 explore the application independently.

Depending on how you have chosen to proceed – whether by having completed 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 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.
    • Creating 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.
    • In order to renormalize the source's spectrum, specify the flux at either a particular wavelength, or in a normalization bandpass, in the Renorm tab.
    • In order 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.
    • 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 and, 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 their Source Spectrum Plots. 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 is used in, by looking at the Used in Calculations pane.

  4. Create one or more scenes. Scenes are idealized representations of spatial (two 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.

      We refer to green highlighted rows as affected by the selected row in the other table. It is possible for a row to be both selected in its own table (yellow) and affected by the selection in the other table (green): in this case, the row appears with yellow and green striping.

    • 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 "associated" source highlighted green? Does the source appear in the Scene Sketch?
    • For each source, specify its offset from the center (and orientation, for extended sources) of 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 panel.

    • 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 by two methods: selecting an instrument and mode, or copying and modifying an existing calculation. For each calculation, you may specify the calculation ID, Scene, Backgrounds, Instrument Setup, Detector Setup, and Strategy parameters.
    • Select one of the instrument buttons and a mode from the instrument button's drop-down menu to create a new calculation.
    • Select a calculation by clicking the row corresponding to that calculation, so that it is highlighted, in the Calculation table. This will activate the calculation Configuration pane.
    • Use the Configuration pane to modify the ID, scene, backgrounds, instrument setup, detector setup and strategy.
    • Click on the Scene ★ tab and select which scene to use in the existing calculation from the drop-down menu of all the scenes available in the scene library.
      • This will populate the source tab with all the sources present in that scene.
      • The Scene ★ tab provides all the same parameters offered under the source editor of the Scenes and Sources page and can be used to directly modify sources on the Calculation page.

        Note that when a change is made to the source properties from the Configuration 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.

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

    • On the Detector Setup tab, specify the subarray configuration, readout pattern, number of groups, number of integrations, and number of exposures. These 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 be prevented from completing.
    • Define the extraction parameters for the source flux in the Strategy tab.
    • To include background subtraction in a calculation, go to the Strategy tab and define a background region for extracting the background flux. For IFU modes, select the IFU Nod off scene option for background subtraction.
    • After all the above mentioned parameters are set, click the Calculate button to perform the calculation.
    • Investigate the Edit menu for copy and delete options, and the Expand menu for systematic explorations of parameter space.

  2. Examine the output information from a selected calculation. Results may be viewed in the Images pane (left), Plots pane (center) and Reports pane (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 of each.
      • The images contain the entire scene used in the calculation.
      • Check the saturation levels and the exact locations of saturated pixels, if present, to determine if the data would be useful.
    • Check the Reports pane for warnings of saturation 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 that is selected in the Reports pane. The report provides a summary of the input parameters and output scalar values associated with the selected calculation.
    • Manually check the checkboxes in the calculation rows in order to see the output plots products of a calculation.
      • The checkboxes serves dual functionality: 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 over-plotted simultaneously, click on the checkbox symbol below the Instrument tabs in the Calculation table and select the All option in the drop-down menu.

      • Use this feature to compare calculated parameters for different filters/grisms 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 in the Downloads tab of 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 download one of the calculation images, click on the link below the image in the Images pane.

  4. Modify the name and description of the workbook. Whenever a new workbook is created it is named "New Workbook" and described as "An Empty Workbook", by default.
    • Write some Notes regarding the contents of the workbook: this is found at the bottom of the Calculations Page.
    • Save your workbook. In order to save a workbook users will need to have obtained a single sign-on account using MyST accounts.Save and organize your calculations.

Video Tutorials

Video tutorials are available for: 

    MultiExcerpt named 'ETCSources2Scenes' was not found
The page: Video Tutorials was found, but the multiexcerpt named 'ETCSources2Scenes' was not found. Please check/update the page name used in the 'multiexcerpt-include macro., 
    MultiExcerpt named 'ETCLibrary' was not found
The page: Video Tutorials was found, but the multiexcerpt named 'ETCLibrary' was not found. Please check/update the page name used in the 'multiexcerpt-include macro., and 
    MultiExcerpt named 'ETC_Calc' was not found
The page: Video Tutorials was found, but the multiexcerpt named 'ETC_Calc' was not found. Please check/update the page name used in the 'multiexcerpt-include macro..



References

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




Published

 

Latest updates

  • Fixed some formatting issues


  • Updated for ETC v1.3.
    Name of article changed