The JWST Exposure Time Calculator (ETC) allows the user to define sources, place them in , 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:
- Following the Quick Start walk-through.
- Experimenting with a copy of a Sample Workbook.
- 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 workbookWithin 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 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.
- Create one or more sources. A default scene, populated by one default source, is made available when a new empty workbook is created (Sample 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.
- 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 , 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.
- 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.
- . 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.
- 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.
- 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.
- Examine the output information from a selected calculation. Results may be viewed in the Images pane (left), Plots pane (center) and Reports pane (right).
- 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.
- Save and organize your calculations.
- 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.
Video tutorials are available for: