HCI APT Coronagraphic Sequence Examples
Examples of how to specify JWST coronagraphic sequences, one for MIRI and one for NIRCam, are available in the Astronomer's Proposal Tool (APT).
On this page
See also: High Contrast Imaging Overview
Getting started
Words in bold are GUI menus/
panels or data software packages;
bold italics are buttons in GUI
tools or package parameters.
A standard coronagraphic sequence involves a set of linked observations; these simple examples demonstrate the process by showing the appropriate special requirements needed for the linking. More complicated combinations using multiple filters and/or coronagraphs are also possible. Also, there are more complex ways of specifying PSF reference star observations than shown in these simple examples below. Refer to the JWST High-Contrast Imaging Roadmap (Stage 3 section) for details.
A MIRI example
See MIRI Coronagraphic Imaging and related articles for detailed information about coronagraphy with MIRI.
There are 2 targets in this example: BET-PIC (the science target) and DEL-DOR (the PSF reference star). A standard coronagraphic sequence involves 2 observations of the science target and at least one observation of the PSF reference star, all linked together in a non-interruptible sequence. (This is done to minimize thermal or other changes that could cause the PSF to vary significantly.)
This example also includes required associated/dedicated background measurements to remove the "glow sticks" that contaminate the coronagraphic fields of view.
These observations have already been added to the APT MIRI example. After loading the example into APT, select the Observations folder in the left tree menu to see the filled out template information in the active GUI window, as shown in Figure 1. Note the template panels labeled Target Acquisition Parameters, Coron Parameters, and PSF Reference Observations, which will be further described below.
Click on the figure for a larger view.
The appearance of the APT GUI for a simple MIRI coronagraphic sequence. In the tree editor at left, observations 1 and 2 are both on the science target, and observation 3 is the background observations 1. Observation 4 is the background for the PSF reference star in observation 6. In the active GUI window, one sees template sections for the target acquisition, the coronagraphic exposure specifications, and the PSF reference star assignment section. Warning flags are due to not having input the ETC ID number, which was not computed for this example.
Special requirements
The science target is observed twice using a single MIRI 4QPM/filter combination. The initial science observation has an allowed roll angle range. (This is only necessary if there is known structure around the target, say a disk or a known planet, and the target needs to be positioned to avoid structures in the instrument field of view, in this case, the 4QPM quadrants boundaries.) The second science target observation has a roll angle offset relative to the first one, called a roll dither†.
Figure 2 shows the special requirements that have been set to control this sequence.
Click on the figure for a larger view.
Clicking on the Special Requirements tab in this example of the APT MIRI coronagraphy template shows special requirements for the first observation. The aperture position angle is set to a fairly narrow 2° range, and an offset angle range of 10°–14° is set between observations 1 and 2. Finally, a non-interruptible sequence requirement is placed on the 5 observations, meaning that the science and reference star observations need to be schedulable at the same time (this can be checked in the APT Visit Planner).
Target acquisition parameters
Target acquisition (TA) parameters are shown in Figure 3. Legal (but unverified) values have been entered. In reality, you will need to assess the proper TA parameters for each target using the Exposure Time Calculator to ensure a successful observation. This has not been done for this example. An important option is to cross-reference the ETC workbook and/or calculation you used using the box at right. This can help you reconstruct your assumptions at a later time. See the APT-ETC Connectivity article for details.
Click on the figure for a larger view.
The MIRI target acquisition parameters section of the template is shown. The Acq Quadrant selection allows the user to avoid having a persistence spot in the quadrant where a possible source is expected to be. See MIRI Coronagraphic Target Acquisition for details.
Coronagraph parameters
The Coron Parameters block (see Figure 1) of the template is where the science exposure parameters are specified. These parameters should be set based on calculations performed with the Exposure Time Calculator, after selecting the parameters appropriate for the MIRI coronagraph.
PSF reference star observation
Finally, even though the SEQ NON-INT special requirement has grouped the observations together, information must be provided to the Data Management System (DMS) on how to connect the PSF reference star observation to each of the science observations. The PSF Reference Observations section, at the bottom of the template, is used for this purpose. Note that in APT, you may have to scroll down to see that block. For Observation 3 (the PSF reference star observation), simply select the appropriate check box:
Then, for each of the science observations, this reference observation needs to be selected from the pick list provided, as shown in Figure 5.
Background observations
Dedicated backgrounds associated with each target (science and reference) are currently required to remove the glow stick features that contaminate the coronagraph field of view. Each background observation should have exactly the same exposure parameters as for the associated target. In addition, the Repeat observation parameter should be set to YES. This will repeat the background observation in the diagonal quadrant to give a 2-point dither, which will mitigate against contaminating background objects and residual instrumental artifacts.
Visit Planner
When all observations in the defined coronagraphic sequence have been completely specified, you can run the Visit Planner (VP) to check schedulability. For the defined sequence to be schedulable, both of the 2 science observations and the PSF reference observation must be observable without interruption. APT will check this, as well as check for available guide stars and other constraints affecting angles and visibilities.
Figure 7 shows the VP display after selecting the observation folder containing the sequence and running the Visit Planner. If you have opened the example program in APT, it may show yellow caution signs by each observation. Simply click the red Update Display button and in a few seconds, green checks should appear, meaning not only is the visibility good for both targets at the same time, but guide stars are also available for all 3 observations as specified. Any time the parameters in the observation template are changed, a new run of the VP will be needed. (Try it!)
Click on the figure for a larger view.
The observation folder containing the sequence is selected and the Visit Planner has been run, returning "all green" check marks, thus confirming schedulability. Note the very narrow windows in time, however, caused by the constrained aperture PA requested in the Special Requirements panel. These are highly constrained observations.
Aladin
While not required, viewing the observations in Aladin can be a useful sanity check to confirm that that the angle had been selected properly and the roll dither had been specified as intended. In Figure 8, the 2 science observations were selected( that is, in the form editor, select Observation 1, then shift-select Observation 2, which should highlight both observations, then choose View in Aladin from the top tool bar in the APT GUI). Since a range of 10°–14° for the offset was allowed, Aladin shows the mean, which is a 12° offset, in the display.
Click on the figure for a larger view.
The Aladin display after selecting the 2 science observations. (Select one, then shift-click the second one; Aladin will display both.) This shows both the selected absolute orientation and the offset specified between the 2 observations. In this example, the Digital Sky Survey (DSS) image was not displayed because the brightness of the target star makes it difficult to see the instrument fields of view.
† Roll dithers are limited by JWST observing constraints to be <14°. See the JWST Dithering Overview.
A NIRCam example
Refer to
NIRCam Coronagraphic Imaging and related support pages for detailed information.
The example proposal contains 2 targets, BET-PIC (which represents the science target) and ALF-PIC (which represents the PSF reference star). In this example, the complexity was stepped up only slightly from the previous MIRI example by having the sequence contain observations with 2 coronagraphs/filters instead of one. In this case, all the observations are done at the initial position angle (roll 1) before moving to the offset roll dither position angle (roll 2). Of course, a single observation in each setup is used on the PSF reference star, so they are put together at the end of the sequence. Hence, this sequence contains a total of 6 observations instead of 3, all of which must be schedulable together in order to be valid.
Click on the figure for a larger view.
The APT GUI for a NIRCam coronagraphic observation. This template has blocks for Target Acquisition Parameters, Science Exposures, and PSF Reference Observations selections (similar to the MIRI template) but also has a section for specifying parameters for an optional Astrometric Confirmation Image, if desired.
Special requirements
First notice the observation order: observations with the 2 different coronagraph/filter combinations are done at roll 1 prior to the roll dither. Then, both of the observations are repeated after the roll dither. Finally, the PSF reference star is observed in both coronagraph/filter configurations but at a single roll angle. Figure 10 shows the special requirements for this example. Setting the special requirements in this case is a bit different from the MIRI case above, but notice all 6 observations are linked in the sequence, so they will execute together. Of course, this means that the PSF reference star must be observable at the same time as the science target.
Click on the figure for a larger view.
An absolute aperture position angle restriction is set, and then the desired relative aperture PA ranges between the pairs of observations with the same configuration is set (e.g., obs. 1 & 3, and obs. 2 &4). The "Sequence...Non-interruptible" means the entire set of observations will by executed back-to-back, and hence at the same absolute orientation.
The SEQUENCE ... NON-INTERRUPTIBLE special requirement indicates that the specified set of observations will be done in "increasing observation number" order. In the example, the observations are shown in order of 1 to 6 in the tree editor (left sidebar). However, for general editing in APT, users are allowed to drag and drop observations in the tree editor. If a user reorders the observations in a sequence using this method, it does not change the execution order, which is done via the observation number. Hence, users should check that their desired order for the sequence is consistent with the ordering on the listed observation numbers.
The specification of PSF reference observations and their proper attachment to each of the science observations proceeds exactly as outlined in the MIRI example.
Visit Planner
As shown in Figure 11, even with a sequence of 6 observations, the Visit Planner has been able to verify that there is a time when all 6 observations can be scheduled together. Again, as with the MIRI example above, the fairly narrow range of allowed absolute PA placed on observation 1 results in a rather small window of schedulability, so this type of restriction should only be placed when necessary for the science.
Click on the figure for a larger view.
A successful VP run for NIRCam, demonstrating schedulability despite the setting of the angular offset special requirements needed in this example.
Aladin
Finally, if you wish to perform a sanity check on the angular offset between the 2 rolls on the science target, you can select the relevant observations in the tree editor and click View in Aladin, as shown in Figure 12.