MIRI Imaging Template Parameters

JWST's MIRI Imaging 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 Imaging template is to be used for all observations using the imaging 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 Imaging APT Template article.

The MIRI Imaging 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   
Science Exposures
Subarrayselect subarraychoose from list
Dither Specifications
Dither Typeselect dither typechoose from list
Starting Pointselect starting point1, 2, 3,..., 310, 311for CYCLING only
Number of Pointsselect number of points4, 5, 6, ...for CYCLING only
Pointssupply a list of pointsi.e. 3, 5, 7-9, 15-19for SPARSE-CYCLING only
Starting Setspecify starting set1-10for 4-POINT-SETS only
Number of Setsspecify number of sets1-10for 4-POINT-SETS only
Optimized Forselect type of science dither optimized forPOINT SOURCE, EXTENDED SOURCEfor 4-POINT-SETS only
Directionselect direction of dither patternPOSITIVE, NEGATIVEfor 4-POINT-SETS only
Pattern Sizeselect pattern sizechoose from listfor CYCLING, SPARSE-CYCLING, or REULEAUX only

Filter(s)select filter name(s)choose from list
Readout Patternselect readout patternchoose from list
Number of Groups/Integrationspecify number of groups per integrationnumber
Number of Integrations/Exposurespecify number of integrations per exposurenumber
Number of Exposures/Ditherspecify number to times repeat the exposure for each dither pointnumber
Ditherselect dither specificationchoose from list

If the TIME SERIES OBSERVATION special requirement is selected, you must also select the NO PARALLEL requirement.

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. 

Science Exposures

Subarray 

SUBARRAY [SUBARRAY] = FULL, BRIGHTSKY, SUB256, SUB128, SUB64, SLITLESSPRISM

This parameter specifies the region of the detector that is to be read out. For more details about these subarrays, see Subarray in the MIRI Imaging APT Template article..

Dither Specifications  

Most MIRI Imaging observations will require dithering; for details see Dithers in the MIRI Imaging APT Template article.

Dither Type 

DITHER TYPE [PATTERN_TYPE] =  CYCLING, REULEAUX, 2-POINT, 4-POINT-SETS, SPARSE-CYCLING

This parameter specifies the   type of dither to be executed. All Dither Types except for 2-POINT require additional parameters.

Cycling 

The Cycling pattern consists of a list of 311 pointing positions where the x- and y-offset distributions (from the central position) are well-described by a Gaussian; the pattern is drawn from the Spitzer IRAC Cycling pattern. Observations may begin at any position in the cycling pattern and include an arbitrary number of dithers. 

Starting Point 

STARTING POINT [STARTING_POINT] = 1, 2, 3, …, 310, 311

This parameter specifies the index of the first dither position.

Number of Points

NUMBER OF POINTS [NUMBER_OF_POINTS] = 4, 5, 6, …

This parameter specifies the number of dither positions of the cycling pattern to execute in sequence.

(warning)If the combination of STARTING POINT and NUMBER OF POINTS exceeds 312, the pattern cycles back to use points 1, 2, 3, etc. 

No explicit maximum is set on the number of points.  The number of points, however, is effectively limited by the maximum allowed visit duration.

Reuleaux 

The Reuleaux pattern is a set of 12 dither positions that defines a Reuleaux triangle; the pattern is drawn from the Spitzer IRAC 12-point Reuleaux pattern.

2-point 

This is a simple 2-point pattern.

4-point-sets 

 This pattern is based on sets of 40 points that can be used in subsets of 4 (see 4 point patterns ).    There are three sets of 40 points defined (each scaled for a different purpose) which are available only when using SUBARRAY = FULL or BRIGHTSKY:

  •  one for extended sources (regardless of filter) 
  •  one for point sources which is scaled for the shorter wavelength filters: F560W, F770W, F1000W, F1130W 
  •  one for point sources which is scaled for the longer wavelength filters: F1280W, F1500W, F1800W, F2100W, or F2550W

 For the three smallest subarrays a particular four point set will be used automatically (so STARTING SET and NUMBER OF SETS will both need to be 1). There are different dither definitions for these five situations:

  • OPTIMIZED FOR = EXTENDED SOURCE and SUBARRAY = SUB128
  • OPTIMIZED FOR = EXTENDED SOURCE and SUBARRAY = SUB256
  •  OPTIMIZED FOR = POINT SOURCE, SUBARRAY = SUB64, SUB128, or SUB256 and FILTER = F560W, F770W, F1000W, F1130W
  •  OPTIMIZED FOR = POINT SOURCE, SUBARRAY = SUB64 and FILTER = F1280W, F1500W, F1800W, F2100W, or F2550W
  • OPTIMIZED FOR = POINT SOURCE, SUBARRAY = SUB128, or SUB256 and FILTER = F1280W, F1500W, F1800W, F2100W, or F2550W

Note to developer: OPTIMIZED FOR = EXTENDED SOURCE and SUBARRAY = SUB64 should not be allowed.

Starting Set 

Select the STARTING SET [STARTING_SET] of dither points; (warning)the range is 1-10.

Note to developer: multiply STARTING_SET  -1 by 4 and add one to get the first dither index point.

Number of Sets

Select the NUMBER OF SETS [NUMBER_OF_SETS] which is the number of 4-point dither sets; (warning)the range is 1-10.

Note to developer: multiply this number by 4 to get the number of index points to use.

 

(warning)If the combination of STARTING SET and NUMBER OF SETS exceeds 11, the pattern cycles back to use sets 1, 2, 3, etc.

Sparse Cycling 

The Sparse-Cycling pattern uses the same list of 311 pointing positions as described for Cycling above, but any sub set of the points may be specified.

Points

Type a monotonically increasing list of POINTS [POINTS] which are indices from the Cycle Table using commas and dashes (i.e. 3, 5, 7-9, 15-19).

Optimized For 

OPTIMIZED FOR [OPTIMIZED_FOR]   = POINT SOURCE (default), EXTENDED SOURCE

Select the type of science the dither is optimized for.

If a dither is created before choosing a target no default is selected. If a target is chosen before a dither is created the default is POINT SOURCE unless the target was marked EXTENDED in which case the default is EXTENDED SOURCE. (warning) If SUBARRAY=SUB64 then OPTIMIZED FOR = EXTENDED SOURCE is not available.

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

Note to developer: If the target is marked EXTENDED, change the default value to EXTENDED SOURCE.

Direction

DIRECTION [DIRECTION] = POSITIVE (default), NEGATIVE

Select the direction of the dither.  

Note to developer: DIRECTION = NEGATIVE means that the X-offset in the dither table is multiplied by -1.

Pattern Size 

PATTERN SIZE [PATTERN_SIZE] = DEFAULT (default), SMALL, MEDIUM, or LARGE

This parameter, which only applies to CYCLING, SPARSE-CYCLING  and REULEAUX, specifies the relative extent of the dither pattern (SMALL, MEDIUM, or LARGE). (warning)The choice of SUBARRAY restricts the available options for PATTERN TYPE and PATTERN SIZE as indicated in Table 1.

 Table 1. Allowed Dither Types and Patterns Sizes by Subarray

SubarrayDither TypeAllowed Pattern Size
FULLReuleaux, Cycling, Sparse CyclingSMALL, MEDIUM, or LARGE
BRIGHTSKYReuleaux, Cycling, Sparse CyclingSMALL, MEDIUM, or LARGE
SUB256Reuleaux, Cycling, Sparse CyclingSMALL, MEDIUM, or LARGE
SUB128ReuleauxSMALL, MEDIUM, or LARGE
SUB128Cycling, Sparse CyclingSMALL
SUB64ReuleauxSMALL, MEDIUM
SUB64Cycling, Sparse CyclingSMALL
SLITLESSPRISMReuleaux, Cycling, Sparse CyclingSMALL, MEDIUM, or LARGE

(warning)When the PATTERN SIZE is not specified by the user the DEFAULT pattern will be used based upon the choice of filter, pattern and subarray according to the following rules:

  • For SUBARRAY = FULL, BRIGHTSKY and SUB256, the default PATTERN SIZE for Cycling, Sparse Cycling and Reuleaux is LARGE.
  • For SUBARRAY = SUB128, and SUB64, the default (and only legal) PATTERN SIZE for Cycling and Sparse Cycling is SMALL.
  • The default values for Reuleaux for SUBARRAY = SUB128 and SUB64 vary and are listed below:
Filter
SUB128SUB64
F560WLARGEMEDIUM
F770WLARGEMEDIUM
F1000WLARGESMALL
F1130WLARGESMALL
F1280WMEDIUMSMALL
F1500WMEDIUMSMALL
F1800WMEDIUMSMALL
F2100WMEDIUMSMALL
F2550WMEDIUMnot recommended
  •  For SUBARRAY = SLITLESSPRISM, the default PATTERN SIZE for Cycling, Sparse Cycling and Reuleaux is SMALL.

Filters 

For each exposure to be executed at each position in a dither pattern, specify the FILTER, READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION, NUMBER OF INTEGRATIONS/EXPOSURE, NUMBER OF EXPOSURES/DITHER, and DITHER. For the filter bandpasses, see MIRI Filters and Dispersers. For more information on defining an exposure specification, see Filters in the MIRI Imaging APT Template article.

Filter Name 

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

Readout Pattern 

READOUT PATTERN [READOUT PATTERN] = FASTR1 (default), SLOWR1, FASTGRPAVG  

This field specifies the readout pattern to be used to obtain the data. 

(warning) SLOWR1 is allowed only when SUBARRAY=FULL.

(warning) If both SLOWR1 and either FASTR1 or FASTGRPAVG are used in the same 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. This delay is specified as miri_readout_settling_duration in the PRD observing_limitations table.

Note to developer: inform the user with a warning about settling time delay in this case.

Number of Groups/Integration

NUMBER OF GROUPS/INTEGRATION [NGROUPS] specifies the number of groups in an integration. Allowed values are shown in Table 2.

(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 2. 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] field specifies the number of times the integration is repeated; default = 1

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.

(warning)  When in coordinated parallel template (prime or parallel) or as a pure parallel, the value of NUMBER OF EXPOSURES/DITHER must be 1.

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

Note for developer: When in coordinated parallel template (prime or parallel) or as a pure parallel the max value is set to 1. The field is made uneditable in this case if the entered value is 1.

Dither 

Select the number of the dither specification previously specified.

  • A value of NONE (limited access) is required when there is a coordinated parallel observation with the NIRSS WFSS template or when the TIME SERIES OBSERVATION special requirement is used.
  • When SUBARRAY = SUB64, NONE is available and is not limited access.

Note for developers: DITHER should be a required field, and there should be no default value (i.e. do not make NONE the default). NONE should always be available when in limited access mode.

Change log

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.


Version 9 (October 19, 2021)

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


Version 8 (May 2, 2021)

  1. PROPINSTJWST-91406 Added table of allowable values for NUMBER OF GROUPS/INTEGRATION.
  2. PROPINSTJWST-91406 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.


Version 7 (April 18, 2019)

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


Version 6 (May 14, 2018)

  1. PR 89846 - Number of Exposures/Dither must be 1 for parallels; added red note and developer note.
  2. PR 89879 - NO PARALLEL special requirement required for external observations with NEXP>1, added red note and developer note.
  3. PR 89323 - Updated red notes in Number of Groups/Integration for FASTGRAVP
  4. PR 86951 = added restricted filters to Filter Name section

Version 5 (December 27, 2017)

  1. PR 88411 - added note about TSO special requirement and NO PARALLEL


Version 4 (November 24, 2017)

  1. PR 83845 - added note about readout pattern when Subarray is not Full
  2. PR 87895 - updated Exposure field labels to Groups/Integration and Integrations/Exposure
  3. PR 89289 - updated definition of Dither parameter to support value of NONE


Version 3 (May 11, 2017)

  1. PR 87747 - revised warning in Readout Pattern about wait period


Version 2 (January 16, 2017)

  1. PR 80734 - added Number of Exposures parameter
  2.  PR 83015 - revised dither
  3. PR 85925 - updated Readout Pattern, Num Groups, Num Ints
  4. PR 85929 - revised Readout Pattern for settling time
  5. PR 85922 - revised the name of the SUBPRISM subarray to SLITLESSPRISM
  6. PR 81292 - removed inconsistency in name of dither parameters


Version 1 (May 6, 2016)

This is the converted Word File from Chapter 10.