Guidance is provided for astronomers preparing NIRCam coronagraphic imaging observations using the Astronomers' Proposal Tool (APT).

NIRCam coronagraphic imaging mode offers high-contrast imaging (HCI) with short-wave (SW) and long-wave (LW) filters spanning 1.82 to 5.0 µm. Three round occulting masks and 2 bar masks with corresponding Lyot stops are available with nominal inner-working angles (IWA) ranging from 0.23" to 0.61", depending on wavelength and geometry. The IWA is defined as the smallest angular separation at which a detection is possible with a throughput of 50%. 

NIRCam coronagraphy enables the highest achievable contrast with JWST (typically ~10^-6 or better at 1″ IWA and beyond) to reveal faint spatially resolved structures or point sources in the vicinity of a target of interest (star, AGN, etc.). Detections at more modest contrasts are possible at smaller IWAs with very high quality PSF subtraction. Prior to requesting coronagraphy, one should evaluate the desired and achievable contrast ratios at a given working angle or separation from the target.

Coronagraphic imaging is performed only with NIRCam's module A. (Redundant coronagraphs in module B are not presently used.) Dual-channel (i.e., SW and LW) images are recorded simultaneously, regardless of which occulting mask is used. The SW channel is considered to be the primary coronagraphic channel if the SW round or SW bar occulter is selected. Likewise, the LW channel is considered to be the primary coronagraphic channel if a LW round or LW bar occulter is selected. 

This article provides guidance for preparing NIRCam coronagraphic observations in APT, including the selections of occulting mask, NIRCam Coronagraphic Target Acquisition, PSF-reference star, etc. It complements the step-by-step instructions given in the NIRCam Coronagraphic Imaging APT Template article. 

Occulting masks and overheads

Each occulting mask has a nominal ranges of wavelength and IWA. Information needed to select the best mask(s) for particular science goals and desired image contrast is located in the NIRCam Coronagraphic Imaging and NIRCam Coronagraphic Occulting Masks and Lyot Stops articles. 

Any change of occulting mask requires a new target acquisition (TA) with associated overheads (up to 15 minutes depending on the brightness of the star).   Associated science and PSF-reference observations using one or masks must be bundled in a non-interruptible sequence to minimize wavefront mismatches between observations caused by thermal or mechanical drift. Smart Accounting will reduce the total slew times and overheads charged for such sequences.

If modest contrast is to be achieved at very small separation or semi-major axis from the science target, non-coronagraphic NIRCam imaging or NIRISS aperture masking interferometry may provide better results and/or better efficiency, as overheads associated with the standard coronagraphic sequence are large. 

Target acquisition 

See also: NIRCam Coronagraphic Target Acquisition

Signal-to-noise ratio

Target acquisition is critical for coronagraphy, as suboptimal placement of the target behind the occulting mask can dramatically decrease the resulting contrast of the images. To ensure good target placement, the signal-to-noise ratio (SNR) of the initial TA image (from which the image centroid is calculated onboard) should be > 30, regardless of the brightness of the target. Very bright targets should be acquired using a neutral density filter to avoid detector saturation. The Exposure Time Calculator should be used to ensure that the selected TA mode and exposure parameters satisfy these recommendations.

Astrometric confirmation images

If 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 (SAM) from the initial TA position to the occulting mask. 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 are not time consuming, and they can be crucial for precisely measuring 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. 

Other considerations

To facilitate the technical review of a proposal, it is good practice to indicate each target's K-band magnitudes, spectral type, and angular distance to its PSF-reference star in the comments section of the APT target template. Always report each target's parallaxes and proper motions, when available, even if they are small. Doing so minimizes the probability of unsuccessful target acquisition.

Coronagraphic observing strategy

See also: JWST High-Contrast Imaging Roadmap

Coronagraphic Visibility Tool

The available coronagraphic setups (NIRCam and MIRI) can be quickly examined with the Coronagraphic Visibility Tool (CVT). This GUI-based tool was developed to explore the visibility and allowed position angles (PAs) for a given target across the year. The allowed PAs for a particular observational epoch can only be varied by ~7º to 14º (depending on the date and object coordinates) to ensure proper orientation of the spacecraft's solar array with respect to the Sun.

The CVT allows the user to visualize the coronagraphic field of view as functions of occulting mask and location (i.e., separation and PA) of objects of interest with respect to the occulted target. Observers can use the CVT to determine (1) any PA constraints that should be imposed to avoid unintended obscuration of the field by the neutral density squares or bar occulters, and (2) any scheduling issues that may occur as a result of the selected PA constraints.

Readout modes, array sizes, and saturation

NIRCam coronagraphy utilizes many detector readout patterns and array sizes. These options are not limited by data volume or rate considerations.   

Images can be recorded with the full detector arrays or using 20" × 20" subarrays centered on the occulted target in the primary coronagraphic channel. If the SW channel is primary, then all detectors are read from a 640 × 640 pixel subarray; if the LW channel is primary, then the subarray size is 320 × 320 pixels.    Because the pixel scales of the SW and LW channels differ, the angular fields of view of the simultaneous subarray images will be different in the primary and secondary coronagraphic channels (see Figure 3 of NIRCam Coronagraphic Imaging).

It is acceptable to saturate pixels around the occulting mask, but the data processing pipeline only recovers the count rates of partially saturated pixels (i.e., pixels that saturate after the first group in an integration). The photometric accuracy and contrast ratios in these saturated regions will be less than surrounding unsaturated regions. Users must determine whether the increased sensitivity at larger (typically >1″) separations afforded from slower readout patterns (e.g., SHALLOW, MEDIUM, or DEEP) is worth the effective increase in IWA within ~1″ due to detector saturation.

If an advanced post-processing technique such as principal component analysis (PCA) will be used to boost detection limits at the smallest possible separations, then a large number (i.e, several tens) of frames must be recorded. A slower readout pattern with fewer frames and groups can limit this strategy and increase the probability of cosmic ray artifacts within the region of interest.

PSF subtraction strategy 

Following the standard coronagraphic sequence, observing the science target at 2 different roll angles and observing a PSF reference star with several small grid dither pointings is recommended. These 3 observations should be executed as a non-interruptible group or sequence in APT (using the Group/Sequence Observations Link special requirement). This strategy is recommended to allow both the angular differential imaging (ADI) and referenced differential imaging (RDI) techniques despite thermal drift of the observatory and associated wavefront and PSF variations. ADI provides optimal results at separations > 1″, while RDI allows imaging to the IWA without self-subtraction of the astrophysical signal of interest in the speckle limited regime (< 1″). 

Selection of PSF reference star

There are extensive guidelines on selecting a suitable PSF reference star, as well as how to evaluate and mitigate the effect of spectral mismatch between the science and PSF-reference targets.

Slew times and overheads can be large (~400 s for 1,000″, ~1,000s for 3°, etc.), so it might be advantageous to relax constraints on the spectral type of the PSF-reference star to reduce the total duration of the proposal.

While small grid dithers (SGD) provide the best subtraction strategy for small IWA, they can significantly increase the required total time. To save time and minimize the noise in the PSF-subtracted product, the PSF-reference star should be brighter than the science target and/or a different readout pattern should used for the PSF-reference observations. More dithered positions guarantee a higher diversity and a better PSF subtraction at small angular separations (<1") by accounting for potentially imperfect centering of either target behind the occulting mask. The choice of the SGD pattern (from 3 to 9 points) therefore depends on how challenging a program is.

ETC calculations

See also: JWST Exposure Time Calculator (ETC), HCI ETC Instructions

Separations > 1″

The ETC allows coronagraphic calculations using an optimal PSF subtraction scenario. The science target and the PSF reference stars are assumed to be centered at the exact same position behind the coronagraphic mask. While their specified spectral types can be different, the ETC accounts only for the total flux difference through the filter bandpass, not for the possible loss of contrast due to the spectral mismatch. 

The ETC accurately calculates the SNR in the background limited regime (i.e., separations > 1″) by assuming an off-axis source under the ideal contrast assumption. 

Separations < 1″

At separations nearer to the occulting masks (< 1″), the ETC yields increasingly optimistic results based upon the closest available PSFs in its limited library.  For more realistic contrast and sensitivity calculations at these separations, the Pandeia engine can be used in command-line mode to generate more realistic model PSFs from WebbPSF "on-the-fly," as well as account for positional offsets due to TA error and small grid dithers.