NIRISS WFSS Recommended Strategies

Recommendations for crafting a NIRISS wide field slitless spectroscopy (WFSS) observing program are presented. This mode enables low resolution (R ≈ 150) spectroscopy between 0.8–2.2 μm, over the 2.2’ × 2.2’ FOV. 

On this page

See also: NIRISS Wide Field Slitless Spectroscopy, NIRISS WFSS Template APT Guide, NIRISS WFSS Science Use Case, NIRISS GR150 Grisms, NIRISS Filters, NIRISS WFSS Dithers

The wide field slitless spectroscopy (WFSS) mode of NIRISS enables low resolution (R ≈ 150) spectroscopy over the wavelength range 0.8–2.2 μm for all objects within the 2.2’ × 2.2’ field of view (FOV) of the NIRISS detectorThe WFSS mode uses a pair of identical grisms (GR150R and GR150C) that are mounted in the filter wheel so that their respective dispersion directions are perpendicular to each other on the detector. Data acquired with both dispersion directions helps to disentangle blended spectra in crowded fields.

WFSS observations are obtained by using one or both of the grisms in combination with a wide- or medium-band blocking filter located in the pupil wheel (PW). The blocking filters limit the wavelength coverage and therefore the extent of spectra on the detector, which reduces the blending of spectral traces from objects distributed throughout the FOV. A direct image is taken before and after each grism exposure.

Since the NIRISS point spread function (PSF) is undersampled at the wavelengths covered by the WFSS mode, dithering is essential. Dithering also helps remove detector artifacts and cosmic rays.

Advice is offered below to guide the user in choosing observing parameters and to discuss considerations that impact a WFSS program.

Recommended dither size and number of dither steps 

See also: NIRISS WFSS DithersNIRISS Ghosts

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

The selection of dither patterns for WFSS is done by specifying 2 parameters:

  1. Dither size (or amplitude): SMALL (~0.3"), MEDIUM ( ~0.6"), or LARGE (~1.2"). 

  2. Number of dithers: 2, 3, 4, 6, 8, 12, or 16 steps. In case NIRISS WFSS is used as the prime instrument mode in a coordinated parallel combination, there are additional custom dither patterns available with 2, 3, 4, or 9 steps. (The latter patterns are recommended for science cases where achieving optimal pixel phase sampling is important for both the prime and parallel instrument modes.) In all cases, the first dither step corresponds to the initial pointing.

As to the dither size parameter (#1 above), consider that smaller dither amplitudes yield the benefit of higher conservation of pixel phase sampling across the detector (due to varying geometric distortion), while larger dither amplitudes allow one to step over larger targets and hence offer a better mitigation of flat fielding errors for astronomical scenes involving such targets. The user should choose the best compromise for a given science case. The MEDIUM patterns (the default choice in the APT template for the WFSS mode) was chosen to be appropriate for extragalactic studies at moderate-to-high redshift. The SMALL patterns are useful for sparse fields of compact sources, while the LARGE patterns should be useful for observing astronomical scenes involving relatively large objects (e.g., galaxies at relatively low redshift).

If the target field is expected to have a large number of bright sources, ghosts from the sources could potentially impact data quality. In this case, a LARGE dither step size may be preferable to help remove ghosts in the final combined spectral product.

As to the selection of the number of dithers, the following questions are relevant to consider:

  1. Efficiency considerations. If the science goals require rather long exposure times with the grisms (e.g., ≥ 10,000 s per filter) whereas that is not the case for the associated direct images, it makes sense to split up the total exposure time per filter into several dithered exposures, since each WFSS exposure specification in APT produces 2 direct images (one at the first dither and one at the last dither position). 

  2. PSF sampling vs. depth considerations. Science programs whose main aim is to achieve the best possible astrometric and photometric precision in the output image (especially for strongly undersampled images) will prefer to have several dither positions, so that each object will be placed at a wide variety of locations with respect to the pixel grid. On the other hand, users mostly interested in reaching the maximum photometric depth within a relatively short time may prefer fewer dithers, so that individual exposures will reach as deep as possible for a given total exposure time.  Many programs, of course, will seek to compromise between those two extremes. As an aid in making such decisions, Figure 1 depicts measures of the relative quality of combined images for the different WFSS filters as function of the number of dithers, from simulated data. Note that for practical purposes, the main benefit of executing more than 8–9 dithers in WFSS mode is observing efficiency (cf. item #1 above) rather than photometric or astrometric quality. 

Four is the minimum number of recommended dither steps to mitigate detector artifacts, cosmic ray hits, and improve PSF sampling, though fewer steps should be considered if 4 dithers increases the exposure time too much or results in integration ramps with NGroups ≤ 3. More detailed advice and metrics for selecting the most appropriate dither pattern for a particular science goal is given in the report NIRISS Dither Patterns for the WFSS and Imaging Observing modes.

Finally, NIRISS WFSS can also be used in coordinated parallel mode, both as primary and as parallel instrument. When this is done, additional customized dither patterns become available through the primary instrument's APT template. These customized dither patterns have been designed to work well for both the primary and the selected parallel instrument mode.  

Figure 1. Quality metrics for photometry and astrometry with the NIRISS WFSS filters

The first column of panels shows the measured PSF FWHM relative to the FWHM that a critically sampled image would have at the central wavelength of the filter in question (which is mentioned on the left side of each row of panels). The second and third columns of panels show the standard deviations (across the FOV) of the measured centroid positions (in pix) and the photometry (in mag), respectively, relative to the known (input) values. Source: technical report NIRISS Dither Patterns for the WFSS and Imaging Observing modes.

Target density at which both grisms are recommended

See also: MIRAGE JWST Data Simulator

It is not possible to provide rigorous general guidelines for source crowding in WFSS observations because whether overlap will occur depends on source sizes, the source distribution in the field of view, the filter to be used, and the on-sky rotation angle at the time the observations are to be taken. The best way to estimate crowding is to simulate the WFSS spectra using MIRAGE for a range of field rotations to see which orientations may cause problems for the science targets. However, some general comments about crowding can be made.

The lengths of the 1st order grism spectra correspond to angular intervals that range from 2.6" for the F140M filter to 7.9" for the F200W filter. For any given target of interest, if there are several nearby sources that are of similar brightness (say at least 10% as bright as the target under consideration) within a radius of 4" then the overlap of different spectra is likely to occur. In such circumstances, use of both grisms is recommended. When spectral traces are longer, probability of overlap is higher, and the density at which one needs to be concerned about possible overlap is somewhat lower than this estimate: having several sources within a radius of 8" indicates that use of both grisms should be considered.

To efficiently set up an observation that uses both grisms for a chosen filter in the NIRISS WFSS observation template in the Astronomer's Proposal Tool (APT), users can select the option BOTH for parameter Grism. This option is described in more detail in the next section. 

Grism options when using only one grism

See also: NIRISS GR150 Grisms

When only using one grism for a science program, please note that the throughput for the GR150C grism in the first order is enhanced compared with the GR150R grism. Choosing the GR150C grism may be preferable for a deeper observation.

Maximizing and homogenizing fraction of sources with images and  1st order spectra within FOV

Because WFSS spectra are extended along the dispersion axis and offset from the target position in the direct image, complete spectra across the entire filter bandpass will only be available within a fraction of the full NIRISS FOV, and that fraction depends on the filter used. Specifically, for a given telescope pointing, that fraction decreases with increasing wavelength (see fractions in Table 1 below).  

Table 1.  Fraction of sources in NIRISS imaging FOV with full  1st order WFSS spectra


Fraction with spectra, one grism

Fraction with spectra, both grisms

To create a setup in which the fraction of the NIRISS FOV with complete 1st order spectra is maximized and approximately the same from one filter to another, it is recommended to select the option Grism = BOTH in the Astronomer's Proposal Tool (APT) template for NIRISS WFSS. In that setup, the initial telescope pointing for a given WFSS exposure sequence depends on the grism and filter being used, resulting in a situation in which a significant fraction of the sources whose 1st order spectra with the GR150R grism are captured on the detector without direct image coverage (such sources are sometimes called "out-of-field" sources) is covered by the direct images in the exposure sequence with the GR150C grism, and vice versa. This Grism = BOTH option yields a fraction of sources with direct images and spectra within the NIRISS FOV of 89%, which constitutes a significant increase for the F200W filter. As such, this option is mainly beneficial for WFSS observations that include exposures with the F200W filter. 

However, it should also be noted that by default, the sources in that additional 13% of the FOV (for the case of F200W) will only receive half of the direct image exposure depth (i.e., 2 exposures rather than 4). To address that issue, users have the option to add 2 additional dithered direct images after each set of dithered grism observations(i.e., the Two Extra Dithers parameter, see NIRISS WFSS Observation Template). This option should be considered if one wishes to obtain at least 4 dithered direct imaging exposures across the full 89% of the NIRISS FOV in the Grism = BOTH case.

The filter-dependent telescope offsets described above are not applied for options Grism = GR150R or Grism = GR150C in the APT template. The initial telescope pointing for those 2 cases are offset from each other by (Δx, Δy) = (8.0, 4.5) pixels in order to yield improved pixel phase sampling when combining direct images from the GR150R and GR150C exposure sequences of a given target field. 

Minimizing contamination from spectral overlap

There may be cases where a particular source of interest is targeted within a WFSS field and a user may want to minimize contamination of this spectrum from overlapping spectra of nearby sources. Specific position angles may mitigate such contamination. The NIRISS grism overlap tool can be used to examine a NIRISS WFSS scene at different orientations to identify which orient ranges may be less affected by spectral overlap.

Mitigating effects of bright sources

For a given target position, any bright star within a radius of about 1.6 arcminutes may be within the field of view for some orientations of JWST. Stars brighter than about 10.5 (Vega) in J-band or about 9 (Vega) in K-band will produce strong saturated GR150 spectra even for the first frame of an observation. Any such stars within 1.6 arcminutes of the center of the field of view will produce saturated spectra in the dispersed images. Even if such a star is slightly outside the imaging field of view for a given orientation, it may produce a spectrum if it is within about 9" of the edge of the imaging field. If a star is very bright even the higher spectral orders may be visible in the spectral images. For the 1st order spectra, only stars just above the edge of the imaging field or stars just to the right of the imaging field can produce spectra for the GR150R and GR150C grisms, respectively. If a star that is brighter than the limits given above is within the field of view or close to the edge of the field of view, the user may need to restrict the roll angle of the observation to avoid seeing the spectra from the bright star. In some cases, a small offset of the target position may also be used to avoid this type of problem, in those cases where the field is at low ecliptic latitude and thus the range of roll angles is restricted.

Recommended aperture strategy choices for Exposure Time Calculator

See also: JWST ETC Aperture Spectral Extraction StrategyNIRISS Filters

The Exposure Time Calculator (ETC) is used to calculate signal-to-noise ratios (SNRs) for an observation based on input exposure parameters. When determining exposure parameters in the ETC, users can select the aperture radius from which the flux is extracted and the background subtraction method. The filter-dependent source extraction aperture full-height values listed in Table 2 are recommended, which are twice the measured value for the 80% encircled energy radii for a point source. It is also recommended that the source aperture extraction full-height width be kept under 4". The recommended sky sample region for extracting the background is a start region of 2 times the aperture full-height value and an end region of 4 times the aperture full-height value.

Table 2. Recommended aperture full-height values for point sources to use for the ETC


Aperture Full-Height














: These extraction values are for point sources. If the source is extended, it is up to the user to define the region of interest for calculating the SNR.  It is also up to the user to ensure that other sources from the ETC scene are not included in the background extraction area, unless this effect is intended.

Update aperture location to center target of interest

See also: APT Special Requirements

WFSS observations are usually designed to observe a field of interest, but there may be times where a particular source is the target of an observation. If so, entering an OFFSET special requirement with values (X, Y) = (-6.310,-0.663) in APT is recommended to position the target at a "clean" location of the detector. In this case, the RA and Dec entered into APT should be the coordinates of the target of interest.


Goudfrooij, P., 2015, JWST-STScI-004466
NIRISS Dither Patterns for the WFSS and Imaging Observing modes


MIRAGE Read the Docs

NIRISS Grism Overlap Tool

Latest updates
    Updated for Cycle 2

    Added sentences in the paragraph after Table 1 to explain the optional two extra dithers for direct images that were implemented in APT 2020.2.

    Replaced prior section "Ensuring that all dispersed spectra are captured on FOV" by new section "Maximizing and homogenizing fraction of sources with images and first-order spectra within FOV"
Originally published