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

The NIRCam coronagraphic imaging mode offers high-contrast imaging (HCI) capabilities for a set of short and long wavelength filters covering 1.8 to 5 µm. Three round occulting masks and 2 bar masks (with corresponding Lyot stops) are available with inner-working angles (IWA) ranging from 0.13" to 0.88", depending on wavelength and geometry.

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.). Prior to requesting coronagraphy, one should evaluate the contrast regime achievable (or needed) at a given working angle or separation from the central object.

Currently, NIRCam coronagraphic imaging is limited to module A only. Starting in Cycle 2 (APT version 2022.7 and above) both short wavelength (SW) data and long wavelength (LW) data will be saved (as for regular imaging but in module A only).

This article provides guidance for preparing NIRCam coronagraphic observations in APT. It complements the step-by-step instructions given in the NIRCam Coronagraphic Imaging APT Template article. The advice below is specific to coronagraphy: choice of mask, target acquisition, choice of the PSF reference star, etc.

---

Choice of mask, overheads

Each occulting mask has a corresponding wavelength range and associated IWA. Any change of mask requires a new target acquisition (TA) with associated overheads (up to 15 minutes depending on the brightness of the star, generally longer for fainter stars).

---

Target acquisition 

See also: NIRCam Coronagraphic Imaging Target Acquisition

Signal-to-noise ratio

For coronagraphy, the TA can easily be a showstopper, directly influencing the quality of the data. A low signal-to-noise ratio (SNR) on the initial TA image can result in a suboptimal centering of the target behind the coronagraph with dramatic consequences. The recommendation for NIRCam is to adjust the TA readout pattern and parameters to achieve at least a SNR of 30 regardless of the brightness of the target. Please plan your observation using the Exposure Time Calculator. 

Very bright targets with K < 7 (Bright (ND Square) in APT) must usually be acquired using a neutral density filter as explained in NIRCam Coronagraphic Imaging Target Acquisition.

Astrometric confirmation images

TA gives users the opportunity to obtain 2 full frame images consecutively for astrometric purposes: one when the science target is still away from the mask and a second after centering the star behind the coronagraph. This allows for the retrieval of the precise position of the host when behind the mask with respect to all the background sources in the full field of view. As this is done through the same filter as the TA (F210M  for SW or F335M for LW), it is not very time consuming and can prove to be crucial to assess the relative position of a putative detected signal (companion or spatially extended structure) with respect to the host source.

---

Observing strategy: planning for coronagraphy

See also: JWST High-Contrast Imaging Roadmap

Which coronagraph (or no coronagraph)?

NIRCam's coronagraphic masks and filters allow an inner-working angle (IWA) from 0.13" to 0.88" depending on the wavelength (from 1.82 to 5 µm for this mode). The IWA is defined as the smallest angular separation at which a detection is possible with a throughput of 50%. Detections at more modest contrasts are possible at the IWA or even a bit closer in certain cases, provided there is a very high quality of PSF subtraction.

In certain cases, where a somewhat more modest contrast is to be achieved at very small separation (or semi-major axis from a host), non-coronagraphic NIRCam imaging or NIRISS aperture masking interferometry can provide better results and/or better efficiency since overheads associated with the baseline, standard coronagraphic sequence are large. 

Coronagraphic Visibility Tool and aperture PA

The choice of available coronagraphic setups (NIRCam and/or MIRI) can be quickly explored with the Coronagraphic Visibility Tool (CVT). This GUI-based tool was primarily developed to provide the visibility and allowed position angles (PAs) for a given target across the year.

The Aperture PA RANGE to maintain the spacecraft oriented with respect to the Sun corresponds to the roll angle "stroke" that is available (between ~7º and ~14º in absolute values) depending on the date and object coordinates. The right-hand plot of the CVT is very useful to also visualize the coronagraphic field of view and physical limitations (size of the mask, neutral density filter positions, orientation of the bar coronagraphs with respect to given companion or circumstellar disk PA and separation). Here are the questions one can seek answer to with the CVT: is scheduling an issue for my target? Is my preferred mask problematic?

Readout mode, window and saturation

As with other NIRCam modes, coronagraphy can make use of any of the numerous readout patterns. Since coronagraphy only makes use of NIRCam module A with a reduced detector region of interest, the readout options are not limited by data volume/rate considerations. 

In addition to reading the full frame of the module A detector, the coronagraphy mode can be operated with faster readout speed using a 20" × 20" field (640-pixel subarray for the SW detector, 320-pixel subarray for the LW detector).

While it is acceptable to saturate many pixels in the vicinity of the coronagraph, the JWST data reduction pipeline in its early versions will only be able to recover slopes of the partially saturated pixels (pixels that saturate prior to the second group in the ramp). The photometric accuracy will be suboptimal in the saturated regions, and the contrast will most likely be affected at or close to the IWA. In HCI, it is a matter of trade-offs: pushing the sensitivity by using a slower readout pattern (SHALLOW, MEDIUM, or DEEP) will allow one to detect very shallow structures in the outer, background-limited surroundings (typically >1") of the central source while losing the capability to recover optimally the innermost regions (IWA to ~1").

Moreover, if one's strategy is to use an advanced post-processing technique such as principal component analysis (PCA) to optimize the detection limits at the smallest possible separations to the host, then it is necessary to have a rather high number (several tens) of frames. Using a slow mode and saving fewer frames and groups can result in a limitation to such a strategy, in addition to increasing the probability of having cosmic rays events polluting the region of interest.

PSF subtraction strategy 

Following the standard coronagraphic sequence, we recommend observing the science target at 2 different roll angles, then slewing to observe the PSF reference star, ideally with several small grid dither pointings (5-point or 9-point). These 3 observations should be gathered in a non-interruptible sequence in APT (using the Group/Sequence Observations Link special requirement). This strategy is recommended to guarantee 2 different optimal PSF subtractions despite thermal drift of the observatory and associated wavefront and PSF variations. 

Given JWST's roll flexibility of ±5º, coronagraphic observations at 2 roll angles provide optimal results at large separations (typically 1" and further). 

The reference differential imaging (RDI) approach provided by the subsequent observation of a bright (as bright or brighter than the science target) PSF reference star with similar spectral properties should, in principle, allow one to reach the IWA of any given coronagraph and the lowest level of self-subtraction of the astrophysical signal of interest in the speckle limited regime (typically within 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 PSF reference and the target of scientific interest.

Slew times and overheads can be large (~400 s for 1,000", ~1,000s for 3°, etc.) and therefore it is sometimes better to relax constraints on the spectral type of the PSF reference star.

While small grid dithers (SGD) provide the best subtraction strategy for small IWA, they can significantly increase the required total time. To save time (as well as minimize the noise in the subtraction product), it is a good idea to use a brighter PSF reference star and possibly a different readout pattern than that used for the science target. More dithered positions guarantee a higher diversity and a better PSF subtraction at small angular separations (e.g. <1"), accounting for a somewhat imperfect centering of either the science target or the reference star. 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

1" and above

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. Also, while their spectral type can be specified to differ, the ETC only accounts for the total flux difference through the filter bandpass and not for the possible loss of contrast due to the spectral mismatch between the 2 sources. 

The ETC is thus perfectly adapted and trustable for the SNR calculation occurring in the background limited regime, typically at 1" separation and beyond, computing the SNR of an off-axis source under the ideal contrast assumption. At shorter separations and towards the edge of the masks, the ETC will return increasingly optimistic results.

Below 1" and down to the IWA 

Below 1", ETC will approximate the results to the closest available PSF in its library. For more realistic contrast and detection limits calculations at any separation within 1" and down to the IWA of a given coronagraph, accounting for eventual pointing errors, one can use the Pandeia engine in command-line and call WebbPSF "on the fly" generate more realistic simulations than the ones provided by the ETC and its pre-computed library of PSFs at discrete angular distances: (1) introducing an initial shift corresponding to a target acquisition error; (2) implementing the small grid dithers. 

---

APT recommendations

TA

In the comments section of the targets, it is good practice to indicate their K-band magnitudes and spectral type (as well as the distance to the science target from the PSF reference star) to facilitate the technical review of the proposal. Please always report all targets' proper motions even if they are small, when available. It will minimize the probability of unsuccessful target acquisition.

Time accounting and Smart Accounting

Coronagraphy with several observations bundled in a non-interruptible sequence can benefit from accounting options in APT. Smart Accounting will reduce the total slew times charged for such sequences.

---

---