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

See also: NIRCam Coronagraphic Imaging, HCI 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

Coronagraphic imaging is one of 5 observing modes available with the Near Infrared Camera (NIRCam). NIRCam offers 5 coronagraphic occulting masks in the focal plane and 2 Lyot stops in the pupil plane. One Lyot stop is used with the round coronagraphic masks, and the other Lyot stop is used with the bar-shaped coronagraphic masks.

NIRCam's 3 round coronagraphic masks, MASK210R, MASK335R, and MASK430R, have inner working angles IWA = 0.40", 0.63", and 0.81" (radius), corresponding to 6λ/D at 2.1, 3.35 and 4.1 μm.

The 2 bar-shaped coronagraphic masks, MASKSWB and MASKLWB, are tapered, with IWA varying by a factor of 3 along their lengths. The half widths at half maximum (HWHM) at the bar end points for the short wavelength (SW) occulter MASKSWB are 0.13" and 0.39", whereas for the long wavelength (LW) occulter MASKLWB are 0.29" and 0.87".

The observer will have control over 5 primary parameters for NIRCam coronagraphic imaging:

1. Coronagraphic mask + filter combination
2. Small grid dithering type
3. Detector subarray (FULL or the smaller subarray corresponding to each mask)  
4. Detector read out pattern and exposure time (via the number of groups and integrations).
5. Astrometric confirmation images (YES or NO to two FULL frame images before and after centering the prime target behind the mask)

Performing multiple coronagraphic observations enables PSF subtraction as described below in the PSF Reference Observations section.

Allowed values are documented in the NIRCam Coronagraphic Imaging Template parameters page.

Step-by-step APT instructions are provided below.

Generic parameters

NIRCam Coronagraphic Imaging tab

Module

See also: NIRCam Modules

NIRCam coronagraphic imaging is only available using module A (with module B as a back-up). This parameter is not user changeable. 

Coronagraphic Mask

See also: NIRCam Coronagraphic Occulting Masks and Lyot Stops

The user specifies the coronagraphic mask, depending on the target-host separation, necessary contrast, and desired filter. Selection of the Coronagraphic Mask also determines the Acq Filter parameter and the target acquisition subarray. The available coronagraphic masks are: 

• MASK210R, MASKSWB: optimized for the short wavelength (SW) channel.
• MASK335R, MASK430R, MASKLWB: optimized for the long wavelength (LW) channel.

The coronagraphic mask and associated Acq Filter is fixed. One should therefore chose the mask wisely based on which channel (filters, working angle) drives the science case.

Examples:

• MASK210R and MASKSWB allows reaching the smallest inner working angles (IWA) but the point spread function (PSF) scales with wavelength. When associated with LW filters, the larger PSF and possible saturation might yield a degraded IWA. For the longest wavelength, the smaller mask will block the core of the PSF which will feature strong satellite spots for an unocculted coronagraphic PSF. This can be checked with the ETC.
  
• MASK430R is very close to the gap between SW detectors and thus will yield a very limited field of view.
  
• MASKLWB only: there is a new rectangle subarray (SUB400X256) to accommodate better all filter-dependent field points along the bar. 

Target Acquisition Parameters

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

Target acquisition is required for coronagraphic imaging. This section specifies the Target ACQ and Acq Exposure Time.

Target ACQ

The user specifies the Acq Target and the Acq Target Brightness.

The Acq Filter is determined by the choice of the coronagraphic mask and it is not user changeable (F210M for the SW occulters MASK210R and MASKSWB, and F335M for the LW occulters MASK335R, MASK430R, and MASKLWB).

Acq Target

The selected Acq Target may be either the same as the science target or any other target defined in the APT file.

Acq Target Brightness

1. FAINT
2. BRIGHT

The user selects the Acq Target Brightness parameter as a function of the target magnitude in the Acq Filter. If BRIGHT is chosen, the target will be imaged through a neutral density (ND) square. BRIGHT should be used for targets with magnitudes brighter than approximately 8.2 mag (F210M) and 6.8 mag (F335M). 

Acq Exposure Time

See also: Understanding JWST Exposure Times

The Acq Exposure Time fields specify the MULTIACCUM exposure configuration. Each exposure is specified by readout pattern and characteristic parameters: Acq Readout Pattern and Acq Groups/Int.

Acq Readout Pattern

All 9 NIRCam readout patterns are available for target acquistion: RAPID, BRIGHT1, BRIGHT2, SHALLOW2, SHALLOW4, MEDIUM2, MEDIUM8, DEEP2, and DEEP8.

Acq Groups/Int 

This parameter defines the number of groups during an integration. The user can select one of the following options: 3, 5, 9, 17, 33, 65. 

Note that target acquisition images are taken using the 128² (SW) or 64² (LW) subarray. For this reason, the number of groups per integration is not limited to 10 as in the astrometric confirmation image and science exposure.

Acq Integrations/Exp, Acq Total Integrations, and Acq Total Exposure Time are not user changeable. For target acquisition, Acq Integrations/Exp is always 1.

Astrometric Confirmation Image Parameters

Obtain astrometric confirmation images?

If Yes is selected, confirmation images are taken. These are 2 identical exposures returning data from either all 4 SW detectors or the single LW detector. Images are taken before and after the science exposures. The first one is taken before and the second taken after the pointing adjustment that moves the target from the target acquisition position to the location behind the selected coronagraphic mask. The filter for confirmation images is the same as the target acquistion filter in Acq Filter (F210M for SW and F335M for LW).

Conf. Exposure Time

The user configures the astrometric confirmation image exposure time by setting the following parameters: Conf. Readout Pattern, Conf. Groups/Int, and Conf. Integrations/Exp. The maximum number of groups per integration is 10. The resulting exposure time (not user changeable) is displayed in Conf. Total Exposure Time. Note that Conf. Total Dithers and Conf. Total Integration are not user changeable. For the astrometric confirmation image Conf. Total Dithers is always 1. 

Science Exposures

Subarray

See also: NIRCam Detector Subarrays

NIRCam coronagraphic imaging supports observations using the full frame or a smaller subarray. Subarrays reduce data volumes and readout times, enabling rapid observations of bright objects without saturation. If one of the SW masks is being used, data will be collected with all 4 SW detectors if Subarray FULL is used, or with a single appropriate SW detector when using a smaller subarray (SUB640A210R on the A2 detector for the occulter MASK210R, SUB640ASWB on the A4 detector for the occulter MASKSWB). If one of the LW masks is being used, data will be collected on the LW detector. Choices for the Subarray parameter are: FULL, SUB640 (for the SW channel), and SUB320 (for the LW channel).

Table 1. NIRCam coronagraphic imaging array and subarray properties

Dither Pattern

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

NIRCam coronagraphic imaging supports various small grid dithers. Dither Pattern values available for the round-shaped coronagraphic masks (MASK210R, MASK335R, and MASK430R) are:

Table 2. Dither patterns for round-shaped coronagraphic masks (MASK210R, MASK335R, and MASK430R)

DITHER PATTERN values available for the bar-shaped coronagraphic masks (MASKSWB and MASKLWB) are:

Table 3. Dither patterns for bar-shaped coronagraphic masks (MASKSWB and MASKLWB)

Filters and exposures

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

The user specifies the Filters (Short Filter and Long Filter since Cycle 2) for the scientific observations. Available filters are a function of the chosen coronagraphic mask. The scientific exposure is configured by setting the readout patterns and characteristic parameters: Readout Pattern, Groups/Int, and Integrations/Exp. The Groups/Int parameter is limited to 10 for all readout patterns except DEEP2 and DEEP8, which allow up to 20.

Total Dithers and Total Integrations are not user changeable and they reflect the values selected in the Dither Pattern and Integrations/Exp fields. 

The resulting exposure time for each filter is displayed in Total Exposure Time.

PSF reference observations

See also: NIRCam Detector Subarrays

In most cases, 3 or more coronagraphic observations should be defined to support PSF subtraction:

• Science observation #1 
• Science observation #2 with the telescope rotated by a specified offset
• PSF reference star

For a detailed description of the observational strategies, see the HCI Coronagraphic Sequences article. 

This is a PSF Reference Observation

Checking this box designates the observation as a PSF reference star used for PSF subtraction. (A detailed discussion on the choice of a good PSF reference star can be found in the high-contrast imaging pages.) The observation for a PSF reference star should mirror the observation for the user's science target. Note that reference star observations have no proprietary period.

PSF Reference Observations

For a science target, uncheck the box mentioned above. This shows the PSF Reference Observations field that lists PSF reference observations that were previously specified in the same proposal; click on one of them to associate it with the science observation. 

Additional Justification

In case the user does not need any PSF Reference Observations  (e.g., for a survey of many targets where some of the science targets may serve as PSF references for others), they must check this box and explain with additional text in the science justification section of a submitted proposal the absence of PSF Reference Observations in APT. 

Other tabs

Special Requirements

A variety of observatory level Special Requirements may be chosen under the Special Requirements tab.

As is often the case with coronagraphic observations, the user may specify, in the, Special Requirements panes, that the observations be in sequence and non-interruptible. To add these special requirements, select Add... in the Special Requirements field, then select Timing followed by Group/Sequence Observations Link. In the pop-up window, select observations from the Observation List and check the Sequence and Non-interruptible boxes.

Additionally, the Special Requirements parameter is where the user could specify a roll dither for their science target. To do this, click on Add... under the Special Requirements parameters field, then select Position Angle followed by PA Offset Link. From there, the user select the 2 observations to offset in position angle, and specify the Min PA offset and Max PA offset (in degrees).

Comments

The Comments field (under the Comments tab) should be used for observing notes.