Several procedures should be followed for entering valid JWST high-contrast imaging (HCI) observations, including correctly specifying coronagraphic sequences and linking PSF reference stars to science observations in the Astronomer's Proposal Tool (APT).

See also: HCI APT Coronagraphic Sequence Examples, MIRI and NIRCam Coronagraphy of the Beta Pictoris Debris Disk, NIRISS AMI Science Use Case, NIRCam and MIRI Coronagraphy of HR8799 b

This article provides a general walk-through of planning high-contrast imaging (HCI) observations in APT. Significant contrast improvements can be achieved when a PSF is subtracted from the star or object of interest to reveal its surroundings. 

Detailed, step-by-step instructions for specific coronagraphic modes are provided in these observation template articles: 

• MIRI Coronagraphic Imaging APT Template,
• NIRCam Coronagraphic Imaging APT Template, and
• NIRISS Aperture Masking Interferometry APT Template.

The template for each coronagraphic observation has sections for entering information on a variety of important topics, including target acquisition, exposure times, special requirements for linking observations, PSF reference star observations, and, if needed for your science case, full frame astrometric images and dedicated background images.

Science targets and PSF reference stars must be observed back-to-back—organized into coronagraphic sequences—in order to minimize changes in the PSF between exposures. You are encouraged to use one of the target visibility tools to verify that all targets in a sequence are simultaneously visible. Also, if specific position angles are required for your targets, the availability of the needed angles should be verified ahead of time with the Coronagraphic Visibility Tool. 

Before starting to work in APT, as outlined below, it is assumed that you have used the JWST ETC to determine the exposure information for each target and type of observation, including target acquisition (TA), science, and PSF reference star exposures. See HCI ETC Instructions for information on gathering exposure specifications prior to entering observations into APT, and JWST Coronagraphic Observation Planning for an overview of the planning process.

Entering target information 

See Also: APT Targets, Specifying APT Background Targets

In APT, coronagraphic targets are entered just like any other target. Nevertheless, you may find it very helpful to use designations in the Name in the Proposal field (Fixed Targets form) to clearly indicate which targets are intended for science and which are PSF reference stars or background targets, as appropriate. These designations will appear in the pull-down menus in other parts of APT, to help you build up your coronagraphic sequences. 

There is a comment box in the target entry form in APT where you can enter freehand information. If you have a large number of science targets and PSF stars to keep track of, you can enter information in the comment box for tracking purposes.

If any of your targets require a separate background observation, check the Observations of this target require companion background observation(s) box under the target's Backgrounds panel and select the desired background target(s) from the Target Selection box. This linking will be fed downstream to the data processing system so that background subtraction can be performed.

Observations and sequences

See also: APT Observations

Getting started on designing coronagraphic observations: 

• For a given pair or set of targets to be observed, decide on the observation strategy and observation sequence to be used.
  
  
• Define observation templates for each of the observations in a planned sequence.

Hint #1: collect all observations that pertain to a particular coronagraphic sequence into a single Observation Folder. Use additional folders for other sequences. This will help you organize your proposal.

Hint #2: each observation is specified in an observation template; create each of the observation templates in the sequence first, just specifying the instrument, template, and target. Later, come back and fill in the details.

These steps will make it easier to make the various connections, such as developing the PSF reference observations or adding the necessary special requirements to link the observations.

Ultimately, each sequence will be executed as a non-interruptible sequence. Therefore:

• Place your observations in the desired order within the observation folder, and make sure the observation numbers occur in increasing order. You can use “drag and drop” in the APT tree editor to reorder observations if needed.

  APT will execute the observations in a Sequence Observations ... Non-interruptible grouping in the order of increasing observation number. If you drag and drop the order of your observations in the APT tree editor, make sure the desired sequence of observations is still in increasing order of observation number. If it is not, edit the observation numbers so that ordering is achieved. (The observation number is an editable field in the observation template.) The numbers do not need to be sequential—only in increasing order within the sequence.

• Next, for each observation in your sequence, enter the observation specifications into the template. Exposure information entered here should come from your advanced work in the Exposure Time Calculator (ETC). (See the individual “template” articles listed near the top of this article.)
  
  

• In the case of NIRCam, if full frame astrometric (FFA) images are needed, indicate Yes in the Astrometric Confirmation Image Parameters panel for this feature, and enter exposure information for these images.
  
  
• In the case of NIRISS, if direct images are needed, indicate Yes in the Direct Imaging Parameters panel and enter the exposure specifications for these images.
  
  
• If any of your observations require the small grid dithering technique (SGD), make this selection in the observation template by choosing the appropriate Dither Type in the MIRI template or Dither Pattern in the NIRCam template. Note that the exposure time is increased by the number of dither points in the SGD pattern. Therefore, it is recommended that SGDs only be used when the highest quality PSF subtraction is required. Furthermore, it is envisioned that SGDs be used only on the PSF reference star, although using SGDs on science targets is not precluded.

Setting links between PSF reference observations and science observations

As previously discussed, the standard coronagraphic sequence requires both science and PSF reference star observations. While the relationships between reference and science observations should be clear in the APT sequences, such information also needs to be explicitly conveyed to the data processing system. This is done in the PSF Reference Observations panel in the APT coronagraphy templates, located at the bottom of the GUI (you may need to scroll down).

In the APT coronagraphy templates' PSF Reference Observations panel:

1. To specify that an observation is a PSF reference observation, click on the check box titled This is a PSF Reference Observation. The rest of the panel will then collapse and no other action is needed.

   By JWST policy, PSF reference observations are designated as non-proprietary, even though the time is charged to the program. The reason for this policy is to serve the community's interests by building up, right from the outset, a library of coronagraphic PSFs, for various instruments and under varying conditions. Any exceptions to this policy must be justified in your proposal and agreed to by the appropriate time allocation committee (TAC) panel.

2. If the observation is a science target, the PSF Reference Observations box will show a list of the PSF observations. These PSF observations were previously flagged as such in their observation templates—for this to work, you should first flag all PSF observations in your sequence as described in (1). 

   Each science observation must be associated with one or more PSF reference observations. Note that only PSF observations with coronagraphs/filters/occulters and subarrays matching a given science observation will appear in the list. In principle, science observations can appear in the list and can serve as reference PSFs for other science observations, but this is a special case (see below).

Special case: coronagraphic surveys

The STScI Coronagraphic Working Group has identified two "survey" cases that may find utility in certain applications.

• The shared-reference survey allows the user to observe a set of science targets with a smaller number (one or more) of PSF reference star observations that can be applied to the entire group. This case is actually handled as described above, since the same PSF reference observation can be selected for the separate science targets, assuming they are all observed the same way and are included in the same observation sequence.
  
  

• The other case is the self-referenced survey, where a group of targets is observed, but it is not known a priori which targets/observations will be useful for science and which will be useful as PSF reference observations; the user just wants to observe the set of targets and decide later.
  

  This is expected to be an extremely limited use case and explicit discussion and justification for its use must be made in your proposal's technical description. This mode is invoked by selecting the "Additional Justification" box in the PSF Reference Observations panel of the template.

  Even with the additional justification, the self-referenced survey still raises issues and concerns for initial data processing. The problem is that no PSF reference observations have been provided to the pipeline treatment of the science targets. To address the issue, APT will mark "errors" (red X's) on each observation in a self-referenced survey until one of the other science observations has been selected for use as the initial PSF reference observation. (Note that this amounts to little more than making a guess about a PSF reference observation. Nevertheless, this remedy will allow the data pipeline to at least make an initial PSF-subtracted data product.)
  
  

  Assuming the TAC agrees with the justification, all targets will remain proprietary until such time that the data can be inspected by the user and a designation of "science" or "PSF reference" can be made. At that time, the PSF observations will be made non-proprietary and added to the PSF library. 

Setting appropriate special requirements

See also: APT Special Requirements

 Adding Special Requirements in APT Video Tutorial

Setting the appropriate special requirements is a very important step for coronagraphic observations. At the very least, use the Sequence Observations ... Non-interruptible special requirement for observations that are part of a coronagraphic sequence to force the Visit Planner to look at the collective schedulability of the entire set (see below).

If a roll dither is required for the science target observations, the appropriate Aperture PA Offset ... special requirement must be placed on them. If you require another observation sequence at a larger offset (which will have to be at a different time), use the Aperture PA Offset ... special requirement to specify the desired angle.  Hint: you should use the Coronagraphic Visibility Tool prior to your APT planning session to understand the range of angles available for your target, in order to avoid the disappointment of only discovering that the needed angles are impossible to observe when you run the APT Visit Planner.

The observation templates contain a major tab labeled Special Requirements, which provides access to the controls in APT for specifying the various special requirements. For some of the more complicated sequences involving multiple instruments, filters, or occulters, setting the special requirements can be tricky, and some iterations may be needed. Users should consult the examples of coronagraphic sequences and practice with the JWST APT coronagraphic sequence examples provided.

There is also a Comments tab in the observation template for each observation, next to the Special Requirements tab.  Feel free to enter any relevant information there for future reference.  Also note that each exposure specification line contains a box for entering a reference ETC workbook identifier (and calculation number). See the APT-ETC Connectivity article for more information.

Run the Visit Planner

See also: APT Visit Planner

 APT Visit Planner Video Tutorial

Once the observations for a given coronagraphic sequence have been fully specified and all APT errors resolved, you should run the APT Visit Planner (VP) on the entire observation folder holding the sequence. The VP can be run on individual observations, on observation folders, and/or on the entire set of proposed observations in a proposal. This process can take some time, depending on the size of the proposal. Since a sequence must be able to execute in its entirety, a check at the observation folder level will evaluate the schedulability of your sequence(s). This process should be straightforward if the visibilities have been checked ahead of time with the Coronagraphic Visibility Tool. Additional details—such as guide star availability—are checked by APT at this point.

Run Smart Accounting

See also: APT Smart Accounting

Once the schedulability of your sequences has been verified and your entire proposal is in hand, run the Smart Accounting tool in APT. This tool identifies any excess major slews assumed by APT in the initial build-up of your observation sequences and reduces the slews to the minimum needed. For example, APT assumes a major slew at the start of each new observation, by default. A set of observations within a non-interruptible sequence will obviously only need one major slew at the beginning of the sequence. Smart Accounting will catch and correct this, thus reducing your reported overheads.

APT tip: duplicating a sequence

If your program involves executing a similar pattern of observations for a number of targets, consider fleshing out the observation sequence for one pairing of science target and PSF reference star. Then, use the duplication functionality in APT to create additional sequences.

Assuming you have placed your observation sequence in a separate observation folder, highlight the folder you wish to duplicate in the APT tree editor in the left sidebar. The top APT bar shows pull-down menus for File, Edit, Tools, etc. From the Edit pull-down menu, select Duplicate (or MultipleDuplicate if more than one copy is desired) and the entire folder will be duplicated. Then, just edit the targets and exposure information as necessary for the actual targets in each observation sequence. This same shortcut can be used to duplicate individual observations instead of entire folders, if desired.

When using the duplication functionality, however, users should review each copied sequence carefully for unintended consequences. There may be any number of subtleties that you might want to change between sequences—blindly copying is not recommended without careful checking.