Several procedures should be followed for entering valid JWST high-contrast imaging observations, including correctly specifying coronagraphic sequences and linking PSF reference stars to science observations in APT.
Parent article: JWST High-Contrast Imaging
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 observation templates are provided for MIRI coronagraphic imaging, NIRCam coronagraphic imaging, and NIRISS aperture masking interferometry.
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, observations of PSF reference stars, and full frame astrometric images, if needed for your science case.
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.
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 JWST Coronagraphy in ETC about the need to gather exposure specifications prior to entering observations into the Astronomers Proposal Tool (APT), and JWST Coronagraphic Observation Planning for an overview of the planning process.
Entering target information
Main article: APT 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 1 field (Fixed Targets form) to clearly indicate which targets are intended for science and which are PSF reference stars, as appropriate. These designations will show up 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.
Observations and sequences
Main article: APT Observations
Getting started on designing coronagraphic observations:
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: create each observation template of 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.
Next, for each observation in your sequence, enter the exposure time information for TA and images of the science target and the PSF reference star. This information comes from your advance work in the Exposure Time Calculator (ETC). (See the individual “template” articles listed in the Introduction for details.) Also, if NIRCam full frame astrometric (FFA) images are needed, indicate Yes in the Astrometric Confirmation Image Parameters template panel for this feature, and enter exposure information 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 discussed above, the standard coronagraphic sequence requires both science and PSF reference observations. While it should be clear in looking at your sequences in APT which PSF reference observations should go with which science observations, there is no clear way for the data processing system to discern this information. All of the observations "look the same" to the data processing system. Hence, a section of the observation templates has been devised where the connections can be made explicit. Your indications in this section of the templates will be passed to the data pipeline for the initial processing of your data.
A section of the observation template at the bottom of the GUI window (you may need to scroll down) is used to indicate which observations produce PSF references and to specify to which science observations they should be linked, in data processing.
Special case: coronagraphic surveys
The STScI Coronagraphic Working Group has identified two "survey" cases that may find utility in certain applications.
Setting appropriate special requirements
Main article: APT Special Requirements
Setting the appropriate Special Requirements is a very important step for coronagraphic observations. At the very least, users must place the Sequence Observations ... Non-interruptible special requirement for the 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 a second sequence at a larger PA offset is needed, the Aperture PA Offset ... special requirement must be set between the two sequences; and so forth. The cases needing this level of attention to detail should be checked out ahead of planning, with the Coronagraphic Visibility Tool. This will avoid the disappointment of only discovering that the needed angles are impossible to observe when checking the schedulability with the APT Visit Planner much later in the proposing process.
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. For future reference, users may wish to enter the relevant ETC workbook and calculation ID information for each TA and observation in this area. (In a future version of APT, a field may be provided in the main science observation section of the GUI for annotating this information.)
Run the visit planner
Main article: APT Visit Planner
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, the check at the level of the observation folder will demonstrate 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
Main article: 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.
Helpful considerations in APT
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 spawn the 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 at left. 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, and blindly copying is not recommended without careful checking.