JWST ETC Scenes and Sources Page Overview

The Scenes and Sources page in the JWST Exposure Time Calculator (ETC) contains an overview of all scenes and sources in a workbook. Users can also create, edit, and inspect their scenes and sources.

On this page

Video Tutorials:  ETC Scenes and Sources,  Adding Emission Lines in the ETC

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

The Scenes and Sources page contains an overview and an editor for all scenes and sources within the workbook. From this page, it is possible to create new scenes, associate sources with scenes, edit scene and source parameters, view a representation of the scenes, inspect the spectrum of the sources, and view which calculations currently contain your sources.



Scenes and Sources page layout

Figure 1 shows the layout of the Scenes and Sources page, labeled in blue to identify its panes, tabs, and sub-tabs in the graphical user interface. 

Figure 1. The Scenes and Sources page with labels on its various panes

New scenes and sources can be created using the NEW button within the Select a Scene and Select a Source pane. Initially the source is not associated with any scene and must be explicitly added to a scene using the ADD SOURCE button. Yellow indicates a selected scene and source. Green highlighted rows are those affected by the selected row in other tables. The newly added source will now be visible at the center of the scene sketch. The striped green and yellow indicates that a row is both selected and affected. Use the copy scene or copy source options in the Copy/Delete drop-down menu to modify the scenes and sources, and use them in a new calculation to avoid auto-update of all affected calculations when an existing scene or source is modified. A purple star next to the left of the scene ID in the Select a Scene table indicates which scene will be used as a default for calculations; this can be changed. The Source Editor pane is where users can specify the following parameters: ID, Continuum, Renormalization, Lines, Shape, and Offsets. Scene and source properties are presented in the two lower panes: the Scene Sketch pane and the Source Spectrum plots. 


Scene and Source tables

Tables in the Scenes and Sources panes are interactively linked, and provide visual cues for the relationship of scenes and sources. When a scene is selected in the Scene table, all sources contained in that scene will be highlighted in green in the Source table. Conversely, when a source is selected in the Source table, all scenes containing that source will be highlighted in green in the Scene table. For convenience, 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.

Both tables are also interactively linked with the "Used in Calculations" pane in the lower right. This table lists all calculations in the workbook. All calculations that are affected by the selected scene (i.e., it uses that scene) or source (i.e., the scene it uses contains that source) will be highlighted in green. All affected calculations will automatically be updated when the selected source or scene is changed.

These tables allow the user to see and manage the scope of any changes to sources and scenes. A recommended workflow is to perform detailed manipulation only on sources and scenes that are not yet used by any calculations. Use the copy scene or copy source options in the Copy/Delete drop-down menu to modify the scenes and sources, and use them in a new calculation to avoid auto-update of all affected calculations when an existing scene or source is modified.



Defining scenes and sources

Sources

Creating a source

Sources contain the spatial-spectral information that will be used in the scenes and calculations. 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). This source is initially not associated with any scene, and must be explicitly added to a scene using the ADD SOURCE button within the Select a Scene pane.

Editing a source

The specific information for the source can be edited in the Source Editor pane. To edit the source information, the user must first select a source from the Select a Source pane. Navigation is done by selecting a tab within the editor, as listed below:

ID

Contains the identity information for both the source and the scene. It is where the user can change the default name and create descriptive references to the source or scene.

Continuum

Contains options for the spectral energy distribution, extinction to be applied, and the redshift information for the source's spectrum.

Renormalization

Allows a user to renormalize a source spectrum by specifying the flux either at a particular wavelength, or in a normalization bandpass. Instrument-specific HST and JWST bandpasses are offered, as well as more general photometric bandpasses. The source flux distribution may be specified in integrated flux or magnitude, and for extended sources there is also the option to specify the normalization in surface brightness units.

The order of operations is to apply the redshift, then the extinction, then renormalize. Lines are added to the spectrum following renormalization, so line parameters must therefore be specified with respect to the redshifted, extincted, renormalized spectrum.

Lines

Allows the user to add spectral lines to the source spectrum. Currently, only emission features are supported.

  • To add a line, the user must first input four values: a user-defined name for the line, the line center (in μm), the line width (in km/s), and the line strength (in erg/cm2/s). The line strength corresponds to the integrated flux, not the peak flux. Once these values have been provided in their respective fields, clicking the ADD button will include the line in the line table. Click the SAVE button to apply this change. The source spectrum, with the emission lines added to it, may be viewed by using the checkbox in the Select a Source table to plot the source spectrum.

  • To edit a line, simply select the line by clicking the appropriate row in the line table. The input fields will be automatically populated with the current values of that line. Simply change the values displayed in the input fields to edit the currently selected line. Once changes have been made, click the UPDATE button. The line table row should now be updated with the new values.

  • To remove a line select the appropriate row in the line table and click the REMOVE button.

After defining all the lines, you must click the SAVE button to apply them to the source spectrum.

Shape

Allows the user to define the source as either a point source or an extended source. Choosing Extended allows for flux distribution, normalization, and axial extent options. The flux normalization for extended sources may be done in integrated magnitudes or surface brightness units, and the selection made in the Shape tab will be reflected in the units used in the Renorm tab (i.e., adding "per arcsec^2" or "per sr" to the right of the unit dropdown menus).

Offset

Contains options for the position of the selected source within the selected scene such as adding spatial offsets, or giving the source some orientation.

There must be a source added to a scene before entries in the Offset tab can be edited.

Saving and Resetting

You may move between these tabs while editing the source, but you must click SAVE before selecting a different source in the source table, or your changes will be lost. Clicking the RESET button will revert your changes to the most recently saved values.



Scenes

Scenes are idealized representations of spatial (two angular coordinates) and spectral brightness distributions, before being observed by a telescope. They are composed as "postage stamps," that is, relatively small areas of ~10–20 square arcseconds (Table 1 shows the default and maximum scene size that will be used in the calculation, centered on scene center for each instrument/mode pairing). Although not a fundamental limitation, this restriction conserves computational resources and reduces the time for calculations. Scenes also contain the source targets of an observation, and all other nearby sources that could contribute to both the observed target and background fluxes

Placement of 2 or more sources within the limits of the default scene size, then centering the extraction aperture and background annulus on a source not in the center of the scene could result in a portion of the extraction aperture or background annulus (or both) falling outside the scene limits. This will produce and error and will prevent the calculation from running. The workaround for this is to add a new source to the scene, offsetting it to a larger distance from the center. This expands the scene size beyond the default size. Note, however, that this works only for modes that use dynamic scene sizes, as indicated in the table below.


Table 1. Default and maximum scene size used in the calculation

InstrumentModeDefault scene size (arcsec)Max scene size (arcsec)PSF size (arcsec)Dynamicª
MIRIImaging6.0540.05.61True

Imaging Time Series6.0540.05.61True

LRS Slitted6.0510.06.05True

LRS Slitless6.0030.05.61True

MRS/MRS Time Series IFU (ch1)§

4.12 

4.12False

MRS/MRS Time Series IFU (ch2)§4.514.51False

MRS/MRS Time Series IFU (ch3)§6.136.13False

MRS/MRS Time Series IFU (ch4)§7.927.92False

Coronagraphy8.918.91False
NIRCamLW Imaging4.0020.03.21True

SW Imaging2.0010.01.59True

WF Grism2.0010.03.21True

LW Time Series Grism2.0010.03.21True

LW Time Series3.213.21False

SW Time Series2 (SW) 4.70 (WLP4) 6.25 (WLP8)1.59/4.70/6.25False

Coronagraphy3.33 (SW) 6.36 (LW)3.14/6.36False
NIRISSImaging4.0020.04.0True

SOSS16.94.0False

WFSS15.075.04.0True

AMI5.315.31False
NIRSpecFixed Slit3.0020.03.07True

BOTS3.0020.03.07True

MOS3.0020.03.07True

MOS Confirmation Imaging3.0020.03.07True

MOS Verification Imaging3.0020.03.07
True

IFU2.992.99False

IFU Verification Imaging2.992.99False

The scene sizes refer to the width on each side.

§ MIRI MRS sizes refer only to the Y-axis dimension of the non-square field of view.

‡ PSF sizes are square, and denote the size of the region around an actual source that contains flux (useful for extraction aperture and annulus sizing).

ª Indicates whether the scene is dynamic. If true, the scene will grow to encompass all specified sources up to the maximum scene size. Not all modes support dynamic scenes. If Dynamic scene is False, the scene size is set by the PSF footprint taken from the PSF library, which varies based on the observing mode settings.

Adding sources to scenes

A new workbook created by a user will initially contain a default scene and a default point source. To add a scene, click the NEW button at the bottom of the Select a Scene pane. The user will find that the table has been populated with a new scene, and selecting this scene will allow the user to view an idealized representation in the Scene Sketch pane below. The new scene is empty and sources can be added to it.

To create a new source, a user must click the NEW button in the Select a Source pane, to the right.

After having created a new source, the user will have to explicitly associate the source with a scene, as it is possible to have multiple scenes that contain the same source. To do so, the user must select the desired source in the source pane, select the scene to which the source will be associated, and click the ADD SOURCE button. The previously yellow highlighting of the selected scene and source will now be visible as a striped green and yellow pattern. The newly added source will now be visible at the center of the scene sketch. You may now use the Offsets tab to place it at the desired location (refer to the Sources and Scene Tables section for a more in-depth explanation of the color scheme). Likewise, the Scene Sketch pane should now display the idealized 2D representation of the scene.

To remove a source from a scene, select the scene and the associated source and click the REMOVE SOURCE button. This will not delete the source, but only remove its association with that particular scene. Again, the user will notice that the source has been removed from the Scene Sketch pane.

To delete a scene, select a scene and click the DELETE button at the bottom of the pane.

Note that if there exists a calculation that contains the scene, the user will not be able to remove the scene without first modifying the calculation to use a different scene, or simply deleting the calculation. The column # Calcs displays the number of calculations that contain the scene.

The default scene in a workbook is used for any default calculation that is triggered when an observing mode is selected from the instrument tabs on the Calculations pane. The default scene provided with a new workbook has a single default point source with a flat continuum, located at the center of the scene. However, the user has the option to change the default scene to any of the new scenes that they have created in the Select a Scene table. Clicking on the purple star in the row containing a scene will make that the default scene. Users are advised to use a simple scene with simple source properties as the default scene. A more complex scene or scene containing complex sources that is assigned to be the default scene can slow down the default calculations considerably.



Viewing scenes and source

Scene and source properties are presented in the two lower panes: Scene Sketch and Source Spectrum Plots. The Scene Sketch is interactively linked with the Source Table. A selected source will appear yellow in the sketch, and clicking on a source in the sketch will select its row in the Source Table. Selecting a scene will automatically update the Scene Sketch pane with an idealized (i.e., before being observed by a telescope) representation of the sources within that scene. The source is directly influenced by the settings within the Source Editor pane; e.g., the idealized sources will reflect the shape and offset parameters defined by the user.

Selecting a source will automatically check its Plot checkbox and show its spectrum in the Source Spectrum Plots. Multiple sources can be compared by manually checking their Plot check boxes. For convenience, the Plot column heading is a drop-down that allows the user to check All or None of the entries for plotting. The extent of the plot axes may also be controlled by setting the bounds below the spectra plot and clicking the APPLY button.

While the # Calcs column of the Select a Scene and Select a Source panes tell the user how many calculations the scene(s) and/or source(s) are used in, users may wish to refer to the "Used in Calculations" pane to view the specific calculations affected by a change in the selected source or scene. The "Used in Calculations" pane displays any calculations that any source or scene are actively used in, but selecting a source or scene will correspondingly highlight the associated calculation(s) in green.



Related articles



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
Pandeia: a multi-mission exposure time calculator for JWST and WFIRST




Latest updates
  •  
    Updated for ETC 3.0.

  •  
    Updated for ETC 2.0. Added additional information to Table 1.

  •  
    Clarifications made to the text.


  • Updated for ETC 1.5. Video links added.


  • Updated for ETC 1.3.
Originally published