MIRI Medium Resolution (Integral Field Unit) Spectroscopy Template Parameters
JWST's MIRI Medium Resolution (Integral Field Unit) 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 MIRI Medium Resolution (Integral Field Unit) Spectroscopy template is to be used for all observations using the medium resolution spectroscopy mode of MIRI, and this article describes allowed values for all parameters. Advice on how to choose values which optimize your science can be found in the MIRI MRS APT Template article.
The MIRI Medium Resolution (Integral Field Unit) 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 Exposure | |||
| Acquisition Target | select acquisition target | choose from list | |
| Acquisition Filter | select filter name | choose from list | |
| Acquisition Readout Pattern | select acquisition readout pattern | choose from list | |
| Acquisition Number of Groups/Integration | select number of groups per integration | choose from list | |
| Acquisition Number of Integrations/Exposure | select number of integrations per exposure | 1 | only allowed value |
| Science Exposures | |||
| Primary Channel | select primary channel | choose from list | |
| Dither Specifications | |||
| Dither Type | select dither type | choose from list | |
| Optimized For | select type of science dither optimized for | POINT SOURCE, EXTENDED SOURCE | |
| Direction | select direction of dither pattern | POSITIVE, NEGATIVE | |
| select if simultaneous imaging required | YES, NO | ||
| Imager Subarray | select subarray for Imager | choose from list | only if Simultaneous Imaging = YES |
| Grating Wheel Direction | select rule for exposure order | ALLOW AUTO REORDER, DISALLOW AUTO REORDER | |
| Exposure Specifications | |||
| Detector | based on selection of Simultaneous Imaging parameter | ||
| Wavelength Range | select wavelength range | choose from list | |
| Imager Filter | select filter | choose from list | only if Simultaneous Imaging = YES |
| Readout Pattern | select readout pattern | choose from list | |
| Number of Groups/Integration | specify number of groups per integration | number | |
| Number of Integrations/Exposure | specify number of integrations per exposure | number | |
| Number of Exposures/Dither | specify number of times to repeat the exposure for each dither position | number | |
| Dither | select dither specification | choose from list | |
General Information
The following parameters are generic to all templates, and are not discussed in this article: Observation Number, Observation Label, Observations Comments, Target Name, ETC Wkbk. Calc. ID, Mosaic Properties, and Special Requirements.
Target Acquisition
The following parameters are used to define MIRI Target Acquisition observations. Note that for Medium Resolution Spectroscopy, the imager is used for the target acquisition and the science target is generally used for the acquisition, although when necessary, an offset star may be used. For more information on defining a target acquisition specification, see MIRI MRS Target Acquisition.
Acquisition Target
If an offset star is to be used for the target acquisition observation, select the ACQUISITION TARGET NAME [TACQ TARGET] from the list of targets previously entered . When the science target is a Solar System target, the acquisition target MUST be the science target. Or, if no target acquisition is needed, select ACQUISITION TARGET to be NONE.
Note for developers: For APT, the ACQUISITION TARGET field should always be present, but should be defaulted to the prime target for the Observation.
Note for developers: If the acquisition target is different from the science target, APT should provide a warning if the distance between the ACQ and Science targets is greater than the Visit splitting distance found in the PRD. 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.
Note for developers: MRS target acquisition will use the FULL array.
Note for developers: If the observation target is a fixed target, remove solar system targets from the acquisition target options. If the observation target is a Solar system target, remove all options from the acquisition target list except for the observation target and NONE.
Acquisition Target Filter
TARGET ACQUISITION FILTER [TACQ FILTER] = F560W, F1000W, F1500W, FND
This parameter specifies the TARGET ACQUISITION FILTER to be used for the target acquisition.
Acquisition Readout Pattern
READOUT PATTERN [TACQ PATTERN] = FAST (default), FASTGRPAVG, FASTGRPAVG8, FASTGRPAVG16, FASTGRPAVG32, FASTGRPAVG64
This field specifies the readout pattern to be used to obtain the acquisition data.
Acquisition Number of Groups/Integration
NUMBER OF GROUPS/INTEGRATION [TACQ NGROUPS] = 4, 6, 8, 10
This field specifies the number of groups in an integration.
Acquisition Number of Integrations/Exposure
The NUMBER OF INTEGRATIONS/EXPOSURE [TACQ NINTS] is set to 1 for target acquisition observations.
Science Exposures
Primary Channel
PRIMARY CHANNEL [PRIMARY_CHANNEL] = ALL MRS (default), CHANNEL1, CHANNEL2, CHANNEL3, CHANNEL4, IMAGER
The parameter specifies the channel of interest for this observation. This choice will drive the placement of the target, the size of offsets if a mosaic is request, what size field of view is displayed in Aladin, and the dither pattern. Note ALL MRS is functionally the same at CHANNEL1.
Dither Specifications
Most MIRI MRS observations will require dithering; see MIRI MRS PSF and Dithering for details.
Dither Type
DITHER TYPE [PATTERN_TYPE] = 2-POINT, 4-POINT (default), SCAN
This parameter specifies the dither for the exposure. The SCAN DITHER TYPE has 57 points and is specified in the PRD MiriMrsDithers table as SCAN-CALIBRATION.
Optimized For
OPTIMIZED FOR [OPTIMIZED_FOR] = POINT SOURCE, EXTENDED SOURCE, BACKGROUND
Selecting the type of science (extended or not) the dither is optimized for controls the scale of the dither.
- If the target is EXTENDED, the default is EXTENDED SOURCE; otherwise the default is POINT SOURCE.
- For DITHER TYPE=SCAN, OPTIMIZED FOR is set to POINT SOURCE and may not be changed.
For PRIMARY CHANNEL=IMAGER, OPTIMIZED FOR is set to BACKGROUND and may not be changed. For more information see MIRI MRS Dedicated Sky Observations.
| After OPTIMIZED FOR has a selected value, it will not change if a target is selected, a target's EXTENDED value is changed, or a new target is selected. The user must manually change the value. |
|---|
Direction
DIRECTION [DIRECTION]= POSITIVE, NEGATIVE (default)
Select the direction of the dither.
- When OPTIMIZED FOR = EXTENDED SOURCE, DIRECTION is set to NEGATIVE and may not be changed.
- For DITHER TYPE=SCAN, DIRECTION is set to NEGATIVE and may not be changed.
- For PRIMARY CHANNEL=IMAGER, DIRECTION is set to NEGATIVE and may not be changed.
Note to developer: When DITHER TYPE is 2-POINT, use only the first two points of the dither pattern for the selected DIRECTION and OPTIMIZED FOR.
Simultaneous Imaging
SIMULTANEOUS IMAGING = YES (default), NO
This parameter specifies if simultaneous imaging is required. A value of YES will obtain imaging data at the same time as data is collected on both of the IFU detector arrays.
The Time Series Observation special requirement is not allowed with Simultaneous Imaging.
Note to developer: To store in the database, if SIMULTANEOUS IMAGING = YES then set DETECTOR = ALL, else set DETECTOR = MRS.
Imager Subarray
IMAGER SUBARRAY [SUBARRAY] = FULL (default), BRIGHTSKY, SUB256, SUB128, SUB64
This parameter is only relevant when SIMULTANEOUS IMAGING = YES. It specifies the region of the detector that is to be read out for the imager data. Note that if a value of IMAGER SUBARRAY other than FULL is used, there may be some data quality issues because of the switch from FULL which is used for the target acquisition. For more details, see Imager subarray in the MIRI MRS APT Template article.
Note for developers: Inform the user with a warning if SUBARRAY other than FULL selected.
Note for developers: These tables show what should be displayed in the GUI, along with the appropriate commanding name for the database, for the two values of SIMULTANEOUS IMAGING.
SIMULTANEOUS IMAGING = NO
| # | Detector | No. of Exposures | Readout Pattern | No. of Groups | No. of Integrations | Dither |
|---|---|---|---|---|---|---|
| 1 | MRSLong | [NEXP] | [READOUT PATTERN] | [NGROUPSLONG] | [NINTSLONG] | |
| 1 | MRSShort | copied from above | copied from above | [NGROUPSSHORT] | [NINTSSHORT] | copied from above |
SIMULTANEOUS IMAGING = YES
# | Detector | No. of Exposures | Filter | Readout Pattern | No. of Groups | No. of Integrations | Dither |
|---|---|---|---|---|---|---|---|
1 | Imager | [NEXP] | [FILTER] | [READOUT PATTERN] | [NGROUPS] | [NINTS] | |
1 | MRSLong | copied from above | N/A | [READOUT PATTERN LONG] | [NGROUPSLONG] | [NINTSLONG] | copied from above |
1 | MRSShort | copied from above | N/A | [READOUT PATTERN SHORT] | [NGROUPSSHORT] | [NINTSSHORT] | copied from above |
Grating Wheel Direction
GRATING WHEEL DIRECTION = ALLOW AUTO REORDER (default), DISALLOW AUTO REORDER
Select the rule for ordering exposures.
For approved proposals, the Long Range Plan (LRP) may reorder exposures according to their WAVELENGTH RANGE which may be Long, Medium, or Short (L-M-S). This is done to optimize mechanical moves of the MIRI Grating Wheel.
To prevent the LRP from reordering exposures, select DISALLOW AUTO REORDER. Exposures may be reordered by the user.
- ALLOW AUTO REORDER - Allows the LRP (Long Range Plan) to reorder exposures. Note that the sequence of wavelength ranges must be a full grating wheel rotation such as L-M-S or S-M-L to actually be auto reordered by the LRP.
- DISALLOW AUTO REORDER - Directs the LRP not to reorder exposures, and retains the exposure order set by the user.
Exposure Specifications
For each exposure to be executed at each position in a dither pattern, specify the NUMBER OF EXPOSURES/DITHER, IMAGER FILTER, READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION, NUMBER OF INTEGRATIONS/EXPOSURE, and DITHER. For the filter bandpasses, see MIRI Filters and Dispersers. For more information on defining an exposure specification, see Exposure parameters in the MIRI MRS APT Template article.
Detector
This field specifies the detector to be used, and is automatically populated based on the choice of SIMULTANEOUS IMAGING.
Wavelength Range
WAVELENGTH RANGE [WAVELENGTH_1_4, WAVELENGTH_2_3] = SHORT (A), MEDIUM (B), LONG (C)
Each of the four Integral Field Unit (IFU) image slicers covers a separate wavelength range. Each of these wavelength ranges can be covered by a set of three available gratings. You can request one grating by means of the WAVELENGTH RANGE parameter. Note the same wavelength region will be obtained with each IFU channel. So if you specify SHORT (A) then the short portion of the wavelength range will be obtained simultaneously with each IFU channel.
Select the wavelength region you wish to use for your science observations; (see Exposure parameters in the MIRI MRS APT Template article for details).
Note for developer: APT will populate the chosen WAVELENGTH RANGE value (with Short/Medium/Long only) into both WAVELENGTH_1_4 and WAVELENGTH_2_3.
Imager Filter Name
IMAGER FILTER [FILTER] = F560W, F770W, F1000W, F1130W, F1280W, F1500W, F1800W, F2100W, F2550W, OPAQUE, FLENS, F1065C, F1140C, F1550C,F2300C, F2550WR, P750L, FND
This field specifies the filters to be used to obtain the imaging data; this parameter is only relevant when SIMULTANEOUS IMAGING = YES.
Note to developer: If the PRIMARY CHANNEL = ALL MRS, or CHANNEL1 -or- the dither is OPTIMIZED FOR = EXTENDED, and the IMAGER FILTER = F1280W, FND, F1500W, F1550C, F1800W, F2100W, F2300C, F2550W, or F2550WR, then warn that "for this filter the MRS dither pattern selected may cause the PSF in the simultaneous MIRI imaging to overlap. Maximum wavelengths for imager with no PSF overlap is lambda/D >= 6." Same warning if the PRIMARY CHANNEL = CHANNEL2 and the IMAGER FILTER = F2100W, or F2550W.
Readout Pattern
READOUT PATTERN = FASTR1 (default), SLOWR1, FASTGRPAVG
This field specifies the readout pattern to be used to obtain the data.
Developer note: see tables above for commanding names.
If both SLOWR1 and either FASTR1 or FASTGRPAVG are used for the MRS in one observation, a settling time delay will be incurred each time there is a switch from one to the other. This delay is currently set to 0 but will likely be updated after commissioning.
If both SLOWR1 and either FASTR1 or FASTGRPAVG are used for the Imager in one observation, no settling time delay will be incurred, but there may be some data quality issues because of the switch.
Note to developer:
- inform the user with a warning about settling time delay in either of these cases.
- This settling delay is specified as miri_readout_settling_duration in the PRD observing_limitations table.
Number of Groups/Integration
NUMBER OF GROUPS/INTEGRATION [NGROUPS] specifies the number of groups in an integration. Allowed values are shown in Table 1.
MIRI integration duration may not be greater than 2000 seconds. Integration time = (Frame time * NUMBER OF GROUPS/INTEGRATION). Frame time is a property of the selected READOUT PATTERN. For more information, see MIRI Detector Readout Overview.
Note to developer: Maximum MIRI integration duration is specified in the PRD as max_integration_duration_miri in the observing_limitations table.
Table 1. Allowed values for NUMBER OF GROUPS/INTEGRATION
| When readout pattern is | Value of NUMBER OF GROUPS/INTEGRATION | Allowed? |
|---|---|---|
| FASTR1, SLOWR1, FASTGRPAVG | 1 | Not allowed (error) |
| FASTR1, SLOWR1 | 2 | Allowed with permission (see Limited Access Parameters) |
| FASTGRPAVG | 2,3 | Allowed but not recommended (warning) |
| FASTGRPAVG | >3 | Allowed |
| FASTR1, SLOWR1 | 3,4 | Allowed but not recommended (warning) |
| FASTR1, SLOWR1 | >4 | Allowed |
Number of Integrations/Exposure
NUMBER OF INTEGRATIONS/EXPOSURE [NINTS] specifies the number of times the integration is repeated; default = 1.
Table 2. MIRI MRS Restrictions on Exposure Time
Readout pattern | Exposure time for Long and Short detectors |
|---|---|
| FASTR1, SLOWR1 | Total Exposure Time for Long detector and Total Exposure Time for Short detector must differ by less than 10%. |
| FASTGRPAVG | Total Exposure Time for Long detector and Total Exposure Time for Short detector must be the same (must conform to the following restriction): NUMBER OF INTEGRATIONS/EXPOSURE (LONG) * NUMBER OF GROUPS/INTEGRATION (LONG) = NUMBER OF INTEGRATIONS/EXPOSURE(SHORT) * NUMBER OF GROUPS/INTEGRATION( SHORT) |
Developer note: see tables under Imager Subarray section above for commanding names.
Developer note: The MRS exposure determines the total exposure duration. If SIMULTANEOUS IMAGING = YES, for each triplet, compare the duration for the Imager exposure to the duration for the MRS exposures and give an error if the Imager exposure is longer.
Number of Exposures/Dither
NUMBER OF EXPOSURES/DITHER [NEXP] specifies the number of times the exposure is to be repeated at each dither position. The default value is 1.
If NUMBER OF EXPOSURES/DITHER > 1, the NO PARALLEL special requirement is required.
When the TIME SERIES OBSERVATION special requirement is used, NUMBER OF EXPOSURES/DITHER is NOT limited access.
Note for developer: If NUMBER OF EXPOSURES/DITHER > 1. provide the following error: " The Special Requirement NO PARALLEL must be used with this Observation." and the following diagnostic explanation: "The NO PARALLEL requirement is required for Coordinated Parallels; Time Series observations; external observations with NUMBER OF EXPOSURES/DITHER > 1 and dithering; NIRSpec observations with Auto Calibrations; NIRCam Grism Time Series; and engineering templates (FGS Internal Flat, MIRI Anneal, MIRI External Flat, NIRSpec Internal Lamp, NIRSpec MSA Masking, NIRSpec MSA Anneal, NIRISS Internal Flat, all WFSC)."
Dither
Select the number corresponding to one of the dither specification previously specified or NONE.
Note for developers: DITHER should be a required field, and there should be no default value (i.e. do not make NONE the default)