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.
Red text indicates restrictions on a parameter.
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:
| Field | Details | Values | Notes |
|---|---|---|---|
| General Information | |||
| Observation Number | assign observation number | number | |
| Observation Label | provide observation label | text | optional |
| Observation Comments | provide observation comments | text | optional |
| Target Name | select Target Name | choose from list | from Target List |
| specify ETC Workbook Calculation ID | number | for science exposures (optional) and target acquisition exposures | |
| Mosaic Properties | specify mosaic parameters | number | if needed |
| Special Requirements | specify special requirements | choose from list | if needed |
| Template Specific Information | |||
| Target Acquisition Parameters | |||
| Target Acquisition Method | select target acquisition method | choose from list | |
| HFF Readout Mode | select HFF Readout Mode on/off | checkbox | |
| MSA Target Acquisition Exposure | |||
| Reference Star Bin | list of reference stars and configuration | choose from list | |
| Acquisition Filter | filter name | set based on Reference star bin | |
| Acquisition MSA Configuration Filename | specify filename | if needed | |
| Acquisition Readout Pattern | readout pattern | set based on Reference star bin | |
| WATA Target Acquisition Exposure | |||
| Acquisition Target | select acquisition target | choose from list | |
| Acquisition Subarray | select subarray | choose from list | |
| Acquisition Filter | select filter | choose from list | |
| Acquisition Readout Pattern | select readout pattern | choose from list | |
| Pointing Verification Image | |||
| Pointing Verification Image Filter | select filter name | choose from list | |
| Pointing Verification Image Readout Pattern | select readout pattern | choose from list | |
| Pointing Verification Image Number of Groups/Integration | specify number of groups per integration | number | |
| Pointing Verification Image MSA Configuration Filename | specify filename | if needed | |
| Science Parameters | |||
| Dither Type | select dither type | choose from list | see Table 1 |
| Pattern Size | specify pattern size | choose from list | for CYCLING only |
| Starting Point | specify first dither position | number | for CYCLING only |
| Number of Points | specify number of dither positions | number | for CYCLING only |
| Pattern Size | specify pattern size | choose from list | for SPARSE-CYCLING only |
| Points | specify list of points | number | for 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 Calibration | select if leakage calibration needed | NO, YES | |
| Dither | select if dither needed | YES, 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 Name, ETC 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.
HFF Readout Mode
(available only when TA METHOD=MSATA)
HFF READOUT MODE (Hybrid Full Frame) is a special readout mode used for MSATA target acquisition depending on the science READOUT PATTERN.
Switching between IRS2 and full-frame readouts can introduce thermal transients which may affect data quality. However, MSATA target acquisition can only be done with a full-frame (non-IRS2) readout pattern.. The HFF Readout Mode is designed to maintain the data format of full-frame readouts, but mimics the power dissipation of IRS2 patterns, such that thermal transients should be minimized. For more information, see (JDOX link).
APT provides a warning when there are different readout modes for TA and Science exposures, This warning is provided when:
- HFF READOUT MODE is selected, and READOUT PATTERN for the first science exposure of the first visit is not NIRS2 or NIRS2RAPID.
- HFF READOUT MODE is not selected, and READOUT PATTERN for the first science exposure of the first visit is NIRS2 or NIRS2RAPID.
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.
| 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 Selected | Warning: 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 ALLCLOSED. If 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 Type | Description |
|---|---|
| NONE | No dither |
| 2-POINT-NOD | Two 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-NOD | Same as 4-POINT-DITHER, except these data will be processed differently by the pipeline. |
| 4-POINT-DITHER | Four 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-CYCLING | There 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. 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/INTEGRATION, NUMBER 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.
Note that NUMBER OF GROUPS/INTEGRATION x NUMBER OF INTEGRATIONS/EXPOSURE must be less than 204 for NRISIRS2 and 1024 for NRSIRS2RAPID.
| 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. 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. 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.