Detailed step-by-step instructions are available for filling out the JWST NIRSpec integral field unit (IFU) spectroscopy APT template.

On this page

The NIRSpec integral field unit (IFU) can obtain spatially resolved imaging spectroscopy of a contiguous, extended 3" × 3" area on the sky. To achieve this, the IFU uses specialized optics to reformat the spatial region and direct light to the spectrograph optics, which it shares with the multi-object spectroscopy (MOS) and fixed slits (FS) observing modes. Additional information is available on the IFU hardware and the IFU observing mode pages.

This article describes the preparation of a NIRSpec IFU observation using the Astronomer's Proposal Tool NIRSpec IFU template.

Step-by-step APT instructions

We assume the observer has already a defined target(s) to be observed, created an observation folder, and loaded the NIRSpec IFU observation template. Instructions for doing this are presented in the JWST Astronomers Proposal Tool.

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

The IFU template can be divided into 4 sections, as shown in Figure 1.

Section 1: This section shows that the NIRSpec IFU spectroscopy template has been selected, along with a target that was previously defined by the user.
Section 2: The area contains parameters that are for the proposer's information. The observer cannot edit this section.
Section 3: In this section, the observer enters the target acquisition parameters.
Section 4: In this section, the user defines the science parameters that determine the specifics of the observation.

Sections 3 and 4 are under the NIRSpec IFU Spectroscopy tab. There are 3 additional tabs: Mosaic Properties, Special Requirements, and Comments, which are discussed at the end of this article.

The NIRSpec IFU spectroscopy APT template showing the four sections described in this article.

IFU template tabs

Different sets of parameters are available when the following tabs (between sections 2 and 3) are selected: NIRSpec IFU Spectroscopy shows target acquisition and science observation parameters for the IFU. Mosaic Properties displays parameters required for mosaics. Special Requirements are used to place constraints on the observations, and Comments are for observing notes.

IFU template section 1: Generic tabs and parameters

The following parameters are generic to all templates, and are not discussed in this article: Observation Number, Observation Label, Target Name, and ETC Workbook Calculation ID (ETC Wkbk. Calc ID).

IFU template section 2: Observation information

The following is included for information only and is generic to all templates. The article APT Observations contains more detailed information on the topics Visit Splitting, Duration (secs), and Data volume.

IFU template section 3: Target acquisition parameters

Section 3 in Figure 1 corresponds to the Target Acquisition Parameters (TA).

For NIRSpec IFU observations, there are 4 options for TA Method: MSA target acquisition (called MSATA), the wide aperture target acquisition (WATA), VERIFY_ONLY, and NONE. The default option for this template is WATA.

Two of the options, WATA and MSATA, perform a target acquisition sequence of imaging and centroiding to make pointing corrections which will result in the science source centered in the science aperture. WATA centers the TA target in the wide aperture to determine a pointing correction to place the science target in the science aperture. MSATA uses reference stars in the MSA to determine the pointing correction. The remaining two TA Method options, NONE and VERIFY_ONLY, forego target acquisition altogether and rely on the pointing accuracy delivered by the guide star acquisition.

A complete description of the target acquisition procedures used to point the telescope with different JWST NIRSpec observing modes are addressed in the NIRSpec Target Acquisition article.

WATA

When selecting WATA as the TA Method, Section 3 will look like Figure 2. A detailed description of this TA method is found in the NIRSpec Wide Aperture Target Acquisition article. WATA can be performed with either the science target (Same Target as Observation) or an offset reference star. WATA is the preferred method for TA acquisition when the science requires improved pointing compared to the telescope blind pointing accuracy, but it is typically not necessary for most observations unless there are objects of interest at the edge of the IFU aperture or a large nodding pattern is employed for point source observations.

The WATA procedure first places the acquisition target in the S1600A1 aperture and centers it with onboard software. If the acquisition target is an offset reference star, the telescope will subsequently slew to the location of the science target. This method is appropriate only for targets that are point sources or close to point sources. Typical suggested coordinate accuracies for both the science target and acquisition target are on the order of 100 milliarcsec. Observers can define 4 target acquisition parameters in the IFU APT template: Acq Target, Acq Subarray, AcqFilter, and Acq Readout Pattern. The choice of subarray, filter and readout pattern affect TA sensitivity and saturation limit. The options for the subarray are SUB32, SUB2048, and FULL. The options for AcqFilter are F110W, F140X, and CLEAR. Detailed information on these filters can be found in the article NIRSpec Dispersers and Filters. The available readout patterns are NRSRAPIDD6, and NRSRAPID which define the TA exposure time. Further information on these options can be found in the article NIRSpec Detector Readout Modes and Patterns.

A section of the NIRSpec IFU spectroscopy template showing the **Target Acquisition Parameters** using the **WATA** method.

MSATA

When selecting the MSATA option as the TA Method, the target acquisition parameters will be specified at the visit level. MSATA uses reference stars to accurately correct the pointing. MSATA is the preferred TA method for MOS observations. Because of its complexity and scheduling constraints, MSATA is generally not recommended for IFU observations unless WATA is infeasible.

Observers do not need to define reference stars in order to propose for NIRSpec IFU science. That can be deferred until the final program update. The planning parameters will be specified for accepted programs after the MSA-based target acquisition is assigned an aperture position angle by the long range planning system. A detailed description of the MSATA TA mode is available in the NIRSpec MSA Target Acquisition article.

VERIFY_ONLY

The NIRSpec VERIFY_ONLY method relies only on guide star acquisition performed by the Fine Guidance Sensor (FGS) to derive a telescope pointing, and does not actually perform NIRSpec target acquistion. This method is suitable when the telescope blind pointing accuracy is sufficient and a pointing verification image is desired. The precision of this method is limited by the JWST observatory pointing accuracy. In many cases, pointing verification is not necessary and an image of the IFU field can instead be constructed from the IFU science data.

When selecting VERIFY_ONLY as the TA Method, Section 3 looks like Figure 3.

A section of the NIRSpec IFU spectroscopy template showing the **Target Acquisition Parameters** using the **Verify_Only** method.

VERIFY_ONLY will obtain an image to verify the pointing during post-analysis. The image, obtained with NIRSpec’s imaging mirror, will provide knowledge of the exact pointing so that it can be aligned with other images and/or data of the field. Under the TA Method VERIFY_ONLY, the proposer needs to define a filter for the Pointing Verification Image. The options are NIRSpec filters F140X, F110W, and CLEAR, as shown in Figure 4. The PV Readout Pattern options for this verification image are NRS, NRSRAPID, NRSIRS2, and NRSIRS2RAPID, which are described in further detail in the NIRSpec Detector Readout Modes and Patterns article. When selected, the Pointing Verification Image is taken at the end of the visit, after all science spectroscopy exposures are completed.

*Click on the figure for a larger view.*
Filter options (left) and **Readout Pattern** (center) for the **Pointing Verification Image**. MSA configuration used to obtain the verification image (right).

By default, the verification image is taken with PV MSA Configuration set to the ALLOPEN configuration and the grating wheel set to MIRROR. The MSA Planning Tool (MPT) can be used to make protected MSA configurations to block shutters on bright targets. The ALLCLOSED shutter configuration option is included. This might not be commonly used, but can be suitable for targets that would saturate in open shutters.

The number of groups, PV Groups/Int for the Pointing Verification Image should be determined using the NIRSpec ETC in single object target acquisition mode with estimates of the brightnesses of sources within the field.

NONE

Like VERIFY_ONLY, selecting NONE as the TA Method relies only on guide star acquisition performed by the Fine Guidance Sensor (FGS) to derive a telescope pointing. Unlike VERIFY_ONLY though, no pointing verification images are taken. NONE is the preferred TA method for IFU observations where the blind pointing accuracy of the telescope is sufficient.

IFU template section 4: science parameters

The Science Parameters are defined in section 4 of the IFU template, as shown in Figure 5. The Science Parameters include the IFU dithering options, and the science exposure specification(s): the spectral configuration used for science and the detector and exposure configuration options to specify the exposure time.

Detail of the NIRSpec IFU spectroscopy template showing the **Science Parameters** section.

Dither parameters and dither type

The user needs to define the Dither Type for the IFU observation. Dithering is always recommended for JWST observations. The dither patterns are pre-determined and the available options in the IFU spectroscopy template are: NONE, 2-POINT-NOD, 4-POINT-NOD, 4-POINT-DITHER, CYCLING, and SPARSE-CYCLING. These options are in a pull-down menu under Dither Type as shown in Figure 6 (left). While the 2-POINT-NOD, 4-POINT-NOD, and 4-POINT-DITHER may be sufficient for some science use cases, a larger number of CYCLING dithers can be beneficial to improve spatial sampling and outlier rejection.

Detail of the IFU template showing options for **Dither Type** (left) and the special menu when **CYCLING** is selected (right).

Note that additional information is required for dither types CYCLING and SPARSE-CYCLING. Figure 6 (Right) shows the case of the CYCLING dither type, where a Size parameter is required with options SMALL, MEDIUM, and LARGE, as well as the Starting Point and the Number of Points. The complete description of each offset pattern is presented in detail in the article NIRSpec IFU Dither and Nod Patterns.

Exposure specification

The Exposure Time Calculator (ETC) should be used to determine the best exposure configuration to optimize the SNR of your observation. An exposure is configured by setting the Grating/Filter combination, Readout Pattern, Groups per Integration, and Integrations per exposure.

Users should ultimately use the Exposure Time Calculator for all sensitivity calculations.

Recommendations about exposure parameter selection are given in NIRSpec Detector Recommended Strategies.

An exposure specification is created by using the Add button located at the bottom of section 4 of the IFU template as shown in Figure 5. Each line in this field represents a set of exposures acquired with the defined dither option (e.g., a dither option of NONE will result in one exposure, a 4-POINT dither will result in 4 exposures). The required exposure parameters are listed in Table 1.

Table 1. Description of Science Parameters for a given exposure specification.

Exposure Parameter	Description
Grating/Filter	Select a Grating/Filter combination from the pull-down menu. The article NIRSpec Dispersers and Filters describes all the available combinations for NIRSpec.
Readout Pattern	The default value is NRS, but the available values are NRS, NRSRAPID, NRSIRS2, and NRSIRS2RAPID. These patterns are described in full detail in NIRSpec Detector Readout Patterns. Select the pattern that best suits your observation.
Groups/Int	The number of groups during an integration, where a group is the product of reading the detectors with a specific readout pattern.
Integrations/Exp	This represents the number of Integrations during an exposure, where integration is defined as the time between resets.
Leakcal	These IFU leakage calibrations can be acquired to mitigate the effects of excess MSA flux from open shutters or leakage. A leakage exposure is specified by duplicating the exposure specification for which a leakcal is needed and clicking the Leakcal checkbox on the resulting exposure line. Dithers may be changed for a leakage exposure specification by clicking on the Dither checkbox and specifying the Dither Type option from the Dither Parameter dropdown.
Autocal	This option is available to automatically add calibration exposures to a science exposure. For the IFU template, the only options are NONE or WAVECAL. NONE is the default and is recommended because Autocals can add significant overhead to an observation. Existing NIRSpec calibrations are usually sufficient for science observations, so this option should only used for special use cases that require custom calibration observations.

A IFU leakage calibration exposure can be specified by duplicating an exposure by highlighting the exposure to be duplicated and clicking the Duplicate button. Then the Leakcal checkbox can be checked, as shown in Figure 7. The leakage exposure can use dithering in the same manner as the exposure to which it will be applied, but this is not a requirement.

*Click on the figure for a larger view.*
IFU Leakcal can be entered into the **Science Parameter** section by duplicating an exposure using the **Duplicate** button and then checking the **Leakcal** checkbox. The leakage exposure is highlighted in the figure. The **Dither** checkbox has not been checked, and will therefore produce only one of the 4 dithered exposures of the science exposure. Clicking the **Dither** checkbox will replicate the specified **Dither Type** of the science exposures.

Other tabs

Mosaics

NIRSpec's IFU may be used to obtain data for a region larger than its 3 × 3 arcsec size by creating a mosaic pattern. The use of APT's mosaic tool is described in the article NIRSpec FS and IFU Mosaic APT Guide.

Special Requirements

A variety of observatory level Special Requirements may additionally be specified.

Comments

The Comments field should be used only to record observing notes. They will become part of the APT file and therefore of the submitted proposal.

Notable updates	28 Jun 2024 Added recommendations on when to use each TA type. Added recommendation for more cycling dithers. Added Figure 7 for Leakcal specification in APT. Added text on how to specify Leakcal observations in APT template. 21 Nov 2022 Major updates to latest TA recommendations for WATA and MSATA 16 May 2017 Figure 1 and 4 updated. New Figure 2. Minor updates to Table 1.
Originally published	09 May 2017

JWST User Documentation

NIRSpec IFU Spectroscopy APT Template