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.
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 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:
| 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 | |||
| Science Exposures | |||
| Subarray | select subarray | choose from list | |
| Dither Specifications | |||
| Dither Type | select dither type | choose from list | |
| Starting Point | select starting point | 1, 2, 3,..., 310, 311 | for CYCLING only |
| Number of Points | select number of points | 4, 5, 6, ... | for CYCLING only |
| Points | supply a list of points | i.e. 3, 5, 7-9, 15-19 | for SPARSE-CYCLING only |
| Starting Set | specify starting set | 1-10 | for 4-POINT-SETS only |
| Number of Sets | specify number of sets | 1-10 | for 4-POINT-SETS only |
| Optimized For | select type of science dither optimized for | POINT SOURCE, EXTENDED SOURCE | for 4-POINT-SETS only |
| Direction | select direction of dither pattern | POSITIVE, NEGATIVE | for 4-POINT-SETS only |
| Pattern Size | select pattern size | choose from list | for CYCLING, SPARSE-CYCLING, or REULEAUX only |
| Filter(s) | select filter name(s) | choose from list | |
| 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 to times repeat the exposure for each dither point | number | |
| Dither | select dither specification | choose 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.
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; 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; the range is 1-10.
Note to developer: multiply this number by 4 to get the number of index points to use.
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. If SUBARRAY=SUB64 then OPTIMIZED FOR = EXTENDED SOURCE is not available.
| 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). 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
| Subarray | Dither Type | Allowed Pattern Size |
|---|---|---|
| FULL | Reuleaux, Cycling, Sparse Cycling | SMALL, MEDIUM, or LARGE |
| BRIGHTSKY | Reuleaux, Cycling, Sparse Cycling | SMALL, MEDIUM, or LARGE |
| SUB256 | Reuleaux, Cycling, Sparse Cycling | SMALL, MEDIUM, or LARGE |
| SUB128 | Reuleaux | SMALL, MEDIUM, or LARGE |
| SUB128 | Cycling, Sparse Cycling | SMALL |
| SUB64 | Reuleaux | SMALL, MEDIUM |
| SUB64 | Cycling, Sparse Cycling | SMALL |
| SLITLESSPRISM | Reuleaux, Cycling, Sparse Cycling | SMALL, MEDIUM, or LARGE |
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 | SUB128 | SUB64 |
|---|---|---|
| F560W | LARGE | MEDIUM |
| F770W | LARGE | MEDIUM |
| F1000W | LARGE | SMALL |
| F1130W | LARGE | SMALL |
| F1280W | MEDIUM | SMALL |
| F1500W | MEDIUM | SMALL |
| F1800W | MEDIUM | SMALL |
| F2100W | MEDIUM | SMALL |
| F2550W | MEDIUM | not 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.
SLOWR1 is allowed only when SUBARRAY=FULL.
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.
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 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] 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.
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)."
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.