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 | optional | |
| 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, Optional ETC ID, Mosaic Properties, and Special Requirements.
Science Exposures
Subarray
SUBARRAY [SUBARRAY] = FULL, BRIGHTSKY, SUB256, SUB128, SUB64, SUB128_IP, SUB64_IP,SLITLESSPRISM, SUBSLIT, SLITLESSPRISM_IP, SLITLESSPRISM_IPS
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
see Dithers in the MIRI Imaging APT Template article
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 dither type specifies dithers in sets of four. Dithers depend on the selected subarray as described below.
For SUBARRAY = FULL, BRIGHTSKY, or SUBSLIT, dithering is based on sets of 40 points. There are three sets of 40 points defined (each scaled for a different purpose):
- one for extended sources (regardless of filter)
- one for point sources scaled for the shorter wavelength filters: F560W, F770W, F1000W, F1130W
- one for point sources scaled for the longer wavelength filters: F1280W, F1500W, F1800W, F2100W, or F2550W
Within each set of 40 points, dither points are grouped into 4 point sets, arranged in a sequence across the subarray which is performed in order (for details and diagrams, see 4 Point Sets). Options include:
- You may use up to 10 sets by specifying Number of Sets.
- You may start the sequence at a different set by specifying Starting Set.
- You may reverse the direction of the sequence by specifying Direction.
For SUBARRAY = SUB64x, SUB128x, SUB256, or SLITLESSPRISMx), APT automatically selects a single set of 4 points depending on the selected SUBARRAY, FILTER, and OPTIMIZED FOR. Dithers for these combinations are shown in Table 1.
Table 1. Dither Definitions Depending on Subarray and Filter
| Optimized For | Subarray | Filter | 4 point set |
|---|---|---|---|
| Extended Source | Extended source not allowed with SUB64x or SLITLESSPRISMx | not allowed | not allowed |
| Extended Source | SUB128x | any | 4-POINT-EXTENDED-128 |
| Extended Source | SUB256 | any | 4-POINT-EXTENDED-256 |
| Point Source | F560W, F770W, F1000W, F1130W | 4-POINT-SHORT-64-128-256 | |
| Point Source | SUB64x, SLITLESSPRISMx | F1280W, F1500W, F1800W, F2100W, or F2550W | 4-POINT-LONG-64 |
| Point Source | SUB128x SUB256 | F1280W, F1500W, F1800W, F2100W, or F2550W | 4-POINT-LONG-128-256 |
| 4 Point Sets from PRD MiriImagingDithers | |||
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.
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.
For certain subarrays EXTENDED SOURCE is not available (see Table 1).
| 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.
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).
Pattern Size
PATTERN SIZE [PATTERN_SIZE] = DEFAULT (default), SMALL, MEDIUM, or LARGE
This parameter applies only to CYCLING, SPARSE-CYCLING and REULEAUX and specifies the relative extent of the dither pattern (SMALL, MEDIUM, or LARGE). Options available depend on the selected SUBARRAY and DITHER TYPE as shown in Table 2.
Note that DEFAULT is a selectable option. The value of DEFAULT depends on the selected FILTER, DITHER TYPE, and SUBARRAY according to the following rules:
- For SUBARRAY = FULL, BRIGHTSKY, SUB256, and SUBSLIT, the value of DEFAULT for Cycling, Sparse Cycling and Reuleaux is LARGE.
- For SUBARRAY = SUB64x or SUB128x, the value of DEFAULT for Cycling and Sparse Cycling is SMALL (and is the only allowed PATTERN SIZE).
- For SUBARRAY - SUB64x and SUB128x subarrays, for REULEAUX the value of DEFAULT depends on the selected FILTER as shown in Table 3.
- For SUBARRAY = SLITLESSPRISMx, the value of DEFAULT for Cycling, Sparse Cycling and Reuleaux is SMALL.
Table 2. Allowed Dither Types and Patterns Sizes by Subarray
| Subarray | Dither Type | Allowed Pattern Size |
|---|---|---|
| FULL BRIGHTSKY SUB256 SUBSLIT SLITLESSPRISM SLITLESSPRISM_IP SLITLESSPRISM_IPS | Reuleaux, Cycling, Sparse Cycling | SMALL, MEDIUM, or LARGE |
SUB128x | Reuleaux | SMALL |
SUB64x | Cycling, Sparse Cycling | SMALL, |
SUB64x | Reuleaux | SMALL |
Table 3. Value of DEFAULT PATTERN SIZE with Reuleaux dithers depending on Subarray and Filter
| Value of DEFAULT | ||
|---|---|---|
| Filter | For Subarray = 128x | For Subarray = SUB64x |
| 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 allowed |
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), FASTGRPAVG8, SLOWR1, FASTGRPAVG
This field specifies the readout pattern to be used to obtain the data.
FASTGRPAVG8 is available for Cycle 6 proposals and later.
SLOWR1 and FASTGRPAVG8 are allowed only when SUBARRAY=FULL.
Number of Groups/Integration
NUMBER OF GROUPS/INTEGRATION [NGROUPS] specifies the number of groups in an integration. Allowed values are shown in Table 4.
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 4. Allowed values for NUMBER OF GROUPS/INTEGRATION
| When readout pattern is | Value of NUMBER OF GROUPS/INTEGRATION | Allowed? |
|---|---|---|
| FASTR1, SLOWR1, FASTGRPAVG, FASTGRPAVG8 | 1 | Not allowed (error) |
| FASTR1, SLOWR1, FASTGRPAVG8 | 2 | Allowed with permission (see Limited Access Parameters) |
| FASTGRPAVG | 2,3 | Allowed but not recommended (warning) |
| FASTGRPAVG | >3 | Allowed |
| FASTR1, SLOWR1, FASTGRPAVG8 | 3,4 | Allowed but not recommended (warning) |
| FASTR1, SLOWR1, FASTGRPAVG8 | >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 or SUB64_IP, 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.