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.
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:
|assign observation number|
|Observation Label||provide observation label||text||optional|
|Observation Comments||provide observation comments||text||optional|
|select Target Name||choose from list||from Target List|
|specify ETC Workbook Calculation ID||number||for science exposures (optional) and target acquisition exposures|
|specify mosaic parameters||number||if needed|
|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|
|Primary Channel||select primary channel||choose from list|
|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 wheel direction||choose from list|
|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
specify number of integrations per exposure
|Number of Exposures/Dither||specify number of times to repeat the exposure for each dither position||number|
|Dither||select dither specification||choose from list|
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.
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
4, 6, 8, 10
This field specifies the number of groups in an integration.
Acquisition Number of Integrations
The NUMBER OF INTEGRATIONS/EXPOSURE [TACQ NINTS] is set to 1 for target acquisition observations.
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.
Most MIRI MRS observations will require dithering; see MIRI MRS PSF and Dithering
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] = 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]= 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 = 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 [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
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||MRSShort||copied from above||copied from above||[NGROUPSSHORT]||[NINTSSHORT]||copied from above|
SIMULTANEOUS IMAGING = YES
No. of Exposures
No. of Groups
No. of Integrations
|MRSLong||copied from above||N/A|
[READOUT PATTERN LONG]
|copied from above|
copied from above
[READOUT PATTERN SHORT]
|copied from above|
Grating Wheel Direction
GRATING WHEEL DIRECTION=NEUTRAL, FORWARD, REVERSE
Select the direction of rotation for the MIRI grating wheel. The selected direction overrides the direction currently in the Long Range Plan (LRP). APT displays a message with the direction already set in the LRP for example: "This observation has a planned MIRI grating wheel direction of Forward."
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 more information on defining an exposure specification, see Exposure parameters in the MIRI MRS APT Template article.
This field specifies the detector to be used, and is automatically populated based on the choice of SIMULTANEOUS IMAGING.
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.
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 = 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)|
|FASTR1, SLOWR1||3,4||Allowed but not recommended (warning)|
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
Exposure time for Long and Short detectors
Total Exposure Time for Long detector and Total Exposure Time for Short detector must differ by less than 10%.
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.
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)."
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)
- PROPINSTJWST-91601 Added ALL MRS and IMAGER options to Primary Channel section. Added BACKGROUND option to Optimized For section.
- PROPINSTJWST-91592 Added GRATING WHEEL DIRECTION section.
December 16, 2022
- PROPINSTJWST-91569 In Number of Integrations/Exposure section, removed constraint for LAP (undoes PROPINSTJWST-91405)
July 15, 2022
- PROPINSTJWST-91521 Changed text color of NUMBER OF EXPOSURES/DITHER section to purple to indicate LAP, and added TSO exception to LAP.
- PROPINSTJWST-91545 Added SCAN dither to Dither Type section.
- PROPINSTJWST-87257 Updated Optimized For section to include new default behavior.
Version 17 (October 19, 2021)
Version 16 (May 2, 2021)
- PROPINSTJWST-91406 Added table of allowable values for NUMBER OF GROUPS/INTEGRATION.
- PROPINSTJWST-91405 Added LAP restriction to NUMBER OF INTEGRATIONS PER EXPOSURE for values > 1 when READOUT PATTERN=SLOW.
- PROPINSTJWST-91407 Added restriction that integration duration must be less than 2000 seconds.
Editorial change - Anchor links fixed in parameter table by removing pagename from link.
Version 15 (September 8, 2020)
- PROPINSTJWST 90194 - Updated Simultaneous Imaging section to disallow TSO SR with Simultaneous Imaging.
- PROPINSTJWST-91455 - Updated developer note regarding Visit Splitting Distance in the Acquisition Target section to change from "error" to "warning."
Version 14 (February 18, 2020)
- PROPINSTJWST-91438 - Updated Readout Pattern section to indicate FAST is the default.
Version 13 (December 19, 2019)
- PROPINSTJWST-87257 - Added developer note to the Direction section.
Version 12 (September 23, 2019)
- PROPINSTJWST-91395 - added new Acq Readout Pattern options.
Version 11 (June 7, 2019)
- PROPINSTJWST-91381 - updated Acquisition Number of Groups/Integration section.
Version 10 (April 18, 2019)
- Editorial change (moved change log to main article).
Version 9 (December 21, 2018)
- PROPINSTJWST-91122 - Added developer note in Acquisition Target section restricting acquisition target options for fixed vs. solar system observations.
- PROPINSTJWST-87189 - removed SLOW option from acq readout
Version 8 (August 14. 2018)
- PR 89798 - Updated Acquisition Number of Groups/Integration section.
- PR 90970 - revised warning to Wavelength Range section.
Version 7 (May 14, 2018)
- PR 89879 - NO PARALLEL special requirement required for external observations with NEXP>1, added red note and developer note.
- PR 89323 - Updated red notes in Number of Groups/Integration for FASTGRAVP
- PR 86951 - added restricted filters and updated developer note Filter Name section
Version 6 (December 26, 2017)
- PR 88480 - revised the WAVELENGTH parameter
- PR 89483 - added restriction on Acq Target for SS observations
- PR 86278 - added option for no target acquisition
Version 5 (September 27, 2017)
- PR 88372 - revised the WAVELENGTH parameter
- PR 87895 - updated Exposure field labels to Groups/Integration and Integrations/Exposure
- PR 88896 - made TA Number of Groups/Integration be a picklist
Version 4 (May 11, 2017)
- PR 87747 - revised Readout Pattern for wait period
Version 3 (December 20, 2016)
- PR 80734 - added Number of Exposures parameter
- PR 85174 - revised Dither Types
- PR 85823 - added Primary Channel parameter
- PR 85925 - added simultaneous MIRI imaging
- PR 85925 - added restrictions on Readout Pattern, Num Groups
- PR 85925 - added default for Num Ints
- PR 85608 - updated TA parameters
- PR 85929 - added Imager Subarray restriction
- PR 85863 - updated developer note for Acquisition Target
- PR 83015 - updated Optimized For parameter
Version 2 (July 16, 2016)
- PR 84810 - updated text for WAVELENGTH REGION to clarify that 3 sets of exposures will be obtained when ALL selected
Version 1 (May 2, 2016)
his is the converted Word File from Chapter 12.