JWST High-Contrast Imaging in APT

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).

On this page

Main articles: JWST APT Coronagraphic Sequence ExamplesMIRI Coronagraphic Imaging APT Template, NIRCam Coronagraphic Imaging APT TemplateNIRISS Aperture Masking Interferometry Template APT Guide
See also: MIRI Coronagraphy of GJ 758 b, MIRI and NIRCam Coronagraphy of the Beta Pictoris Debris Disk, NIRISS AMI Science Use Case 

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.

Strictly speaking, the only restriction on science targets and PSF reference targets is they be schedulable at the same time. Furthermore, for purposes of efficiency and practicality, the closer together they are, in time, the better. For PSF reference stars, as a guideline, try to find a reference target that is within about 20° of your science target. Larger separations are possible, but slew times get longer and thermal changes in the JWST optics may occur that could make it more difficult to match the reference PSF to your science observations.

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.

1  Bold italics font style is used to indicate parameters, parameter values, and/or special requirements that are set in the APT GUI.

Observations and sequences

Main article: 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 that will 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: 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.

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 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.

  1. To specify an observation as a PSF reference observation in APT, just mark the check box titled This is a PSF Reference Observation. The template section 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 template in question is for a science target, the user must activate the pull-down menu of similar observations in the proposal and use the check boxes provided to indicate which observation (or observations) should be used for PSF subtraction in the data processing system. Hint: first go through your sequences and mark all of the PSF reference observations, so APT knows about them. Then, they will be available in the pull-down menu for this step. 

    Users must associate one or more PSF reference observations with each science observation. Note that only observations with coronagraphs/filters/occulters and subarrays matching a given science observations are valid for association, and therefore only those should 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 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 to be 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 section 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, from the pull-down menu of options, 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

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.



Latest updates