NIRISS WFSS Recommended Strategies

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

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 Dithers

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). 

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 two 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. 

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.

Beware the imprint of occulting spots 

The NIRISS pick-off mirror has 4 coronagraphic occulters engraved on its surface which projects circular spots with diameters of 0.58", 0.75", 1.5", and 2.0" (approximately 9, 11, 23, and 31 pixels, respectively) located about 11" from the top of the detector. The projection of the detector on the observing field, and thus the exact location of the spots, depends on the PA_V3 orientation of the spacecraft at the time of observation. The "medium" and "large" dither step sizes are sufficient to move a source over the smaller two spots but not enough to fully cover the larger two spots.  There will be a very small region that is not covered by the "large" four point dither pattern.

Though the risk of a source overlapping one of these spots is relatively small, if there is a particular target of interest in the WFSS field, it may be desirable to position the field center so that the target(s) do not fall within ~11" of the detector edges.

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.

Words in bold italics are buttons 
or parameters in GUI tools. Bold 
style represents GUI menus/
panels & data software packages.

The lengths of the first-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. 

Maximizing and homogenizing fraction of sources with images and first-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 first-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 first-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 first-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, an option to add two additional dithered direct images after each set of dithered grism observations has been implemented as of APT v2020.2 (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 two 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. 

Mitigating effects of bright sources

For a given target position, any bright star with 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 first 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. We recommended the filter-dependent source extraction aperture half-height values listed in Table 2, which are based on the mean 80% encircled energy radii for a point source calculated from a WebbPSF grid. The recommended sky sample region for extracting the background is a start region of 2 times the aperture half-height value and an end region of 4 times the aperture half-height value.

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


Aperture Half-Height














Note: 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.

Designing an efficient science program with multiple blocking filters 

See also: NIRISS Pupil and Filter Wheels

When using both the GR150R and GR150C grisms for observations, grism exposures should be obtained through the same filter before switching to another filter. Overheads are associated with each mechanism move. To design an efficient WFSS observing program, it is recommended to select filters in sequential order in the Pupil Wheel, as illustrated in Figure 2.

Figure 2. Layout of optical elements in the pupil filter and filter wheel

Layout of the NIRISS Pupil Wheel and Filter Wheel

Schematic diagram showing the layout of optical elements in the pupil wheel (left) and filter wheel (right). The GR150R and GR150C grisms in the filter wheel are used in conjunction with blocking filters in the pupil wheel. To design an efficient WFSS observing program, it is recommended to choose filters in the pupil wheel in sequential order when multiple blocking filters are used.


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

Latest updates
    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