NIRSpec Integral Field Unit (IFU) Spectroscopy Template Parameters

fJWST's NIRSpec Integral Field Unit (IFU) Spectroscopy template, available in the Astronomer’s Proposal Tool (APT), has parameters for specifying and scheduling observations.

Introduction

Purple text indicates the parameter is Limited Access.

Boldface italics type indicates the name of an APT parameter or a value for a parameter.

(warning)Red text indicates restrictions on a parameter.

(red star) Black text indicates an important note.

Brown text indicates notes for the developers.

Green text indicates the name of the parameter used by Commanding.

Items in brackets - <value> - are required values.

Items in square brackets - [<value>] - are optional.

The NIRSpec Integral Field Unit (IFU) Spectroscopy template is to be used for all observations using the IFU spectroscopy mode of NIRSpec, and this article describes allowed values for all parameters. The IFU offers either the option of the standard MSA target acquisition, or to simply take an image to verify pointing during post-analysis. Advice on how to choose values which optimize your science can be found in the NIRSpec IFU Spectroscopy APT Template article.

The NIRSpec IFU Spectroscopy template consists of the following parameters:

FieldDetailsValues Notes
General Information   
Observation Numberassign observation number

number



Observation Label provide observation labeltextoptional
Observation Commentsprovide observation commentstextoptional
Target Nameselect Target Namechoose from listfrom Target List

ETC Wkbk. Calc. ID

specify ETC Workbook Calculation IDnumberfor science exposures (optional) and target acquisition exposures
Mosaic Propertiesspecify mosaic parametersnumberif needed
Special Requirementsspecify special requirementschoose from listif needed
Template Specific Information   
Target Acquisition Parameters
Target Acquisition Methodselect target acquisition methodchoose from list
MSA Target Acquisition Exposure
Reference Star Bin

list of reference stars and configuration 

 choose from list
Acquisition Filterfilter name
set based on Reference star bin
Acquisition MSA Configuration Filenamespecify filename
if needed
Acquisition Readout Patternreadout pattern
set based on Reference star bin
WATA Target Acquisition Exposure


Acquisition Targetselect acquisition targetchoose from list
Acquisition Subarrayselect subarraychoose from list
Acquisition Filterselect filterchoose from list
Acquisition Readout Patternselect readout patternchoose from list
Pointing Verification Image
Pointing Verification Image Filterselect filter namechoose from list
Pointing Verification Image Readout Patternselect readout patternchoose from list
Pointing Verification Image Number of Groups/Integrationspecify number of groups per integrationnumber
Pointing Verification Image MSA Configuration Filenamespecify filename
if needed
Science Parameters
Dither Typeselect dither typechoose from listsee Table 1
Pattern Sizespecify pattern sizechoose from listfor CYCLING only
Starting Pointspecify first dither positionnumberfor CYCLING only
Number of Pointsspecify number of dither positionsnumberfor CYCLING only
Pattern Sizespecify pattern sizechoose from listfor SPARSE-CYCLING only
Pointsspecify list of pointsnumberfor SPARSE-CYCLING only
select grating/filter name

choose from list


select readout pattern

choose from list


specify number of groups per integration

number


specify number of integrations per exposure

number


MSA Leakage Calibration
Leakage Calibrationselect if leakage calibration neededNO, YES
Ditherselect if dither neededYES, NO




select Auto Calibration option

NONE, WAVECA


General Information   

The following parameters are generic to all templates, and are not discussed in this article: Observation Number, Observation Label, Observation Comments, Target NameETC Wkbk. Calc. ID, Mosaic Properties, and Special Requirements.

Target Acquisition 

Target Acquisition (TA) Method 

TA METHOD [TA METHOD] = NONE, MSATA, WATA (default), VERIFY_ONLY

For NIRSpec IFU Spectroscopy there are four options: NONE which performs no target acquisition, the standard MSA Target Acquisition (MSATA) that uses reference stars observed through the MSA, the Wide Aperture Target Acquisition (WATA) that observes the target or a reference object through the wide aperture, and calculates an offset to the science aperture to be applied to the subsequent science exposures, and the VERIFY_ONLY method which performs no TA but takes a verification image at the end of the science exposures to allow users to validate the pointing after the fact.

Select the target acquisition method to be used; see IFU template section 3: Target Acquisition Parameters. The standard MSATA is used for observations that require high precision. When roll correction is not required, WATA provides  a means to acquire a target or a reference target without the need for Reference Stars. Pointing Verification can be used for observations that do not require high precision.

Note that MSA target acquisition is not allowed for moving targets. WATA can be used for moving targets, but offset acquisition targets are not allowed when the science target for IFU spectroscopy is a moving target.  The acquisition target must be the same as the science target in that case.

Note for developers:

  • TA METHOD is a required parameter. If WATA is selected, APT should accept WATA target acquisition parameters below. If VERIFY_ONLY is selected, APT should accept Pointing Verification Image parameters below. If MSATA is selected, APT should accept MSA Target Acquisition parameters below.
  • Give a warning when the MAXIMUM REFERENCE STARS special requirement is present for observations that are not NIRSpec TA Method=MSATA.

MSA Target Acquisition Exposure  

If TA METHOD = MSATA then the standard MSA target acquisition uses reference stars located in the MSA field of view to acquire the target. Since you must specify a target acquisition for each individual Visit, the specification is done at the Visit level. Prior to specifying the acquisition, you must import a catalog of candidate reference stars via the MSA Planning Tool (see NIRSpec MPT - Planner). Note that, after the acquisition is complete, an acquisition (or pointing) image will be obtained to allow observers to check the status of the acquisition; see IFU template section 3: Target Acquisition Parameters.

Note that MSATA is not allowed with moving targets.

(red star) The following TA parameters for MSATA are selected at the *Visit Level* of the program.

Reference Star Bin

A Reference Star Bin contains valid reference stars (i.e. they are of a limited brightness range appropriate for a particular ACQUISITION FILTER and READOUT PATTERN) and the NIRSpec configuration that will be used for the acquisition. The MSA Planning tool will generate multiple options of different combinations of references stars, ACQUISITION FILTER, and READOUT PATTERN for you to choose from. While all combinations containing one or more reference stars will be presented, the only viable choices are those with more than 5 reference stars.

Acquisition Filter

 The TARGET ACQUISITION FILTER [TACQ FILTER] is automatically set based on your choice of Reference Star Bin, and can be CLEAR, F140X, or F110W.

 Acquisition MSA Configuration Filename 

The ACQUISITION MSA CONFIGURATION [TACQ MSAFILE] field specifies the MSA configuration to be used for target acquisition (to mask bright stars in the field). Select a configuration previously defined in the MPT, or select ALLOPEN (which leaves all shutters open). If no selection is made, then all shutters will be open.

Acquisition Readout Pattern 

The ACQUISITION READOUT PATTERN [TACQ PATTERN] is automatically set based on your choice of Reference Star Bin, and can be NRSRAPID or NRSRAPIDD6.

Note that the ACQUISITION NUMBER OF GROUPS/INTEGRATION is automatically set to 3 and ACQUISITION NUMBER OF INTEGRATIONS/EXPOSURE is automatically set to 1.

Note for developers: Note that while the SUBARRAY is not explicitly given, its value is FULL for the purposes of calculating exposure time.

WATA Target Acquisition Exposure 

If TA METHOD = WATA, the wide aperture target acquisition must place the acquisition target (which may be the science target) into the NIRSpec wide aperture.  A target acquisition exposure is taken through this aperture to derive a centroid, to center the acquisition target in this wide aperture.  After the target acquisition completes, a “reference image” of the acquisition target centered in the wide aperture is obtained to allow observers to check the status of the acquisition after the fact. Following that, the spacecraft will be repointed to put the science target in the IFU aperture prior to the start of the science exposures; see IFU template section 3: Target Acquisition Parameters.

For this method of TA, the following parameters are used to define NIRSpec Target Acquisition observations. 

Acquisition Target

The default for this parameter is "Same Target as Observation." If instead of the target of the observation, an offset star is to be used for the target acquisition, select the ACQUISITION TARGET [TACQ TARGET] from the list of targets previously entered.

Note that for observations of moving targets, the ACQUISITION TARGET cannot be an offset target.

Notes for developers:

  • The ACQUISITION TARGET field should always be present, but should be defaulted to SAME TARGET AS OBSERVATION.
  • If the acquisition target is different from the science target, APT should provide a warning if the slew distance between the ACQ pointing (to place the acquisition target in the acquisition aperture) and Science pointing (to place the science target in the science aperture) is greater than the Visit splitting distance found in the PRD.
  • If there are multiple pointings within a visit, then the rules have to apply to the greatest separation between acq target and pointing within the visit.

Acquisition Subarray

TARGET ACQUISITION SUBARRAY [TACQ SUBARRAY] = SUB32, SUB2048, FULL

This field specifies the Subarray region on the detector to be used to obtain the acquisition data.

Acquisition Filter 

TARGET ACQUISITION FILTER [TACQ FILTER] = F140X, F110W, CLEAR

This field specifies the filter to be used to obtain the acquisition data.

Acquisition Readout Pattern 

TARGET ACQUISITION READOUT PATTERN [TACQ PATTERN] = NRSRAPID (default), NRSRAPIDD6

This field specifies the readout pattern to be used to obtain the acquisition data.

Note that the ACQUISITION NUMBER OF GROUPS/INTEGRATION is automatically set to 3 and ACQUISITION NUMBER OF INTEGRATIONS/EXPOSURE is automatically set to 1.

Pointing Verification Image

If TA METHOD = VERIFY_ONLY then the following parameters are used to define the NIRSpec Pointing Verification Image exposure. This is an image of the MSA field that will be taken after all science exposures and auto calibrations in each visit have completed.  This exposure can be used during post-analysis to determine the exact pointing of every exposure within the observation.

When  TA METHOD=VERIFY ONLY, certain warnings and informational messages are shown depending on POINTING VERIFICATION IMAGE MSA CONFIGURATION and TARGET

Table 1: Warnings and messages when TA METHOD=VERIFY ONLY

TA METHOD = VERIFY ONLY and...Message

Warning: WATA may be a better choice for more accurate placement in the IFU for point-like acquisition targets with positional uncertainty of 0.1 arcsec or less. 
POINTING VERIFICATION IMAGE MSA CONFIGURATION = None SelectedWarning: NIRSpec MOS pointing verification should normally use the ALLOPEN MSA configuration.
POINTING VERIFICATION IMAGE MSA CONFIGURATION = ALLCLOSED

Warning: A verification image of the target in the IFU using the TA broad-band filter will be acquired. Please note that an image of the target in the science filter can be constructed from the IFU data cube itself, so verification imaging may not be necessary. If neither MSA nor IFU verification imaging is needed, select TA Method = None to omit this imaging."

POINTING VERIFICATION IMAGE MSA CONFIGURATION = ALLOPEN and target is not a moving target

Warning: Verification imaging with an ALLOPEN MSA configuration may cause persistence from bright sources in the field of view.

POINTING VERIFICATION IMAGE MSA CONFIGURATION = ALLOPEN and target is a moving target

Warning: Verification imaging while tracking on a moving target with the MSA ALLOPEN is not recommended.  It will typically cause trailing of fixed background sources in the MSA.

Pointing Verification Image Filter

POINTING VERIFICATION IMAGE FILTER [TACQ FILTER] = F140X, F110W, CLEAR

This field specifies the filter to be used to obtain the pointing verification image. For the grating/filter bandpasses, see NIRSpec Dispersers and Filters.

Pointing Verification Image Readout Pattern

POINTING VERIFICATION IMAGE READOUT PATTERN [POINTING PATTERN] = NRS (default), NRSRAPID, NRSIRS2, NRSIRS2RAPID

This field specifies the readout pattern to be used to obtain the pointing verification image. General Target Acquisition cannot use the noise reduction readout patterns (the IRS2 patterns), but the POINTING VERIFICATION IMAGE can since it is just an image taken after the science observation.

Pointing Verification Image Number of Groups/Integration

POINTING VERIFICATION IMAGE NUMBER OF GROUPS/INTEGRATION [POINTING NGROUPS] specifies the number of groups in an integration.

Note for developers: APT will use these values for calculating the overhead for pointing image exposure times: PV INTEGRATIONS/EXPOSURE=1.  Also, while the SUBARRAY is not explicitly given, its value is FULL for the purposes of calculating exposure time.

Pointing Verification Image MSA Configuration  

POINTING VERIFICATION IMAGE MSA CONFIGURATION=ALLOPEN, ALLCLOSED

The POINTING VERIFICATION IMAGE MSA CONFIGURATION [POINTING MSAFILE] field specifies the MSA configuration to be used for target acquisition (to mask bright stars in the field). Select  ALLOPEN or ALLCLOSEDIf no selection is made, then all shutters will be open.

Science Parameters

Dither Specifications

Most observations with JWST will require dithering.  The following parameters define the dither pattern for NIRSpec Integral Field Unit (IFU) Spectroscopy. Note that the dither pattern does NOT apply to the target acquisition image. From one to sixty exposures result from the different choices of NIRSpec IFU dither parameters.

Dither Type 

DITHER TYPE [PATTERN_TYPE] = NONE, 2-POINT-NOD, 4-POINT-NOD, 4-POINT-DITHER, CYCLING, SPARSE-CYCLING

This parameter specifies the type of dither to be executed.  Nods are like dithers, except that the resulting data are processed differently during background subtraction (see Table 2). CYCLING and SPARSE-CYCLING both require additional parameters.

Table 2. Dither Type Descriptions 

Dither TypeDescription
NONENo dither
2-POINT-NODTwo points separated by just under 2 arcsec in both x (dispersion) and y (spatial) directions.  Both points lie within 1 IFU aperture of each other, so there will be some overlap in their fields.
4-POINT-NODSame as 4-POINT-DITHER, except these data will be processed differently by the pipeline.
4-POINT-DITHERFour points constituting a box a little less than two arcsec on a side. All points lie within 1 IFU aperture of each other, so there will be some overlap in their fields.
CYCLING, SPARSE-CYCLINGThere are three sixty-point cycling patterns (SMALL, MEDIUM and LARGE)  .  If CYCLING, the user chooses STARTING POINT and NUMBER OF POINTS, if SPARSE-CYCLING the user chooses a list of POINTS.

Cycling 

The Cycling pattern consists of a list of 60 pointing positions with random separations.

Pattern Size 

PATTERN SIZE [PATTERN_SIZE] = SMALL, MEDIUM, LARGE

This parameter specifies the extent of the cycling pattern.

Starting Point 

STARTING POINT [STARTING_POINT] = 1, 2, 3, …, 59, 60

This parameter specifies the index of the first dither position.

Number_of_Points 

NUMBER OF POINTS [NUMBER_OF_POINTS] = 1, 2, 3, …

This parameter specifies the number of dither positions of the cycling pattern to execute in sequence. (warning)The combination of STARTING POINT and NUMBER OF POINTS cannot exceed 61.

Sparse Cycling 

The Sparse-Cycling pattern uses the same list of 60 pointing positions as Cycling, but any subset of the points may be specified.

Pattern Size 

PATTERN SIZE [PATTERN_SIZE] = SMALL, MEDIUM, LARGE

This parameter specifies the extent of the cycling pattern to use.

Note to developers: See NIRSpec Dithering Details for dithering details.

Points 

This parameter is a monotonically increasing list of POINTS [POINTS] which are indices from the Cycle Table. Use commas and dashes to separate the values (e.g. 3, 5, 7-9, 15-19).

Grating/Filters

For each exposure, specify the GRATING/FILTER, READOUT PATTERN, NUMBER OF GROUPS/INTEGRATIONNUMBER OF INTEGRATIONS/EXPOSURE, LEAKCAL, DITHER, and AUTOCAL. DITHER. For the grating/filter bandpasses, see NIRSpec Dispersers and Filters. For more information on defining an exposure specification, see  Gratings/Filters and Exposure Configuration.

Note for developers: users can specify one or more combinations of the parameters below.

Grating/Filter Name 

GRATING/FILTER [GRATING, FILTER] = G140M/F070LP, G140M/F100LP, G235M/F170LP, G395M/F290LP, G140H/F070LP, G140H/F100LP, G235H/F170LP, G395H/F290LP, PRISM/CLEAR

Select the name of the grating/filter combination you wish to use for the science observations.

Readout Pattern 

READOUT PATTERN [READOUT PATTERN] = NRS (default), NRSRAPID, NRSIRS2, NRSIRS2RAPID

This field specifies the readout pattern to be used to obtain the science data.

(warning)Note that NUMBER OF GROUPS/INTEGRATION x NUMBER OF INTEGRATIONS/EXPOSURE must be less than 204 for NRISIRS2 and 1024 for NRSIRS2RAPID.

(red star)  Note that there is a 100 second overhead associated with switching between IRS2 and non-IRS2 readout patterns in an observation.

Note to developer:  If there is interleaving of IRS2 and non-IRS2 readout patterns, issue a warning alerting the user to the 100 second overhead.

Number of Groups/Integration

NUMBER OF GROUPS/INTEGRATION [NGROUPS] specifies the number of groups in an integration. (warning)The maximum number of GROUPS/INTEGRATION is 65535.

Number of Integrations/Exposure

NUMBER OF INTEGRATIONS/EXPOSURE [NINTS] field specifies the number of times the integration is repeated. (warning)The maximum number of INTEGRATIONS/EXPOSURE is 65535.

Note to developers: while the SUBARRAY is not explicitly given, its value is FULL for the purposes of calculating exposure time.

MSA Leakage Calibration Exposure(s) 

The user may optionally choose to indicate the exposure is an MSA Leakage Calibration exposure by checking the checkbox in the exposure specification table row. When checked, the exposure specification is for MSA leakage calibration and is provided as a way to compensate for the light leaks in the MSA during data analysis ; for more information on MSA Leakage Calibration Exposures, see NIRSpec MSA Leakage Correction for IFU Observations

LEAKAGE CALIBRATION [LEAKCAL] = NO (default), YES

This parameter specifies whether this exposure specification is for a MSA leakage calibration (with IFU blocked).

Note to developers: LEAKCAL and AUTOCAL are mutually exclusive.  If an exposure specification is for a MSA leakage calibration exposure the AUTOCAL must set to NONE and uneditable.

Note to developers: If the exposure specifications are not grouped by grating in the table, report an error. (The grating wheel must not move between science and LEAKCAL exposures.)

Note to developers: If there is more than one LEAKCAL exposure specification per grating, report an error. (The Data Management System may not be able to deal with this.)

Note to developers: If a LEAKCAL exposure specification does not have a matching science exposure with the same grating/filter combination, provide a warning.

Dither 

The following optional parameter can be  used to turn off dithering for a leakage calibration specification if it is not necessary.

DITHER  = YES(default), NO

Note that when no dithering is requested, the single LEAKCAL exposure will be obtained at the first pointing of the specified dither.

Note to developers: If the exposure specification has LEAKCAL=NO, the DITHER parameter is uneditable and simply reflects whether or dithering has been requested at the template level.

Auto Calibration Exposure

The following parameter is used to request an optional auto calibration exposure  in order to compensate for the inaccuracy of the grating wheel sensors during data analysis

AUTOCAL [AUTOCAL] = NONE(default), WAVECAL

This parameter specifies whether an automatic wavelength calibration exposure(s) will be acquired after all science exposure readouts have been obtained for each this grating/filter combination (at the final science dither position).

 If NONE is chosen, then no automatic wavelength calibration exposure will be obtained.

 If WAVECAL is chosen, the lamp used and the exposure time for calibration will be compatible with the selected science grating.

Note to developer: if AUTOCAL is not NONE, then an error should be generated if the NO PARALLEL special requirement is not specified.

Change log

The documents used in preparing this chapter were the Preliminary Definition of Observing Templates for JWST Science Programs (Fullerton, Nov. 28, 2007) and the NIRSpec OCD (Boker and Valenti, V5, July 1, 2008).

 

  1. PROPINSTJWST-91403 Added Table 1 for VERIFY ONLY messages.


Version 11 (May 11, 2022)

  1. PROPINSTJWST-91468  In Acquisition Target section, removed visit splitting error from developer note.  


Version 10 (October 20, 2021)

  1. PROPINSTJWST-91497 Removed developer note about error/warning.


Version 9 (August 9, 2021)

  1. Editorial change - Anchor links fixed in parameter table by removing pagename from link.


Version 8 (June 19, 2020)

  1. PROPINSTJWST-91483 Added developer note for MAXIMUM REFERENCE STARS special requirement. 


Version 7 (October 2, 2020)

  1. PROPINSTJWST-89341  Changed NGroups*Nints limit for NIRSIRS2 readout pattern from 256 to 204. 


Version 6 (September 17, 2019)

  1. PROPINSTJWST-91408 - Replaced NRS with NRSRAPIDD6 in TA Readout Pattern.


Version 5 (April 19, 2019)

  1. Editorial change (moved change log to main article)


Version 4 (November 29. 2018)

  1. PROPINSTJWST-91157 - Added developer note in MSA Leakage Calibration Exposures section requiring warning for "no matching science exposure."


Version 3 (October 16, 2017)

  1. PR 85473 - added TA and other parameters to support WATA (includes PR 88516)
  2. PR 87895 - updated terminology for Exposure parameters
  3. PR 88968 - revised overhead time for switching between IRS and IRS2 readout patterns
  4. PR 88047 - added restriction on NGroups x NINTs for IRS2 readout pattern
  5. PR 86097 - added TA=NONE option


Version 2 (November 12, 2016)

  1. PR 82875  - added dither specification
  2. PR 82856  - added MSA Leakage Calibration exposure
  3. Editorial - updated description of Auto Calibration exposure


Version 1 (June 9, 2016)

This is the converted Word File from Chapter 31.