MIRI Coronagraphic Imaging Template Parameters

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

The MIRI Coronagraphic 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
Special Requirementsspecify special requirementschoose from listif needed
Template Specific Information   
Target Acquisition Exposure
Target Acquisition Quadrantselect target acquisition quadrantnumbernot available when target is a background target

Target Acquisition Filter

select filterchoose from list
Acquisition Readout Patternselect acquisition readout patternchoose from list
Acquisition Number of Groups/Integrationselect number of groups per integrationnumber
Acquisition Number of Integrations/Exposureselect number of integrations per exposure1only allowed value
Coronagraphic Exposures
Background Quadrantselect background quadrantChoose from listonly  available when target is a background target
Science Observation Coronagraphic Mask/Filterselect mask/filterchoose 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 of times to repeat the exposure for each dither positionnumber

Dither Type

select dither typechoose from list
Repeat Observationspecify if repeat acq and observation neededYES, NO
PSF Reference Observations
This is a PSF Reference Observationselect checkboxcheckboxindicates the observation is a "designated PSF reference observation"
PSF Reference Observationsselect observationschoose from list
Additional Justificationselect checkbox checkboxindicates self-referenced survey; justification must be submitted with proposal

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

Target Acquisition 

The ACQUISITION TARGET parameter is used to define MIRI Target Acquisition observations. The science target must be used for target acquisition (unlike NIRCam Coronagraphic Imaging, where an offset target may be used). The exception is when the target is a background target for which target acquisition is not allowed (see Special Handling of Background Targets below). For more information on defining a target acquisition specification, see MIRI Coronagraphic Imaging Target Acquisition.

Special Handling of Background Targets

When the science target is a background target:

  • ACQUISITION TARGET is set to NONE and the other target acquisition parameters are hidden.
  • The BACKGROUND QUADRANT parameter becomes available.
  • DITHER TYPE is set to NONE (or BACKGROUND if REPEAT OBSERVATION is also selected) and cannot be changed.
  • The PSF Reference Observation section is hidden.

When the science target is linked to a background target:

 For each science or PSF observation of that science target using a distinct mask/filter, there must exist a background observation of that background target that meets all of the following criteria:

 a) The background observation must be in the proposal (error if not)

 b) The background observation should be in a SEQ NON-INT set with the science observation (warning if not)

 c) The background observation must use the same mask/filter as the science observation (error if not)

Note for developers: Target acquisition with the LYOT coronagraph will use the MASKLYOT subarray. With the 1550 4QPM will use the MASK1550 subarray. Same for 1140 and 1065.

Target Acquisition Quadrant  

TACQ QUADRANT [TACQ QUADRANT]= 1, 2, 3, 4

Select the quadrant in which the initial target acquisition will be performed. When the science target is a background target, this parameter is not available.

Target Acquisition 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, 12, 22, 36, 44, 66, 86, 98

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.

Coronagraphic Exposures

For the exposures to be executed, specify the MASK/FILTER, READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION, NUMBER OF INTEGRATIONS/EXPOSURE, and theNUMBER OF EXPOSURES/DITHER.For more information on defining an exposure specification, see  Exposure time in the MIRI Coronagraphic APT Template article. Optional DITHER TYPE and REPEAT OBSERVATION may also be selected.   

Note for developers: Observations with this template must fit into a single visit. If more than one visit is created for an observation, give an error.

Background Quadrant  

BACKGROUND QUADRANT [BACKGROUND QUADRANT]= 1, 2, 3, 4

Select the quadrant in which the background target will be placed. This parameter is only available when the science target is a background target.

CORONAGRAPHIC MASK[CORON]/FILTER[FILTER] = 4QPM/F1065C, 4QPM/F1104C, 4QPM/F1550C, LYOT/F2300C

Select the coronagraphic mask  and filter  combination you wish to use to obtain the data; for the mask properties, see MIRI Coronagraph Masks, while for the filter bandpasses, see Coronagraphic filters in MIRI Coronagraphic Imaging.

Note for developers: The following SUBARRAY values are used for the specified mask: 4QPM/F1065C - MASK1065, 4QPM/F1104C- MASK1140, 4QPM/F1550C - MASK1550, and LYOT/F2300C - MASKLYOT.

Note for developers: for now, only 1 mask/filter can be selected for an observation.  However, in the future, it may be possible to use all 4. Also, APT will need to break the selection into their component values for the scripts. Also note that only 1 exposure time per Mask/Filter will be supported.

Readout Pattern

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

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

Number of Groups/Integration

NUMBER OF GROUPS/INTEGRATION[NGROUPS] specifies the number of groups in each 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, FASTGRPAVG1Not allowed (error)
FASTR12Allowed with permission  (see Limited Access Parameters)
FASTGRPAVG2,3Allowed but not recommended (warning)
FASTGRPAVG>3Allowed
FASTR13,4Allowed but not recommended (warning)
FASTR1>4Allowed

Number of Integrations/Exposure

NUMBER OF INTEGRATIONS/EXPOSURE[NINTS] field specifies the number of times the integration is repeated in each exposure; 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) IfNUMBER OF EXPOSURES/DITHER > 1, the NO PARALLEL special requirement is required.

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 Type

DITHER  TYPE [PATTERN_TYPE] = None (default), 5-POINT-SMALL-GRID, 9-POINT-SMALL-GRID, BACKGROUND

This parameter specifies the type of dithering needed. When the science target is a background target, DITHER TYPE is set to NONE (or BACKGROUND if REPEAT OBSERVATION is also selected) and cannot be changed.

Repeat Observation

REPEAT OBSERVATION = NO (default), YES

If REPEAT OBSERVATION=YES:

  • If an ACQUISITION TARGET is selected, the target acquisition (followed by a science exposure) will be repeated starting in the quadrant diagonally across the central spot from the initial TARGET ACQUISITION QUADRANT.
  • If ACQUISITION TARGET=NONE, two exposures are executed: the first in the BACKGROUND QUADRANT, and a second exposure in the diagonal quadrant as shown in Figure 1.


Figure 1: Diagonal  Quadrants

Note for developer:

  • When TARGET ACQUISITION QUADRANT has a valid value, show the text "(with Target Acquisition in quadrant X)" where X is the value of the diagonal quadrant.
  •  Store the second TACQ QUADRANT value instead of this boolean in the database.

PSF Reference Observations

Coronagraphic observations generally have two science observations with an APERTURE PA OFFSET between them of 1-14 degrees as well as an associated PSF reference observation. These observations should be done back-to-back using the SEQUENCE NON-INT special requirement. Warnings and errors will help guide the user to correctly set up these links. When the target is a background target, the PSF Reference Observations parameters are not displayed.

This is a PSF Reference Observation

Choosing this option indicates the observation is a "designated PSF Reference Observation."

 (warning) All observations with THIS IS A PSF REFERENCE OBSERVATION selected will have EXCLUSIVE ACCESS PERIOD = 0 (unless CATEGORY=COM)

Note to developer: If this option is chosen, display on the GUI "exclusive access period will be 0 months".

PSF Reference Observations

Select one or more observations from the list provided. The list includes all observations in the proposal which are observed with the same instrument, same CORONAGRAPHIC MASK, and same FILTER as the science observation. 

One or more observations must be selected, except when Proposal CATEGORY = COM, CAL, or ENGThe selected observation must be a "designated PSF Reference observation" (i.e., the THIS IS A PSF REFERENCE OBSERVATION option is selected), unless ADDITIONAL JUSTIFICATION is also selected.

Note to developer: In the list, observations should be ordered first with the ones that have This Is A PSF Reference Observation checked,  then the ones without the check.

Additional Justification

Choosing this option indicates that this observation will not have a "designated PSF Reference observation," because it is part of a self reference survey which will be described in the science justification. One or more PSF Reference Observations are still required. For more information see the "Special case: coronagraphic surveys" section in HCI APT Instructions.

Notes to developer:

  • It is an error to have nothing checked in the PSF Reference Observations. And it is still an error for a science observation to only choose other science observations and not choose a designated PSF observation, but in that case choosing the Additional Justification option replaces that error with a warning that a self reference survey must be justified.
  • If a "designated PSF Reference observation" is selected, Additional Justification is disabled.  
  • If Additional Justification  is selected, it is un-selected when a designated observation with This Is A PSF Reference Observation checked is selected


Change log

September 21, 2022

  1. PROPINSTJWST-91552 Updated changes related to TA=NONE in multiple sections.


September 9, 2022

  1. PROPINSTJWST-91552 Added BACKGROUND QUADRANT section. Updated Special Handling of Background Targets section.


July 15, 2022

  1. PROPINSTJWST-91521 Changed text color of NUMBER OF EXPOSURES/DITHER section to purple to indicate LAP.


May 19, 2022

  1. PROPINSTJWST-91518 Added red note in PSF Reference Observation section documenting PSF Reference Observation is required except for COM, CAL and ENG.


Version 14 (October 19, 2021)

  1. PROPINSTJWST-91491 Updated Readout Patterns section with new patterns; updated Table 1.
  2. PROPINSTJWST-91488 Added user facing red warning to PSF Reference Observations section.


Version 13 (September 18, 2021)

  1. PROPINSTJWST-91488 Added user facing red warning to PSF Reference Observations section.


Version 12 (May 2, 2021)

  1. PROPINSTJWST-91406 Added table of allowable values for NUMBER OF GROUPS/INTEGRATION.
  2. PROPINSTJWST-91407 Added restriction that integration duration must be less than 2000 seconds.
  3. Anchor links fixed in parameter table by removing pagename from link.


Version 11 (November 18, 2019)

  1. PROPINSTJWST-91317 Updated developer note in Repeat Observation section and Coronagraphic Exposures section.


Version 10 (September 23, 2019)

  1. PROPINSTJWST-91395 - added new Acq Readout Pattern options. Changed FASTGRAVP from LAP (purple) to non-LAP based on discussion in meeting: https://innerspace.stsci.edu/display/JPI/2017-08-31+Meeting+about+MIRI+Slow+Read+Out


Version 9 (June 7, 2019)

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


Version 8 (April 18, 2019)

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


Version 7 (December 3, 2018)

  1. PROPINSTJWST-91038 - renamed Second Exposure section to Repeat Observation; reorganized developer note.


Version 6 (August 10. 2018)

  1. PR 89798 - Updated Acquisition Number of Groups/Integration section.


Version 5 (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


Version 4 (September 25, 2017)

  1. PR 88629 - revised name of exclusive access period
  2. PR 83845 - removed SLOW from readout pattern
  3. PR 87895 - updated Exposure field labels to Groups/Integration and Integrations/Exposure 


Version 3 (February 21, 2017)

  1. PR 87071 - removed mosaic option 
  2. PR 83117 - added PSF Reference Observation section


Version 2 (November 14, 2016)

  1. PR 83365 - added TA Quadrant parameter
  2.  PR 83365 - added Second Exposure parameter
  3. PR 80734 - added Number of Exposures parameter  
  4.  PR 85608 - added TA Readout Pattern, Num Groups, Num Ints
  5. PR 83373 - added small grid dither
  6. PR 85925 - added restriction on Number of Groups


Version 1 (April 27, 2016)

This is the converted Word File from Chapter 13.