MIRI External Flat Template Parameters

JWST's MIRI External Flat Engineering template, available in the Astronomer’s Proposal Tool (APT), is used for calibration observations for the MIRI instrument.  

Introduction

JWST Proposal Parameters Home

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.

These parameters are required to obtain MIRI External Flat observations. Note that this type of observation cannot be obtained as a parallel to normal science observations, but can be in parallel with slews, except where the parameter LAMP USE = OFF THEN ON, a TARGET NAME is specified, or where DITHER = TRUE.

The MIRI External Flat Engineering template consists of the following parameters:

 FieldDetails Values Notes 
General Information   
Observation Numberassign observation number

number 


Observation Labelprovide observation labeltextoptional
Observations Commentsprovide observation commentstextoptional
 Mosaic Propertiesspecify mosaic parametersnumberif needed
Special Requirementsspecify special requirementschoose from listif needed
Template Specific Information   

Target Name

select target name

choose from list

from Target list

Science Exposures
Pointing Typeselect pointing typePARALLEL, PRIME

Detector

select detector

choose from list


Imager Subarray

select the subarray

choose from list

 

Dither Patterns
Ditherselect if Dither is desired TRUE, FALSE
Dither Typeselect dither typechoose from list
Starting Setspecify starting set number for 4-point-sets
Number of Setsspecify number of sets number for 4-point-sets
Optimized Forselect type of science POINT SOURCE, EXTENDED SOURCEfor 4-point-sets
Directionselect direction Positive, Negative  for 4-point-sets
Pointssupply a list of pointsi.e. 3, 5, 7-9, 15-19for SPARSE CYCLING
Starting Pointspecify starting point1, 2, 3,..., 310, 311for CYCLING
Number of Pointsspecify number of points4, 5, 6, ...for CYCLING
Pattern Sizeselect pattern sizechoose from listfor  SPARSE-CYCLING, CYCLING, or REULEAUX only

Lamp Use

select if observation with lamp off is desired

choose from list


Grating Wheel Direction

select wheel direction

choose from list

 

Filter

select filter

choose from list

for DETECTOR = IMAGER OR ALL

Wavelength1&4, Wavelength 2&3

select wavelength range

choose from list

for DETECTOR = MRS or ALL

Readout Pattern

select a readout pattern

choose from list


Number of Groups/Integrationspecify number of groups per integrationnumber 
Number of Integrations/Exposurespecify number of integrations per exposurenumber 

Number of Exposures/Dither

specify number of times to repeat the flat exposure at each dither position

number

for DITHER=TRUE

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, Mosaic Properties, and Special Requirements.

Target Name 

Select the TARGET NAME from the list of targets previously entered (see list of targets) or select NONE. If POINTING TYPE=PARALLELTARGET NAME=NONE.

Science Exposures

Pointing Type

POINTING TYPE = PARALLEL (default), PRIME

This parameter enables the user to control whether the data will be obtained in parallel like other calibrations, or as a primary observation like regular science.

Note for developers: This field is not saved directly into the database.

If PRIME, make TARGET NAME required, make the default “None Selected,” and remove the NONE option (so the user is prompted to select a target). Give an error if any PARALLEL special requirement is present.

If PARALLEL, set TARGET NAME = NONE (not changeable), set DITHER=FALSE,  hide the DITHER options, set LAMP USE = ON ONLY, and add a PARALLEL SLEW ONLY special requirement. Give an error if the PARALLEL SLEW ONLY special requirement is not present.

Detector 

DETECTOR [DETECTOR] = IMAGER, MRS, ALL

This parameter specifies the detector array(s) on which data will be collected. If IMAGER is selected, data is collected on the single Imager detector array. If the selection is MRS, data is collected on both of the IFU detector arrays.  When the selection is ALL, data is collected from all three detector arrays.

Note for developers: The following tables show what should be displayed in the GUI, along with the appropriate commanding name for the database, for each value of DETECTOR.

 

Imager






#

Filter

Readout Pattern

No. of Groups/Integration

No. of Integrations/Exposure

No. of Exposures/Dither

1

[FILTER]

READOUT PATTERN

NGROUPS

NINTS

[NEXP]

 

MRS

#

Detector

Wavelength 1   & 4

Wavelength 2   & 3

Readout   Pattern

No. of Groups/Integration

No. of Integrations/Exposure

No. of   Exposures/Dither

1

MRSLong

[WAVELENGTH_1_4]

[WAVELENGTH_2_3]

READOUT   PATTERN

NGROUPSLONG

NINTSLONG

[NEXP]

1

MRSShort

copied from above

copied from above

copied from above

NINTSLONG

NINTSSHORT

copied from above

 

ALL

#

Detector

Filter

Wavelength 1   & 4

Wavelength 2   & 3

Readout   Pattern

No. of Groups/Integration

No. of   Integrations/Exposure

No. of   Exposures/Dither

1

Imager

[FILTER]

N/A

N/A

[READOUT PATTERN]

[NGROUPS]

[NINTS]

[NEXP]

1

MRSLong

N/A

[WAVELENGTH_1_4]

[WAVELENGTH_2_3]

[READOUT   PATTERN LONG]

[NGROUPSLONG]

[NINTSLONG]

copied from   above

1

MRSShort

N/A

copied from above

copied from above

[READOUT   PATTERN SHORT]

[NGROUPSSHORT]

[NINTSSHORT]

copied from   above

Imager Subarray  

IMAGER SUBARRAY [SUBARRAY] = FULL, BRIGHTSKY, SUB256, SUB128, SUB64, SLITLESSPRISM, MASK1550, MASK1140, MASK1065, MASKLYOT

For DETECTOR = IMAGER or DETECTOR = ALL specify the choice of subarray. This parameter specifies the region of the detector that is to be read out (see Table 1).

The value of SUBARRAY for the MRS detectors will always be FULL and will be set to that value by the scripts.

Table 1. Subarrays for MIRI Imager and ALL Flats

Subarray

Rows

Columns

Light Sensitive Rows

Light Sensitive Columns

FULL

1024

1032

600

1016

BRIGHTSKY

512

968

512

512

SUB256

256

668

256

664

SUB128

128

136

128

132

SUB64

64

72

64

68

SLITLESSPRISM

416

72

416

68

MASK1550

224

288

224

256

MASK1140

224

288

224

256

MASK1065

224

288

224

256

MASKLYOT

304

320

304

288

Note for developers: users can specify one or more combinations of the parameters below for FLATs.

Dither Patterns

Some MIRI External Flat observations will require dithering; see MIRI Dithering for details.

Dither  

DITHER = TRUE, FALSE

This field indicates if dithering is desired. When set to TRUE, the following fields need to be specified. (warning) If POINTING TYPE = PARALLEL, the DITHER options are not available. 

Dither Type  

DITHER TYPE [PATTERN_TYPE] =  4-POINT-SETS (default), 2-POINT, SPARSE-CYCLING, CYCLING, REULEAUX, CYCLING-MICRO, MRS 4-POINT, MRS 2-POINT, LFLAT-CORON1065, LFLAT-CORON1140, LFLAT-CORON1550, LFLAT-CORONLYOT, PFLAT-CORON1065, PFLAT-CORON1140, PFLAT-CORON1550, PFLAT-CORONLYOT 

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

For DETECTOR=MRS, MRS 2-POINT and MRS 4-POINT are the only dither types allowed.

For DETECTOR=ALL, Coron PFLAT and LFLAT dithers are not allowed.


4-point-sets    

This pattern is based on an overall set of 40 points that are grouped into sets of 4 . 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 based on the filter bandpass and setting of OPTIMIZED FOR. These are the five special cases:

  1. OPTIMIZED FOR = EXTENDED SOURCE and SUBARRAY = SUB128
  2. OPTIMIZED FOR = EXTENDED SOURCE and SUBARRAY = SUB256
  3. OPTIMIZED FOR = POINT SOURCE, SUBARRAY = SUB64, SUB128, or SUB256 and FILTER = SHORT
  4. OPTIMIZED FOR = POINT SOURCE, SUBARRAY = SUB64 and FILTER = LONG
  5. OPTIMIZED FOR = POINT SOURCE, SUBARRAY = SUB128, or SUB256 and FILTER = LONG

where:

  • SHORT FILTERS = OPAQUE, FLENS, F560W, P750L, F770W, F1000W,F1065C, F1130W, F1140C
  • LONG FILTERS = F1280W, FND, F1500W, F1550C, F1800W, F2100W, F2300C, F2550W, F2550WR

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 for developers: 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 for developers: multiply this number by 4 to get the number of index points to use.

Optimized For  

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

Select the type of science that the dither is optimized for. 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 for developers: 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. For DITHER TYPE=MRS 2-POINT or MRS 4-POINT, if OPTIMIZED FOR=EXTENDED SOURCEDIRECTION must be NEGATIVE

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

Note for developers: see Appendix F1 for dithering details.

2-point 

This is a simple 2-point pattern.

Sparse Cycling 

The Sparse-Cycling pattern uses the same list of 311 pointing positions as described for Cycling below, 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).

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.

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

  Table 2. Allowed Dither Types and Patterns Sizes by Subarray 

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:
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.
Cycling-micro

The Cycling-micro pattern is a sub-pixel dither pattern used in checking Point Spread Function during commissioning.

Lamp Use  

LAMP USE = OFF THEN ON, ON ONLY, OFF ONLY

This field indicates if the calibration is to be executed twice; first with the calibration lamp OFF, then with the calibration lamp ON. This is done in order to permit subtraction of external objects from the lamp on data.  Note that if OFF THEN ON is requested, you will be prompted separately for the NUMBER OF INTEGRATIONS and NUMBER OF GROUPS for the OFF exposures and the ON exposures. (warning) If POINTING TYPE = PARALLEL, LAMP USE=ON ONLY.

Note for developers: If LAMP USE = ON ONLY, then populate Lamp Power field in the exposure spec [LAMP_POWER] with ON. If LAMP USE = OFF THEN ON, then populate Lamp Power field in the exposure spec [LAMP_POWER] with all the OFF exposures then all the ON exposures. The same value of READOUT PATTERN should be used for the lamp off exposures as was specified for the lamp on exposures.

Maximum lamp on time

(warning)  The Lamp On Time for an observation is limited to 7080 seconds for one lamp, or 3300 seconds for both lamps. The number of lamps depends on the selected DETECTOR: One lamp for IMAGER or MRS, and both lamps for ALL. Maximum Lamp On Time is defined in the PRD observing_limitations table as max_lamp_on_duration_miri_single and max_lamp_on_duration_miri_dual.

(warning) Observations that use a lamp (LAMP USE = OFF THEN ON or ON ONLY) must fit into a single visit.

Grating Wheel Direction

GRATING WHEEL DIRECTION=NEUTRAL, FORWARD, REVERSE

 Select the direction of rotation for the MIRI grating wheel (available only for DETECTOR=MRS). 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, specify the FILTER (for DETECTOR = IMAGER or ALL), WAVELENGTH (for DETECTOR = MRS or ALL), READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION, NUMBER OF INTEGRATIONS/EXPOSURE, and the NUMBER OF EXPOSURES/DITHER.

Filter  

For DETECTOR = IMAGER or DETECTOR = ALL, select the name of each FILTER (see Table 2) you wish to use.

Table 2. Filters Available for MIRI Imager External Flat Observations

Filter

Center Wavelength λ0 (mm)

Filter Bandpass Δλ (mm)

OPAQUE

Blackened blank


FLENS

N/S

N/S

F560W

5.6

1.2

F770W

7.7

2.2

F1000W

10.0

2.0

F1065C

10.7

0.5

F1130W

11.3

0.7

F1140C

11.4

0.6

F1280W

12.8

2.4

F1500W

15.0

3.0

F1550C

15.5

0.8

F1800W

18.0

3.0

F2100W

21.0

5.0

F2300C

23.0

4.6

F2550W

25.5

4.0

F2550WR

25.5

4.0

FND

13

10

P750L

7.5

~9

Wavelength  

WAVELENGTH1&4 = SHORT (A), MEDIUM (B), LONG (C)

WAVELENGTH2&3 = SHORT (A), MEDIUM (B), LONG (C)

For DETECTOR = MRS or DETECTOR = ALL select each pair of wavelength region (see Table 3) you wish to use for channels 1 and 4, and for channels 2 and 3.

Table 3. Wavelength Regions Available for MIRI MRS Flat Observations 

Wavelength RegionWavelength Ranges Δλ(mm)Maximum number of integrations

SHORT (A)

4.87-5.82

7.45-8.90

11.47-13.67

17.54-21.10

TBD

MEDIUM (B)

5.62-6.73

8.61-10.28

13.25-15.80

20.44-24.72

TBD

LONG (C)

6.49-7.76

9.94-11.87

15.30-18.24

23.84-28.82

TBD

Readout Pattern  

READOUT PATTERN [READOUT PATTERN] =  FASTR1, FASTR100, SLOWR1, FAST, SLOW

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

(warning) FASTR100 is allowed only when SUBARRAY=SUB64

(warning) SLOW and SLOWR1 are allowed only when SUBARRAY=FULL and DETECTOR=IMAGER

Number of Groups/Integration   

NUMBER OF GROUPS/INTEGRATION specifies the number of groups in an integration. The default value is 4. (warning) Values 1-3 are allowed but not recommended (warning).

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

Number of Integrations/Exposure   

This field specifies the NUMBER OF INTEGRATIONS/EXPOSURE to be obtained.

Number of Exposures/Dither   

NUMBER OF EXPOSURES/DITHER [NEXP] specifies the number of times the flat exposure is to be repeated. The default value is 1.

Change log

 

  1. PROPINSTJWST-91611 Added GRATING WHEEL DIRECTION section.


Version 14 (February 14, 2022)

  1. PROPINSTJWST-90292 Added PFLAT and LFLAT dither types.
  2. PROPINSTJWST-90292 Added constraint to DIRECTION for MRS dithers


Version 13 (January 20, 2022)

  1. PROPINSTJWST-91506 Added PFLAT and LFLAT dithers to Dither Type section.


Version 12 (October 19, 2021)

  1. PROPINSTJWST-91491 Updated Readout Patterns section with new patterns.
  2. PROPINSTJWST-89765 Added Maximum Lamp On Time to Lamp Use section.


Version 11 (August 19, 2021)

  1. PROPINSTJWST-89765 Added max lamp time limits to Lamp Use section.


Version 10 (May 4, 2021)

  1. PROPINSTJWST-91407 Added restriction that integration duration must be less than 2000 seconds.


Version 9 (August 21, 2020)

  1. PROPINSTJWST-91467 Updated Target Name section to include TARGET NAME=NONE.


Version 8 (April 18, 2019)

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


Version 7 (July 23, 2018)

  1. PR 79707 -  Added Pointing Type section, updated Target Name and Lamp Use sections


Version 6 (May 11, 2018)

  1. PR 87837 - Added Cycling-micro dither pattern


Version 5 (March 23, 2018)

  1. PR 88903 - added additional dither options
  2. PR 88903 - added Lamp Off Only option


Version 4 (September 27, 2017)

  1. PR 88372 - revised developer note on Detector for MRS/ALL
  2. PR 83845 - added note about use of readout pattern when Subarray not Full
  3. PR 87895 - updated Exposure field labels to Groups/Integration and Integrations/Exposure


Version 3 (January 17, 2017)

  1. PR 83015 - revised Optimized For parameter
  2. PR 86352 - revised Dithers
  3. PR 86632 - revised restrictions on Dithers


Version 2 (December 14, 2016)

PR 85922 - revised the name of the SUBPRISM subarray to be SLITLESSPRISM

Editorial - for DETECTOR=ALL table, made IMAGER the first item.


Version 1 (November 07, 2016)

This is the converted Word File from Chapter 19