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 two 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 coronagraphy is limited to Module A only, and short and long wavelength observations cannot be carried out simultaneously. In this page we give guidance for preparing NIRCam Coronagraphic observations in APT.  This complements the step-by-step instructions given in the NIRCam Coronagraphic Imaging APT Template. We intend to give advice 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).

Note: Currently, simultaneous observations with the short wavelength (SW) and long wavelength (LW) channels are not supported.


Target Acquisition 

See also: NIRCam Coronagraphic 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 sub-optimal centering of the target behind the coronagraph with dramatic consequences. With NIRCam it is thus recommended 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 OldVery bright targets with K < 7 ("Bright" case in APT) must usually be acquired using a neutral density filter as explained in NIRCam Coronagraphic Target Acquisition.

Astrometric confirmation images

TA gives users the opportunity to obtain two full-frame images consecutively for astrometric purposes: one when the science target is still away from the mask and a second one 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 Coronagraphic Observation Planning

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 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 as the overheads associated to 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 thanks to the Coronagraphic Visibility Tool (CVT). This GUI-based tool was primarily developed to provide the visibility and allowed positon angles (PAs) for a given target across the year. The right-hand plot of the CVT is very useful also to 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 the 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 sub-optimal 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-off: 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 rather a high number (several tens) of frames. Using a slow mode and saving fewer frames and groups can result as a limitation for 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, it is recommended to use two subsequent rolls on a science target and then slew and observe a PSF reference star, ideally with several small-grid-dither pointings  (5-point or 9-point). These three observations should be gathered in a non-interruptible sequence in APT. This strategy is recommended to guarantee two different optimal PSF subtractions despite thermal drift of the observatory and associated wavefront and PSF variations. 

The maximum roll angle being ±5º, the two 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 property in principle should allow one to reach 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 to select 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 (~400s for 1000", ~1000s 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 provide the best subtraction strategy for small IWA, they can explode 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 for the science target. 

ETC calculations

See also: JWST Coronagraphy in ETC

1" and above

The JWST web-based 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 two sources. 

The ETC is thus perfectly adapted and trustable for the SNR calculation occuring in the background limited regime, typically at 1" separation and beyond.

Below 1" and down to the IWA 

Below 1" the official web-based 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, it is recommended to make use of the Pandeia-Coronagraphy extension of the ETC's Pandeia engine. This python based package allows one to introduce a mis-registration of the PSF Reference star, experiment with small grid dithers, etc.

APT recommendations


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 these accounting options in APT. Smart accounting will reduce the total slew times charged for such sequences.

Last updated

Not published


The format for 'Last updated' is shown below. Enter updates above this internal"Comment" box. Only enter major updates (not typos or formatting changes).

Updated April 5, 2017

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam fermentum vestibulum est. Cras rhoncus. 
  • Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed quis tortor. 

Published March 2, 2017