JWST's NIRSpec Multi-Object Spectroscopy template, available in the Astronomer’s Proposal Tool (APT), has parameters for specifying and scheduling observations.

Introduction

The NIRSpec Multi-Object Spectroscopy (MOS) template is to be used for all observations using the multi-object spectroscopy mode of NIRSpec, and this article describes allowed values for all parameters. The MOS offers either the option of the standard MSA target acquisition, or to simply take an image to verify pointing during post-analysis. Note that for the MSA, the target position refers to the reference point of the MSA apertures, and not to any particular MSA source. Advice on how to choose values which optimize your science can be found in the NIRSpec MOS Recommended Strategies; also see NIRSpec MSA Planning Tool, MPT.

Observers will normally need to use the MSA Planning Tool, which is accessed at the Observation Folder level, to design their observations. This tool will automatically populate some necessary parameters for the observation template. Note that the MSA Planning Tool can be used to:

• Create MOS observations
• Make custom MSA configurations for MOS observations, Calibrations , or MSA standard target acquisition
  
• Specify parameters needed to perform MSA standard target acquisition for the MOS, Fixed Slit, or Integral Field Unit Spectroscopy observations.
  

For those templates created using the MPT, APT will automatically add either the special requirement MSA PLANNED APERTURE PA  (if an aperture position angle has not yet been selected by STScI) or MSA SELECTED APERTURE PA  (if an aperture position angle has been selected by STScI).

For visits with the MSA PLANNED APERTURE PA special requirement, the Visit Planner schedules visits without guide star checking (PCS MODE=COARSE). When STScI assigns an aperture position angle, MSA PLANNED APERTURE PA is removed and MSA SELECTED APERTURE PA is assigned.

The NIRSpec Multi-Object Spectroscopy template consists of the following parameters:

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.  

MSA Plan 

If the template was generated by using the MSA Planning Tool (MPT), select the appropriate plan. Note that the MSA Plan defaults to the plan used when the template was created. If you select a different plan than the one the template was built from, the template (e.g. the exposure specifications) is rebuilt to match that plan.

Pre-Image Availability 

PRE-IMAGE AVAILABILITY = “Is already obtained”, “Will be obtained external to this program”, “Will be done in this program”, “Not required”

Most NIRSpec MOS observations require a preliminary NIRCam image, or possible other  (e.g. HST/WFC3) image, to be obtained.  This should be indicated in the template in one of three ways:

• If the NIRCam (or other ) image is already obtained, select the "Is already obtained" option. You must also then specify the Pre-Image file. Pre-image file upload is available only for approved proposals.
  
• If a NIRCam image is to be obtained external to the proposal (either as part of a different JWST proposal or with another observatory), select the "Will be obtained external to this program" option.

You should also use the ON HOLD special requirement on the observation.

• If a NIRCam image is to be obtained as part of the proposal, select the "Will be done in this program" option, and select the observation which contains the NIRCAM image.

You should also place an AFTER OBS BY special requirement on the MOS observation(s) to link the NIRCam observation to the MOS observation(s).

If a pre-image is not required, select the "Not required" option.

Note that if “Will be obtained external to this program” or “Will be done in this program” is selected, the NIRSpec MOS observation will NOT be scheduled until the observer has notified STScI that the NIRCam image has been obtained and analyzed.

Note for developers: If the last option is selected, APT should issue a warning if the AFTER OBS BY is not a sufficient interval  (at least 6 weeks). If the second option is selected, APT should issue an error if an ON HOLD is not present. APT should also verify that at least one of the options is selected.

Note for developers: If PRE-IMAGE AVAILABILITY = "Will be done in this program" then:

- Error if an AFTER OBS BY special requirement is not included, or is after < 42 days.

- Warning if AFTER OBS BY is after < 60 days (but not if error is triggered).

Target Acquisition 

Target Acquisition (TA) Method 

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

For NIRSpec MOS 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 NIRSpec Target Acquisition. 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 (TA METHOD=VERIFY_ONLY) can be used for observations that do not 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 MOS 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 MSATA is selected, APT should accept MSA Target Acquisition parameters below. If VERIFY_ONLY is selected, APT should accept Pointing Verification Image parameters below. If WATA is selected, APT should accept WATA Target Acquisition parameters below.

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 - Catalogs). 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 NIRSpec Target Acquisition.

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

Note for developers: If the user selects a bin with fewer than 5 reference stars an error will be shown. If they select one with 5-8 reference stars they will get a warning.

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

Acquisition Readout Pattern 

The 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  

For MSA spectroscopy, wide aperture target acquisition can only be used for observations of fixed or moving targets designed at the observation level in APT.  WATA is not compatible with observations generated using the MSA Planning Tool, and cannot be applied to them.  For MPT-generated observations and visits, the MSA TA method must be used; see NIRSpec Target Acquisition.

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 selected aperture prior to the start of the science exposures; see NIRSpec Target Acquisition.

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

Acquisition Target

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.

Note for developers: For APT, the ACQUISITION TARGET field should always be present, but should be defaulted to SAME TARGET AS OBSERVATION.

Note for developers: 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. But if the separation is greater than 2 arcminutes, an error should be provided. Also, 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.

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, 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 Filename  

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 a configuration previously defined in the MPT, ALLOPEN (which leaves all shutters open), or ALLCLOSED (which leaves all shutters closed). If no selection is made, then all shutters will be open.

Science Exposures

Science Aperture

For MOS observations, the science aperture is typically the full MSA (with reference point at the center of the MSA).  However, when TA METHOD=NONE, WATA or VERIFY_ONLY, the user must select where the science source should be centered.  There are three options: the MSA center reference point, or one of the two defined field points in MSA quadrant 4 which are within reach of the acquisition aperture used for WATA in the same Visit; only the FIELD1 position is within visit splitting distance of the acquisition aperture.  The FIELD2 position requires the use of an offset acquisition target that keeps the slew length within the visit splitting distance for the allowed orientation range.  Alternatively, the FIELD2 position can be used with TA_METHOD=VERIFY_ONLY.

SCIENCE_APERTURE [APERTURE] = MSA Center, Q4 Field Point 1, Q4 Field Point 2

The nominal default aperture is MSA Center, however, when the WATA methodology is used for target acquisition, Q4 Field Point 1 becomes the default reference position for MOS spectroscopy.

Grating/Filters 

For each exposure to be executed, specify the GRATING/FILTER, MSA CONFIGURATION, READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION, NUMBER OF INTEGRATIONS/EXPOSURE, and AUTOCAL (if desired). For the grating/filter bandpasses, see NIRSpec Dispersers and Filters. For more information on defining an exposure specification, see MPT Section 5: Exposure Setup.

Note that if the template was generated from the MPT, the following fields (through AUTOCAL) will already be populated.

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

Grating/Filter Name 

GRATING/FILTERS [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.

MSA Configuration 

MSA CONFIGURATION [MSA CONFIGURATION] = ALLOPEN, ALLCLOSED, Q4 Field Point 1 Long Slit, Q4 Field Point 2 Long Slit

Select the MSA configuration to be used to obtain the science data.

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 256 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 for developers:  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.

Autocal Calibration Exposure(s) 

The AUTOCAL  parameter is used to request optional auto calibration exposure(s) in order to compensate for the inaccuracy of the grating wheel sensors during data analysis. 

AUTOCAL [AUTOCAL] = NONE (default), FLAT, WAVECAL, BOTH

This parameter specifies whether automatic flat or wavelength calibration exposure(s) will be acquired after all science exposure readouts have been obtained for each grating/filter combination. 

If NONE is chosen, then no automatic flat or wavelength calibration exposures will be obtained.

If FLAT, WAVECAL, or BOTH is chosen, the lamp used and the exposure time for calibration will be compatible with the selected science grating. Specifying BOTH will result in taking flat and wavelength calibrations during the observation.

Note to developers: if AUTOCAL is not NONE, then the observation should get an implicit NO PARALLEL special requirement attached.

Optional Confirmation Image

The following parameters are used to define an optional confirmation image.

Obtain Confirmation Images 

OBTAIN CONFIRMATION IMAGES [CONFIRM] = NO (default), AFTER TARGET ACQ, AFTER TARGET ACQ AND NEW MSA CONFIGURATION

If desired, an optional confirmation image can be obtained.  This image will be acquired with the first science filter; see Planning NIRSpec MOS confirmation images. If you wish to obtain this image (and have it repeated after every target acquisition), select AFTER EACH TARGET ACQ. If you would also like to obtain this image after each new MSA configuration, select AFTER TARGET ACQ AND NEW MSA CONFIGURATION.

Confirmation Images

If the AFTER TARGET ACQ AND NEW MSA CONFIGURATION is selected, specify the CONFIRMATION READOUT PATTERN AND CONFIRMATION NUMBER OF GROUPS; note that the CONFIRMATION NUMBER OF INTEGRATIONS must be 1.

Confirmation Type 

This field specifies the confirmation type to be used to obtain the data, and is automatically populated based on the choice of OBTAIN CONFIRMATION IMAGES.

Confirmation Readout Pattern 

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

This field specifies the readout pattern to be used to obtain the optional confirmation image. Note that the choice of science READOUT PATTERN dictates which of the READOUT PATTERNs are available for the confirmation image (i.e. either the IRS2 or the non-IRS2 patterns).

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

Note for developer: NINTS = 1. Also note that while the SUBARRAY is not explicitly given, its value is FULL for the purposes of calculating exposure time.

Change log