How to create a default Pandeia calculation with the build_default_calc function or by importing a JSON file from the web UI, how to make basic configuration edits, how to run the calculation, and how to get commonly-used elements of the results, are covered in this article.

On this page

Creating a Pandeia observation requires a configuration dictionary, which is most easily created with either the build_default_calc function, or by importing a JSON file created by the JWST ETC web UI. Running a Pandeia calculation is relatively straightforward, and obtaining useful information (e.g., observation time, signal to noise, or saturation) from the calculation results is also relatively easy. Whilst there are more advanced operations that can be performed with Pandeia via Python, a significant number of useful operations can be performed just by editing the default configuration.

Pandeia configuration files

Creating a Pandeia configuration dictionary

Importing a JSON configuration file from JWST ETC web UI

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

When running the JWST ETC web UI, at the bottom right of the page (when a calculation is selected) is a tabbed interface containing the option Downloads. From this, it is possible to download your calculation result as a gzipped tar file. Inside the results is a file named "input.json", which contains the calculation parameters that were used in the calculation you prepared. It is possible to create a configuration dictionary from this file with the following Python code (assuming that Python is running in the directory containing "input.json"):

Importing JWST ETC Configuration JSON

import json
with open('input.json', 'r') as inf:
    calculation = json.loads(inf.read())

Once you have done this, calculation is a standard Python dictionary of key-value pairs that you can change as you would for any other Python dictionary (see examples below).

Creating a default configuration dictionary

You can create a Pandeia configuration dictionary by running the built-in Pandeia convenience function build_default_calc. In order to do so, enter the following commands whilst running Python from within your Pandeia environment:

Creating Default Pandeia Configuration

from pandeia.engine.calc_utils import build_default_calc
calculation = build_default_calc(<telescope>, <instrument>, <mode>)

where "telescope", "instrument", and "mode" are the telescope you are using (here jwst), the instrument (one of nircam, miri, niriss, or nirspec), and the observation mode of interest (see below for a list of modes).

Regardless of the values of "telescope", "instrument", and "mode", the build_default_calc function will create a scene with a single object. That object will be a point source with x and y offsets of zero, and a flat spectrum in f_nu normalized to 2.0 mjy at 0.001 μm. The source will have zero redshift, zero extinction, and no applied emission or absorption lines.

Four instrument modes have multiple possible data reduction strategies. For NIRSpec's IFU mode and MIRI's MRS and MRS TS modes, there are options of ifunodinscene (the default) and ifunodoffscene; for NIRSpec's MOS mode there are options of msafullapphot (the default) and specapphot. These can be set with a 4th method option to build_default_calc, so that it produces a properly configured calculation:

Select Data Reduction Strategy

calculation = build_default_calc("jwst", "nirspec", "mos", method="specapphot")
calculation = build_default_calc("jwst", "miri", "mrs", method="ifunodoffscene")

Editing Pandeia configuration files

Changing the observation filter

Changing Observation Filter

calculation['configuration']['instrument']['filter'] = <filter>

filter is the filter you wish to use (see below for a full list).

Changing the disperser

Changing Observation Disperser

calculation['configuration']['instrument']['disperser'] = <disperser>
calculation['configuration']['instrument']['filter'] = <matching_filter>

disperser is one of the available dispersers (see below), and <matching_filter> the filter that goes along with it (again, see below).

Changing the scene

Changing Scene

scene = {<dictionary_designing_scene>}
calculation['scene'][0] = scene

The scene in the configuration is a list of all the sources in the calculation. There are a number of examples of creating scene dictionaries below.

Running Pandeia

Once you have a configuration dictionary, running a Pandeia calculation on that dictionary may be done as follows:

Running Pandeia

from pandeia.engine.perform_calculation import perform_calculation
report = perform_calculation(calculation)

Pandeia calculation results

When run using its default parameters, Pandeia returns a Python dictionary reporting on the results of the simulation. Amongst the useful contents of this dictionary are:

"report['warnings']" contains any warnings generated by the calculation
"report['input']" contains a copy of the configuration dictionary (which may be useful)
"report['scalar']" contains
- The exposure time in "report['scalar']['exposure_time']"
- The signal-to-noise ratio in "report['scalar']['sn']"
- The extracted flux in "report['scalar']['extracted_flux']"
- The extracted background counts in "report['scalar']['background']"

Appendices

Observing modes

MIRI

- coronagraphy - coronagraphic imaging
- imaging - imaging
- imaging_ts - imaging time series
- lrsslit - low resolution spectroscopy (LRS) slit
- lrsslitless - low resolution spectroscopy (LRS) slitless, a time-series mode
- mrs - medium resolution spectroscopy (MRS)
- mrs_ts - MRS time series
- target_acq - target acquisition
- wfss - wide field slitless spectroscopy

NIRCam
- coronagraphy - coronagraphic imaging
- lw_imaging - long wavelength imaging
- lw_ts - long wavelength time-series imaging
- lw_tsgrism - long wavelength time-series grism
- sw_imaging - short wavelength imaging
- sw_ts - short wavelength time-series imaging
- sw_tsgrism - short wavelength time-series grism
- wfgrism - wide field slitless spectroscopy
- target_acq - target acquisition

NIRISS
- imaging - imaging
- soss - single object slitless spectroscopy
- wfss - wide field slitless spectroscopy
- ami - AMI
- target_acq - target acquisition

NIRSpec
- mos - multi-object spectroscopy
- mos_conf - multi-object spectroscopy confirmation imaging
- mos_ver - multi-object spectroscopy verification imaging
- fixed_slit - fixed slit
- bots - bright object time series
- ifu - integral field unit
- ifu_ver - IFU verification imaging
- target_acq - target acquisition

Observation filters

MIRI
- Coronagraphic
  - F1065C
  - F1140C
  - F1550C
  - F2300C
- Imaging
  - F560W
  - F770W
  - F1000W
  - F1130W
  - F1280W
  - F1500W
  - F1800W
  - F2100W
  - F2550W
  - FND
  - F1065C
  - F1140C
  - F1550C
  - F2300C

NIRCam
- Short Wavelength
  - F070W
  - F090W
  - F115W
  - F140M
  - F150W
  - F150W2
  - F162M
  - F164N
  - F182M
  - F187N
  - F200W
  - F210M
  - F212N
  - F212N2 (with WLP4 lens only)
- Long Wavelength
  - F250M
  - F277W
  - F300M
  - F322W2
  - F323N
  - F335M
  - F356W
  - F360M
  - F405N
  - F410M
  - F430M
  - F444W
  - F460M
  - F466N
  - F470N
  - F480M

NIRISS
- F090W
- F115W
- F140M
- F150W
- F158M
- F200W
- F277W
- F356W
- F380M
- F430M
- F444W
- F480M

NIRSpec
- F110W
- F140X

Dispersers and associated filters

NIRCam
- GRISMC/GRISMR
  - F250M
  - F277W
  - F300M
  - F322W2
  - F335M
  - F356W
  - F360M
  - F410M
  - F430M
  - F444W
  - F460M
  - F480M

NIRISS
- GR150R/GR150C
  - F090W
  - F115W
  - F140M
  - F150W
  - F158M
  - F200W
- GR700XD
  - F277W

NIRSpec
- G140H
  - F070LP
  - F100LP
- G140M
  - F070LP
  - F100LP
- G235H
  - F170LP
- G235M
  - F170LP
- G395H
  - F290LP
- G395M
  - F290LP
- PRISM
  - CLEAR

Sample code

Creating a Scene with a centered flat spectrum point source normalized to 2 mJy at 2.5 μm

Scene: Flat Spectrum

# The following section is only needed if the PYSYN_CDBS environment variable is not already set.
# The PYSYN_CDBS environment variable should point to the path of the CDBS data files
import os
location_of_cdbs = "/path/to/cdbs/files"
os.environ['PYSYN_CDBS'] = location_of_cdbs
# End section

# The following section is only needed if the pandeia_refdata environment variable is not already set
# The pandeia_refdata environment variable should point to the path of the pandeia reference data
import os
location_of_pandeia_refdata = "/path/to/pandeia/refdata"
os.environ['pandeia_refdata'] = location_of_pandeia_refdata
# End section

from pandeia.engine.calc_utils import build_default_calc

configuration = build_default_calc('jwst', 'nircam', 'sw_imaging')
scene = configuration["scene"][0]
scene['position'] = {'x_offset': 0., 'y_offset': 0., 'orientation': 0., 'position_parameters': ['x_offset', 'y_offset', 'orientation']}
scene['shape'] = {'geometry': 'point'}
scene['spectrum'] = {'name': 'Flat Source', 'spectrum_parameters': ['sed', 'normalization']}
scene['spectrum']['sed'] = {'sed_type': 'flat', 'unit': 'flam'}
scene['spectrum']['normalization'] = {'type': 'at_lambda', 'norm_wave': 2.5, 'norm_waveunit': 'um', 'norm_flux': 2., 'norm_fluxunit': 'mjy'}
configuration['scene'][0] = scene

Note that the supplied instrument and mode are examples intended for illustration only.

Creating a Scene with a 50,000 K blackbody spectrum Gaussian extended source

Scene: Gaussian Extended Blackbody

# The following section is only needed if the PYSYN_CDBS environment variable is not already set.
# The PYSYN_CDBS environment variable should point to the path of the CDBS data files
import os
location_of_cdbs = "/path/to/cdbs/files"
os.environ['PYSYN_CDBS'] = location_of_cdbs
# End section

# The following section is only needed if the pandeia_refdata environment variable is not already set
# The pandeia_refdata environment variable should point to the path of the pandeia reference data
import os
location_of_pandeia_refdata = "/path/to/pandeia/refdata"
os.environ['pandeia_refdata'] = location_of_pandeia_refdata
# End section

from pandeia.engine.calc_utils import build_default_calc

configuration = build_default_calc('jwst', 'nircam', 'sw_imaging')
scene = {}
scene['position'] = {'x_offset': 0., 'y_offset': 0., 'orientation': 0., 'position_parameters': ['x_offset', 'y_offset', 'orientation']}
scene['shape'] = {'geometry': 'gaussian2d', 'major': 3.5, 'minor': 1.5, 'norm_method': 'integ_infinity', 'surf_area_units': None} #major and minor in arcseconds
scene['spectrum'] = {'name': 'Blackbody Source', 'spectrum_parameters': ['sed', 'normalization']}
scene['spectrum']['sed'] = {'sed_type': 'blackbody', 'temp': 50000.}
scene['spectrum']['normalization'] = {'type': 'photsys', 'bandpass': 'bessell,j', 'norm_flux': 20., 'norm_fluxunit': 'abmag'}
scene['spectrum']['lines'] = []
scene['spectrum']['extinction'] = {'bandpass': 'j', 'law': 'mw_rv_31', 'unit': 'mag', 'value': 0}
configuration['scene'][0] = scene

Note that, again, the supplied instrument and mode are intended for illustration only.

Creating and observing a scene with Pandeia

Full Example

# The following section is only needed if the PYSYN_CDBS environment variable is not already set.
# The PYSYN_CDBS environment variable should point to the path of the CDBS data files
import os
location_of_cdbs = "/path/to/cdbs/files"
os.environ['PYSYN_CDBS'] = location_of_cdbs
# End section

# The following section is only needed if the pandeia_refdata environment variable is not already set
# The pandeia_refdata environment variable should point to the path of the pandeia reference data
import os
location_of_pandeia_refdata = "/path/to/pandeia/refdata"
os.environ['pandeia_refdata'] = location_of_pandeia_refdata
# End section

from pandeia.engine.calc_utils import build_default_calc
from pandeia.engine.perform_calculation import perform_calculation

configuration = build_default_calc('jwst', 'miri', 'imaging')
scene = {}
scene['position'] = {'x_offset': 0., 'y_offset': 0., 'orientation': 0., 'position_parameters': ['x_offset', 'y_offset', 'orientation']}
scene['shape'] = {'geometry': 'point'}
scene['spectrum'] = {'name': 'Phoenix Spectrum', 'spectrum_parameters': ['sed', 'normalization']}
scene['spectrum']['sed'] = {'sed_type': 'phoenix', 'key': 'g2v'}
scene['spectrum']['normalization'] = {'type': 'jwst', 'bandpass': 'miri,imaging,f560w', 'norm_flux': 2., 'norm_fluxunit': 'mjy'}
scene['spectrum']['lines'] = []
scene['spectrum']['extinction'] = {'bandpass': 'j', 'law': 'mw_rv_31', 'unit': 'mag', 'value': 0}
configuration['scene'][0] = scene
configuration['configuration']['instrument']['filter'] = 'f1000w'

report = perform_calculation(configuration)
print(report['scalar']['sn'])

The resulting SNR (to three decimal places) is 2032.883

Notable updates	01 Aug 2025 Updated available modes and examples for ETC 5.0. 01 Aug 2024 Updated examples for ETC 4.0.
Originally published	02 May 2018

JWST User Documentation

Pandeia Quickstart