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.

(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 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:

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 Exposure
Acquisition Targetselect acquisition targetchoose from list
Acquisition Filterselect filter namechoose from list
Acquisition Readout Patternselect acquisition readout patternchoose from list
Acquisition Number of Groups/Integrationselect number of groups per integrationchoose from list
Acquisition Number of Integrations/Exposureselect number of integrations per exposure1only allowed value
Science Exposures
Primary Channelselect primary channelchoose from list
Dither Specifications


Dither Typeselect dither typechoose from list

Optimized Forselect type of science dither optimized forPOINT SOURCE, EXTENDED SOURCE
Directionselect direction of dither patternPOSITIVE, NEGATIVE




Simultaneous Imaging

select if simultaneous imaging requiredYES, NO
Imager Subarrayselect subarray for Imagerchoose from listonly if Simultaneous Imaging = YES
Grating Wheel Directionselect wheel directionchoose from list
Exposure Specifications
Detector

based on selection of Simultaneous Imaging parameter
Wavelength Rangeselect wavelength rangechoose from list
Imager Filterselect filterchoose from listonly if Simultaneous Imaging = YES
Readout Patternselect readout patternchoose 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/Ditherspecify number of times to repeat the exposure for each dither positionnumber
Ditherselect dither specificationchoose 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.

(red star) 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 SOURCEDIRECTION is set to NEGATIVE and may not be changed.
  • For DITHER TYPE=SCANDIRECTION 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.

(warning) 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

#DetectorNo. of ExposuresReadout PatternNo. of GroupsNo. of IntegrationsDither
1MRSLong[NEXP][READOUT PATTERN][NGROUPSLONG][NINTSLONG]
1MRSShortcopied from abovecopied 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

MRSLongcopied from aboveN/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=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."

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.

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.

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

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

(warning) 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 isValue of NUMBER OF GROUPS/INTEGRATIONAllowed?
FASTR1, SLOWR1, FASTGRPAVG1Not allowed (error)
FASTR1, SLOWR12Allowed with permission  (see Limited Access Parameters)
FASTGRPAVG2,3Allowed but not recommended (warning)
FASTGRPAVG>3Allowed
FASTR1, SLOWR13,4Allowed but not recommended (warning)
FASTR1, SLOWR1>4Allowed

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.

 (warning) 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)

Change log

 

  1. PROPINSTJWST-91601  Added ALL MRS and IMAGER options to Primary Channel section. Added BACKGROUND option to Optimized For section. 


 

  1. PROPINSTJWST-91592 Added GRATING WHEEL DIRECTION section.


December 16, 2022

  1. PROPINSTJWST-91569 In Number of Integrations/Exposure section, removed constraint for LAP (undoes PROPINSTJWST-91405)


July 15, 2022

  1. PROPINSTJWST-91521 Changed text color of NUMBER OF EXPOSURES/DITHER section to purple to indicate LAP, and added TSO exception to LAP.
  2. PROPINSTJWST-91545 Added SCAN dither to Dither Type section.
  3. PROPINSTJWST-87257 Updated Optimized For section to include new default behavior.


Version 17 (October 19, 2021)

  1. PROPINSTJWST-91491 Updated Readout Patterns section with new patterns; updated Table 1 and Table 2.


Version 16 (May 2, 2021)

  1. PROPINSTJWST-91406 Added table of allowable values for NUMBER OF GROUPS/INTEGRATION.
  2. PROPINSTJWST-91405 Added LAP restriction to NUMBER OF INTEGRATIONS PER EXPOSURE for values > 1 when READOUT PATTERN=SLOW. 
  3. PROPINSTJWST-91407 Added restriction that integration duration must be less than 2000 seconds.
  4. Editorial change - Anchor links fixed in parameter table by removing pagename from link.


Version 15 (September 8, 2020)

  1. PROPINSTJWST 90194  - Updated Simultaneous Imaging section to disallow TSO SR with Simultaneous Imaging.
  2. 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)

  1. PROPINSTJWST-91438 - Updated Readout Pattern section to indicate FAST is the default.


Version 13 (December 19, 2019)

  1. PROPINSTJWST-87257 - Added developer note to the Direction section.


Version 12 (September 23, 2019)

  1. PROPINSTJWST-91395 - added new Acq Readout Pattern options.


Version 11 (June 7, 2019)

  1. PROPINSTJWST-91381 - updated Acquisition Number of Groups/Integration section.


Version 10 (April 18, 2019)

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


Version 9 (December 21, 2018)

  1. PROPINSTJWST-91122 - Added developer note  in Acquisition Target section restricting acquisition target options for fixed vs. solar system observations.
  2. PROPINSTJWST-87189 - removed SLOW option from acq readout


Version 8 (August 14. 2018)

  1. PR 89798 - Updated Acquisition Number of Groups/Integration section.
  2. PR 90970 - revised warning to Wavelength Range section.


Version 7 (May 14, 2018)

  1. PR 89879 - NO PARALLEL special requirement required for external observations with NEXP>1, added red note and developer note.
  2. PR 89323 - Updated red notes in Number of Groups/Integration for FASTGRAVP
  3. PR 86951 - added restricted filters and updated developer note Filter Name section


Version 6 (December 26, 2017)

  1. PR 88480 - revised the WAVELENGTH parameter
  2. PR 89483 - added restriction on Acq Target for SS observations
  3. PR 86278 - added option for no target acquisition


Version 5 (September 27, 2017)

  1. PR 88372 - revised the WAVELENGTH parameter
  2. PR 87895 - updated Exposure field labels to Groups/Integration and Integrations/Exposure
  3. PR 88896 - made TA Number of Groups/Integration be a picklist


Version 4 (May 11, 2017)

  1. PR 87747 - revised Readout Pattern for wait period


Version 3 (December 20, 2016)

  1. PR 80734 - added Number of Exposures parameter
  2. PR 85174 - revised Dither Types
  3. PR 85823 - added Primary Channel parameter
  4. PR 85925 - added simultaneous MIRI imaging
  5. PR 85925 - added restrictions on Readout Pattern, Num Groups
  6. PR 85925 - added default for Num Ints
  7. PR 85608 - updated TA parameters
  8. PR 85929 - added Imager Subarray restriction
  9. PR 85863 - updated developer note for Acquisition Target
  10. PR 83015 - updated Optimized For parameter


Version 2 (July 16, 2016)

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