Instructions for designing NIRCam coronagraphic imaging observations using the Astronomer's Proposal Tool (APT) are provided in this article.

See also: NIRCam Coronagraphic Imaging, JWST High-Contrast Imaging Roadmap, HCI APT Instructions, NIRCam Coronagraphic Imaging Recommended Strategies, NIRCam and MIRI Coronagraphy of HR8799 b, NIRCam and MIRI Coronagraphy of the Beta Pictoris Debris Disk

There are 4 major components of the NIRCam Coronagraphic Imaging template in APT:

1. Generic parameters for observation and target identification
2. NIRCam Coronagraphic Imaging tab, featuring
   1. Coronagraphic occulting mask selection
   2. Target acquisition (TA) parameters
   3. Astrometric confirmation image parameters
   4. Science exposure parameters (image format, small grid dither pattern, filter, detector read out pattern, exposure time)
   5. PSF-reference observation selection
3. Special Requirements tab, which offers
   
   1. Observation links
   2. Position angle constraints
   3. Target position offsets
4. Comments tab
   

Generic parameters

NIRCam Coronagraphic Imaging tab

Module [= A]

See also: NIRCam Modules

Coronagraphic imaging is only available using NIRCam's module A. (Module B has a redundant back-up coronagraph.) This parameter is not alterable by the user. 

Occulting Mask [= MASK210R, MASKSWB, MASK335R, MASK430R, or MASKLWB]

See also: NIRCam Coronagraphic Imaging, NIRCam Coronagraphic Occulting Masks and Lyot Stops

The choice of occulting mask depends on the desired inner working angle (IWA), contrast (flux ratio), and filter set.

• If MASK210R or MASKSWB is selected, then the short-wave (SW) channel is the primary coronagraphic channel. If MASK335R, MASK430R, or MASKLWB is selected, then the long-wave (SW) channel is the primary coronagraphic channel. Although SW and LW are recorded simultaneously regardless of which occulting mask is selected, the number and type of filters allowed with each mask depends on whether the SW channel or LW channel is the primary coronagraphic channel.
• The selected mask also determines the Acq Filter parameter and the TA subarray location. These parameters are not alterable by the user. 

Target Acquisition Parameters

See also: NIRCam Coronagraphic Target Acquisition, JWST ETC NIRCam Target Acquisition

Target acquisition is required for coronagraphic imaging. This panel contains the Target ACQ and Acq Exposure Time parameter blocks.

Target ACQ

• Acq Target is selected by the user from a drop-down list of the targets defined in the APT file. In most cases, it is the same as the coronagraphic science target, but other targets may be used if the coronagraphic target is unsuitable.
  
  
• Acq Filter is determined by the choice of the occulting mask: F210M for SW occulters MASK210R and MASKSWB; F335M for LW occulters MASK335R, MASK430R, and MASKLWB. It is not alterable by the user
  
  
• Acq Target Brightness [= FAINT or BRIGHT (ND SQUARE)]
  This parameter determines whether the Acq Target will be imaged in a clear region of the coronagraph optical mount ("faint TA") or through a neutral density (ND) square ("bright TA"). It is recommended that the BRIGHT (ND SQUARE) option be used for SW-channel and LW-channel TA if the target is brighter than K = 6.3 and K = 4.7, respectively.
  
  

Acq Exposure Time

See also: Understanding JWST Exposure Times

This parameter block specifies the MULTIACCUM exposure configuration for the TA images.

• Acq Readout Pattern [= RAPID, BRIGHT1, BRIGHT2, SHALLOW2, SHALLOW4, MEDIUM2, MEDIUM8, MEDIUMDEEP2, MEDIUMDEEP8, DEEP2, or DEEP8]
  All 11 NIRCam readout patterns are available for TA imaging.
  
  
• Acq Groups/Int [= 3, 5, 9, 17, 33, or 65]
  This parameter sets the number of groups during an integration. Because TA images are obtained with 128² (SW) and 64² (LW) subarrays, the number of groups per integration is not limited to 10, as it is for astrometric confirmation and science exposures.
  
  
• Acq Integrations/Exp, i.e., the number of integrations per exposure, is set to 1 for all TA images. This parameter are not alterable by the user.
  
  
• Acq Total Integrations is computed automatically from the preceding parameters, so it is not alterable by the user.
  
  
• Acq Total Exposure Time is computed automatically from the preceding parameters, so it is not alterable by the user.
  
  
• Optional ETC ID is an optional field for documenting the Exposure Time Calculator (ETC) workbook calculation that supports the chosen TA exposure parameters.

Astrometric Confirmation Image Parameters

See also: NIRCam Coronagraph Astrometric Confirmation Images

If a precise measurement of the target's location behind the occulter is needed, full frame dual channel astrometric confirmation images may be recorded before and after the small angle maneuver to the occulter. The first image allows registration of the unocculted target with respect to fainter sources within the field of view, most of which will appear in the second image of the occulted target. These images can also be used to precisely measure the separation and position angle between the occulted target and any detected faint companions. The SW and LW confirmation images are recorded by default with the F210M and F335M filters, respectively. 

Obtain astrometric confirmation images?  [= YES or NO]

Conf. Exposure Time

See also: Understanding JWST Exposure Times

This parameter block specifies the MULTIACCUM exposure configuration for the astrometric confirmation images.

• Conf. Readout Pattern [= RAPID, BRIGHT1, BRIGHT2, SHALLOW2, SHALLOW4, MEDIUM2, MEDIUM8, MEDIUMDEEP2, MEDIUMDEEP8, DEEP2, or DEEP8]
  All 11 NIRCam readout patterns are available for astrometric confirmation imaging.
  
  
• Conf. Groups/Int [= 1, 2, 3, 4, 5, 6, 7, 8, 9, or 10]
  This parameter sets the number of groups during an integration (maximum of 10).
  
  
• Conf. Integrations/Exp [= 1, 2, 3, 4, 5, 6, 7, 8, 9, or 10]
  This parameter sets the number of integrations per exposure (maximum of 10).
  
  
• Conf. Total Dithers, i.e., the total number of dither positions, is set to 1 for all confirmation images. It is not alterable by the user.
  
  
• Conf. Total Integrations is computed automatically from the preceding parameters, so it is not alterable by the user.
  
  
• Conf. Total Exposure Time is computed automatically from the preceding parameters, so it is not alterable by the user.

Science Exposures

Subarray

See also: NIRCam Detector Subarrays

Subarray [= FULL, SUB640A210R (when MASK210R is selected), SUB320A335R (for MASK335R), SUB320A430R (for MASK430R), SUB640ASWB (for MASKSWB), or SUB400X256ALWB (for MASKLWB)]
The fields of view (FOV) of the subarrays depend upon whether the SW or LW channel is the primary coronagraphic channel. (See Figure 3 of NIRCam Coronagraphic Imaging.) The subarrays in the primary channel encompass 20″ × 20″ squares centered approximately on each occulting mask, except for MASKLWB, which features a 24″ × 15″ FOV to better accommodate the filter-dependent field points along the bar. 

Table 1.  Subarray dimensions and FOVs in primary and secondary channels.

Dither Pattern [= NONE; 5-POINT-BOX, 5-POINT-DIAMOND, 9-POINT-CIRCLE for round occulters; 3-POINT-BAR, 5-POINT-BAR for bar occulters]

See also: NIRCam Small Grid Dithers, HCI Small Grid Dithers

NIRCam coronagraphic imaging utilizes small grid dithers (SGDs), which are executed within a specified observation without repeating TA. The names of the SGD patterns reflect the number and geometry of the dither positions. The SGDs for the bar occulters are linear and perpendicular to the bar axes.

Filters

See also: NIRCam Filters for Coronagraphy, Understanding Exposure Times, HCI Coronagraphic Sequences, HCI APT Coronagraphic Sequence Examples

This parameter block specifies the filters and MULTIACCUM exposure configurations used for the simultaneous SW and LW coronagraphic science exposures for the selected occulting mask. The number and types of allowed primary- and secondary-channel filters depend on the choice of occulter, as shown in Table 1 of NIRCam Filters for Coronagraphy. 

• Short Filter [= F182M, F187N, F200W, F210M, or F212N]
  These SW filters are available with all occulters, regardless of whether the SW or LW channel is primary.
  
  
• Long Filter [= F250M, F300M, F335M, F356W, F360M, F410M, F430M, F444W, F460M, F480M for all occulters; F277W bar occulters only; F322W2 round occulters only]
  These LW filters are available with the specified occulters, regardless of whether the SW or LW channel is primary.
  
  
• Readout Pattern [= RAPID, BRIGHT1, BRIGHT2, SHALLOW2, SHALLOW4, MEDIUM2, MEDIUM8, MEDIUMDEEP2, MEDIUMDEEP8, DEEP2, or DEEP8]
  All 11 NIRCam readout patterns are available for astrometric confirmation imaging.
  
  
• Groups/Int [= 1-10 for all readout patterns; 11-20 for DEEP2 and DEEP8 only)]
  This parameter sets the number of groups during an integration (maximum of 10).
  
  
• Integrations/Exp [= Any integer that yields an exposure duration ≤ 10,000 s]
  This parameter sets the number of integrations per exposure.
  
  
• Total Dithers, is computed automatically from the choice of Dither Pattern, so it is not alterable by the user.
  
  
• Total Integrations is computed automatically from the preceding parameters, so it is not alterable by the user.
  
  
• Total Exposure Time is computed automatically from the preceding parameters, so it is not alterable by the user.
  
  
• Optional ETC ID is an optional field for documenting the Exposure Time Calculator (ETC) workbook calculation that supports the chosen science exposure parameters.
  
  

PSF Reference Observations

See also:  HCI Coronagraphic Sequences

This is a PSF Reference Observation  [toggle check mark in box]

This box must be checked for all observations of targets that will be used as references for coronagraphic-PSF subtraction of associated science images. Once checked, the other fields within the PSF Reference Observations block will disappear. No proprietary access is given to PSF-reference observations; they are immediately made publicly available. This box should not be checked for science observations, unless one must be selected to satisfy the data processing pipeline requirements for observations in a self-referenced survey. In such cases, users can provide justification for limited proprietary access to the checked observation (see Additional Justification below), which must be approved by the Time Allocation Committee (TAC).

PSF Reference Observations [check box(es) associated with the PSF-reference observation(s) desired for PSF-subtraction of the science observation by the data-processing pipeline]

All selected PSF-reference observations should be linked to the science observation via a Group/Sequence Observation Link that is accessible in the Special Requirements tab. See instructions below.

Additional Justification [toggle check mark in box]

This box should be checked if the user desires a limited proprietary period for observation(s) of targets in a self-referenced survey that have been designated as PSF-reference stars to satisfy initial data-processing pipeline requirements. If the justification submitted by the proposer is approved by the TAC, then all observations in the self-referenced survey program will remain proprietary until the investigators determine which observations are scientifically valuable and which ones are useful only as PSF references. The designated PSF-reference observations will then become publicly available. 

Special Requirements tab

Special Requirements

A variety of observatory level Special Requirements (SRs) may be implemented in this field.  

The SRs most commonly associated with coronagraphic observations are those that (1) non-interruptibly link the science and PSF-reference observations and (2) specify the position angle (PA) offsets of the coronagraphic field of view with respect to the spacecraft axes or other coronagraphic observations. To invoke these SRs, the user must first click on the Add... button, which brings up a menu of possible observational constraints, the topmost being Timing and Position Angle. 

Clicking the Timing option produces another menu of options, including the Group/Sequence Observations Link. This option is used to satisfy the requirement that the coronagraphic science observations are executed contiguously and continuously with their associated PSF-reference observations in order to minimize any changes in the optical wavefront due to thermal or mechanical drifts. Clicking the Group/Sequence Observations Link produces a window in which the desired observations can be grouped and the manner of their execution can be specified. By default, a selected group of observations can be executed in any order that the Visiting Scheduling Subsystem (VSS) determines to be most efficient. If the user wants the grouped observations to be executed in order of their ascending numerical designations in APT, then the Sequence box should be checked. To force contiguous and continuous execution of the grouped or sequenced observations, the Non-interruptible must be checked. (Note: Despite the current APT warning that the PSF-reference observations must be linked as SEQ NON-INT, this is not a requirement. In fact, if the order of execution is unimportant, the user is encouraged to use the GROUP NON-INT configuration to allow greater flexibility of scheduling and slew efficiency.) The final option to require Exclusive Use of Instrument is irrelevant for NIRCam coronagraphic imaging.

To implement a roll about JWST's optical axis between science observations (i.e., a "roll dither"), the user must select the Position Angle option followed by PA Offset Link. A window appears in which the minimum and maximum PA offsets (in degrees) can be designated with respect to another observation in the program. The user can also select the PA Reference axis (spacecraft V3 axis or NIRCam aperture), but this choice is irrelevant for relative PA offsets.

If using a bar occulter to image known companions or extended emission near a bright target, the user should specify a range of absolute PAs that will avoid obscuration of the companion or extended emission by the bar. To do so, select the Position Angle option followed by PA Range. A window appears in which the minimum and maximum values of the PA (in degrees) can be designated with respect to either the coronagraphic aperture or the spacecraft V3 axis. The orientations of NIRCam's apertures and the V3 axis differ by less than 0.1°, so the choice of reference axis is inconsequential for most coronagraphic targets.

Comments tab

This field should be used for observing notes.