Step-by-Step PandExo Guide for NIRISS SOSS Time-Series Observations of HAT-P-1

A walk through of the JWST PandExo (Pandeia-ETC for Exoplanets) for the NIRISS SOSS Example Science Program is provided, demonstrating how to select exposure parameters for this observing program.

On this page

Main articles: NIRISS Single Object Slitless Spectroscopy, NIRISS SOSS Recommended Strategies
See also: JWST ETC Residual Flat Field Errors

PandExo is the "ETC ('Pandeia') for Exoplanets" which performs signal-to-noise (SNR) calculations for the JWST time series observing modes. The calculations from the JWST Exposure Time Calculator (ETC, which uses "Pandeia") are considered to be conservative (and averaged over wavelengths) SNR estimates for the exoplanet transit/eclipse depths or brown dwarf rotation amplitudes.

The ETC includes an error term for residual flat field errors which affects long exposures, and significantly underestimates the SNR for exoplanet transit spectroscopy where we take relative measurements. For exposures longer than ~10,000 s, ETC calculations have a "noise floor" above which an increase in exposure time no longer results in an increase in SNR that scales with the square root of the exposure time. Since we are making relative measurements on the same pixels for exoplanet transit spectroscopy, our precision is not affected by the "noise floor" imposed by the residual flat field errors. The Step-by-Step ETC Guide for NIRISS SOSS Time-Series Observations of HAT-P-1 provides a conservative, average estimate, but using the JWST ETC to compute a full exposure with ~2000 integrations is not possible for time series observations (TSOs).

For the "NIRISS SOSS Time-Series Observations of HAT-P-1" Example Science Program, we focus on selecting stellar, planetary, and exposure parameters to detect the exoplanet transit at the desired signal-to-noise ratio (SNR), for each wavelength. We start by defining the stellar, planetary, observational, and instrument modes specific to the proposal observations. The result of these calculations will be both the expected SNR on the host star and exoplanetary atmospheres, as well as necessary parameters to input into the Astronomer's Proposal Tool (APT) observation template, which is used to specify an observing program and submit proposals.

Observing goals of time series observations

Main articles: JWST Time-Series Observations, NIRISS-Specific Time-Series Observations
See also: Noise Sources for Time-Series Observations

    MultiExcerpt named 'tso_snr_soss_hatp1' was not found
The page: Step-by-Step ETC Guide for NIRISS SOSS Time-Series Observations of HAT-P-1 was found, but the multiexcerpt named 'tso_snr_soss_hatp1' was not found. Please check/update the page name used in the 'multiexcerpt-include macro.

Opening PandExo

After opening the PandExo website, select "New Calculation" under the picture of "James Webb Space Telescope".

Figure 1. PandExo website landing page

Select "New Calculation" in the "James Webb Space Telescope" pane to begin PandExo SNR calculations.

At the top of the next page, it is useful to set the name of the target in the "Name" text box. This will become relevant on the next page, which will have a list of all recent calculations from the current computer. 

Setting stellar parameters in PandExo

The set the stellar parameters for HAT-P-1, we will use is the "Phoenix Model Grid," setting:

  • Steller temperature to 6251 K 
  • Stellar metallicity to 0.146 ([Fe/H])
  • Stellar log g to 4.36 (dex)
  • Magnitude to 8.858 – set to K magnitude on drop down menu.

Figure 2 shows a screenshot of the stellar parameters input page in PandExo.

Figure 2. Defining stellar properties for HAT-P-1 in the JWST PandExo

Nominal input stellar parameters for PandExo to make an accurate prediction for observing HAT-P-1 with JWST NIRISS SOSS.

Setting planetary parameters in PandExo

To supply the exoplanetary parameters for HAT-P-1b, we will use the "Select From Grid" under "Planet Model" option, setting:

  • Temperature (K) to 1250 K (The equilibrium temperature for HAT-P-1b is 1351 K)
  • Select Chemistry Type to Equilibrium Chemistry
  • Clouds or Scattering to Weak Rayleigh
  • Planet Mass to 0.529 MJ (relative to Jupiter mass)
  • Planet Radius to 1.319 RJ (relative to Jupiter radius)
  • Stellar Radius to 1.123 RS (relative to Solar radius)

Figure 3 shows a screenshot of the planetary parameters input page in PandExo.

Figure 3. Planetary bulk and atmospheric properties

Nominal input planetary parameters for PandExo to make an accurate prediction for observing HAT-P-1 with JWST NIRISS SOSS.

Setting transit observational parameters in PandExo

We need to supply the observational parameters for HAT-P-1b and encompass the entire transit and necessary out of transit time to make the relative measurement. For this, we need to set the following parameters (Figure 4):

  • Transit Duration to 10,002 s
  • Baseline to 33,668 s (3 × transit duration + 1 hour for detector settling)
  • Number of Transit` to 1 (the default)

Figure 4. Observational parameters for the HAT-P-1 transit

Nominal input observational parameters for PandExo to make an accurate prediction for observing HAT-P-1 with JWST NIRISS SOSS.

Set instrument (SOSS) parameters in PandExo

To supply the instrumetnal parameters for NIRISS SOSS, we will select the NIRISS SOSS option and sub-array selections as follows (Figure 5)

  • Instrument to NIRISS Single Object Slitess Spectroscopy
  • Mode to Substrip 256 (because it provides more pixels to estimate background)
  • Number of Groups per Integration to optimize (the default: This scans a range of options and selects the one that sustains half the saturation limit)
  • Saturation Limit to 80% Full Well – this helps the optimization algorithim select a number of groups that will sustain 40% (half saturation) well depth or ~35–30k electrons per pixel
  • Noise Floor to 10`ppm – this is most useful with multiple transit/eclipse/rotation observations; it sets the lowest possible uncertainties per wavelength

Figure 5. Observational parameters for the HAT-P-1 transit

Nominal input detector parameters for PandExo to make an accurate prediction for observing HAT-P-1 with JWST NIRISS SOSS.

Run PandExo

To compute all of the necessary – and useful – values for planning and proposing for JWST TSO observations, select the "Submit" button at the end of the page. This operation could take a few minutes. The following page will provide a rotating symbol and the label "Running" if the calculations are ongoing. Moreover, the buttons to the right (a box and an eye) will be grey and unusable.

After the calculation has finished processing on STScI server, the rotating dial will stop and the label "Running" will change to "Finished". Moreover, the buttons to the right are now useful.

Select the EYE symbol (), to view the JWST TSO planning and proposing calculations.

PandExo results

After selecting the EYE symbol , the first image that we can see is the raw, unbinned planetary spectrum as it would be resolved by fitting a transit model (see Kreidberg 2015) to the synthetic JWST-NIRISS simulated observations, which include photon noise, background noise, and read noise as is expected from both Pandeia and field testing of the instruments (Figure 6).

Figure 6. Raw, unbinned planetary spectrum

Synthetic JWST-NIRISS simulated observations from PandExo, which include photon noise, background noise, and read noise.

There are two dials to this plot, as well as the standad Bokeh interaction functions (e.g., move, zoom, etc): "binning" and "Num trans". The units of "binning" selection are given in the log10(min(wavelengths per bin)); the default is at the native resolution for NIRISS (R ~ 700), such that log10 (0.625/700) = -3.049. The scientific measurement for an exoplanet transit is the "transit depth" or "eclipse depth", which is a temporal measurement. The spectroscopic result is therefore a relative comparison between a contiguous sequence of time-series measurement i.e., transit/eclipse depth over wavelength. It is equivalent to measuring variations in the stellar spectrum over time.

The native resolution can provide a useful transmission/emission spectrum, if the atmospheric signal is large enough to overcome the intrinsic, temporal noise, which is dominated by the photon noise and read noise. It is much more common to "bin" the native spectrum into what are called "channels", which are higher SNR sets of pixels that improve the SNR on the temporal signal. In our case, we will bin 10 pixels together to form ~200 "channels" (i.e., 2048 pixels/10 (pixels per bin), which results in a binned resolution of R ~ 70. Sliding the dial to -2.049 (= log10(0.625/70)), is equivalent to binning by 10 pixels per channel. The plot itself will update to reveal what this binning should look like from our synthetic observation. This dial allows the user to visually determine ithe theoretical spectrum (here: clear, equilibrium chemistry) with the precise stellar model for the HAT-P-1 system.

Figure 7 shows a zoom-in of the binned spectrum using the Bokeh tools on the right side of the interactive plot.

1-D stellar and error spectra for HAT-P-1

Scrolling down on this page, we come to the 1-D stellar and error spectra for HAT-P-1. The first tab on the top figure defaults to "Total Flux" (Figure 8), which shows the integrated electrons per wavelength, integrated to form the 1-D stellar spectrum (top) and 2-D spectral image (bottom).

Selecting the SNR tab at the top of the upper figure reveals the SNR expected per wavelength along the stellar spectrum (Figure 9). Because our exoplanet host stars are nominally bright, the stellar spectrum is very nearly photon noise limited; the SNR figure is therefore precisely the √(1-D stellar spectrum) over wavelengths.

Transit/Eclipse depth uncertainty over wavelengths

The final tab to select on this figure is likely the most important. Select the "Error" tab to see the predicted ppm uncertainty as a function of wavelength (Figure 10).

Figure 10 shows that the smallest uncertainty predicted for HAT-P-11 in our observational parameters is ~100 ppm; the average is closer to 200 ppm. This estimate is for the native resolution (R ~ 700); because we are expecting to bin the 2-D image by 10 columns to form 200 channels from 2048 columns, we will state that we predict to achieve 200/√10 ~ 63 ppm uncertainty (on average) across the spectrum. Note that we sought to achieve <50 ppm uncertainty, on average, across the spectrum. To sustain this uncertainty, we would need to bin the spectrum by 16 pixels instead of 10; or observe the target for a second observation. Depending on the spectral resolution desired to detect specific atmospheric molecular signatures, either of these options is viable (see Figure 11).

Figure 11. Observed spectrum with different binnings

Top: Spectrum binned by 16 pixels per channel, which provides an average uncertainty <50 ppm across the spectrum, with 1 visit. Bottom: Spectrum binned by 10 pixels per channel, which provides an average uncertainty of ~63 ppm across the spectrum, with two visits. The error curve for both panels is for the native (i.e., unbinned) resolution.
Figure 11 (top) bins the native spectrum by 16 pixels per channel, with 1 visit. Figure 11 (bottom) bins the native spectrum by 10 pixels per channel, with two visits. Both panels show the "error spectrum" at the native resolution.

Determining number of groups and number of integrations

APT requires the user to enter the number of groups (NGroups) and number of integrations (NIntegrations) to define the length of the exposure. We want to observe a balanced number of groups per integration to maximize both temporal resolution and spectral precision. Previous experience has led the community to nominally fill the detector pixel wells to an average of half full. Because an H2RG pixel can hold ~65k e, we nominally choose ~30k e per pixel per integration. In the context of number of groups for JWST, PandExo derives the number of groups corresponding to the onset of saturation (NGroupssat) (we defined this at 80% well depth), and then selects the number of groups per integration to be NGroupssat/2 (rounding up).

After the "Table of Original Inputs"–which matches the values we entered at the beginning–there is a second table named "Timing Info" (Figure 12).

  1. APT: Num Groups per Integration = 2 
  2. APT: Num Integrations per Occultation = 2048

Both of these values will be entered in the APT NIRISS SOSS Observation template as described in the Step-by-Step APT Guide for NIRISS SOSS Time-Series Observations of HAT-P-1.

PandExo warnings

The final table provided by PandExo is named "Warnings" (Figure 13). If the target is not too bright for the minimum number of groups (NGroupsmin = 2), and the given instrument/detector setup, then all "values" should be listed as "All Good." If the any pixels on the detector are saturated, or experience strong non-linearity, then one of these warnings will list further information. 

  • "Group Number Too Low" warns if the target is too bright for the minimum number of groups.
  • "Group Number Too High" warns if the target is too faint for the maximum number of groups.
  • "Non linear?" warns if any pixels are expected to sustain significant non-linearity, which could happen if the target is not too bright to saturate pixels, but bright enough to sustain non-linearity.
  • "Saturated?" warns if any pixels are expected to be saturated.
  • "% full well high" warns if the definition of full well provided on the previous page is useful to achieve nominal integration parameters.
  • "Num groups Reset" is a catch all warning that warns if the "something else went wrong", which might have required PandExo to reset the number of groups to the minimum value of 2.

Figure 13. Warnings table in PandExo

This final PandExo table warns the user if any problems were encountered in the simulation, as described in the main text. If the simulation ran without any issues, "All good" will be listed in the "Value" column.

Download Data

PandExo provides a "Download Data" button at the bottom of the results page, which allows the user to download a `pickle` file for the user to use Python to plot and interact with all of these figures. The follow code snippet would allow user to create the "Error Spectrum" figure above – with Python 3.6.1 :: Anaconda 4.4.0 (×86_64):

# To plot the error spectrum after downloading the PandExo results

import pickle

from pylab import *; ion()

id = '2a348356-69f9-4a31-826f-5dbcaf075946e' # this `id` only applies for this test case; all users will have a different values for `id`

ppm = 1e6

num_bins_per_channel = 10

with open("ETC-calculation" +id+".p", "rb") as f:

    hatp1 = pickle.load(f)

plot(hatp1['FinalSpectrum']['wave'], hatp1['FinalSpectrum']['error_w_floor']*ppm)

plot(hatp1['FinalSpectrum']['wave'], hatp1['FinalSpectrum']['error_w_floor']*ppm / sqrt(num_bins_per_channel))

# To print the average expected error across the entire spectrum

print(mean(hatp1['FinalSpectrum']['error_w_floor']*ppm / sqrt(num_bins_per_channel))

Target acquisition

Main articles: NIRISS Target Acquisition, JWST ETC NIRISS Target Acquisition

PandExo does not yet comptue expectations for target acquisition (TA). Please see the "Target Acquisition" section of the Step-by-Step ETC Guide for NIRISS SOSS Time-Series Observations of HAT-P-1 for guidance on how to select observing parameters to ensure a successful TA. Note that if a TA does not succeed, the observation can not be performed.


Kreidberg, L. 2015, PASP, 127, 1161
batman: BAsic Transit Model cAlculatioN in Python



Latest updates