Step-by-Step APT Guide for MIRI and NIRCam Coronagraphy of HR8799 b
Example Science Program #36: APT Guide
Dated material
This example was created pre-launch, and the APT has been updated since its creation. You may see differences in the appearance of the APT GUI and/or the warnings and errors in APT from what is shown herein.
Please refer to JWST Example Science Programs for more information.
See also: NIRCam and MIRI Coronagraphy of HR8799 b, JWST Astronomers Proposal Tool Overview
The Astronomer's Proposal Tool (APT) is the official submission tool for all JWST proposals. Filling out a JWST proposal in the APT involves entering proposal information, specifying information about the target(s), setting up the observation(s), defining any special requirements, and ensuring the program can be scheduled as specified. This guide provides a walkthrough of this process for the NIRCam and MIRI Coronagraphy of HR8799 b example science program.
Fill out Proposal Information
See also: APT Proposal Information
Words in bold are GUI menus/
panels or data software packages;
bold italics are buttons in GUI
tools or package parameters.
Enter proposed Targets
See also: APT Targets
The next step is to specify the proposed targets. Target information is entered by selecting Targets in the Tree Editor, which provides options in the Active GUI window.
This program consists of 3 Fixed Targets: the science target HR 8799 (i.e., * HD 218396) and PSF reference stars HD 218261 (for NIRCam) and and HD 220657 (* ups Peg; for MIRI). Using the APT Fixed Target Resolver tool, retrieve each target from the SIMBAD database using their archival names and then commit them to the proposal.
Once resolved, re-name the targets "HR8799", "HD220657" and "HD218261", in the Name in the Proposal field respectively.
Define the Category of the "HR8799" target as Star and provide the F stars and Exoplanet Systems Description keywords. For "HD220657" and "HD218261", select Calibration in Category and select the Coronagraphic and Point spread function Description keywords.
Create observations
See also: APT Observations
With the targets specified, you can now begin fleshing out the proposal. In the APT, observations reside in one or more observation folders, located under the main Observations folder in the tree editor. Because you had decided to split the MIRI and NIRCam coronagraphic observations into two different coronagraphic observation sequences (at different epochs), you can create two separate observation folders. To create a new folder, click on Observations in the tree editor and click the New Observation Folder button, creating a new observation folder with a new blank observation form inside that folder. When an observation folder is selected, a new observation can be created by clicking the Add button.
For ease, you can create each of the desired observation folders and observation templates as placeholders, specifying only the Label and observation Number, Instrument, Template and Target, prior to entering the specific details of each observation—this will make it much easier to specify various connections, such as PSF reference observations and special requirement links, as you craft your individual observations. As such, create two new observation folders containing 3 and 9 observations, respectively, and specify them as follows:
- Observation Folder 1: Label: NIRCam Coronagraphic observations
- Observation Folder 2: Label: MIRI Coronagraphic observations
Note that while you may create these observations in any order, it is essential to assign the "Observation Number" for each observation as stated above (i.e., organized according to the observing strategy previously devised). This is because within the APT, observations occur according to increasing observation number.
Specify observations
See also: JWST APT Observation Templates
With the proposal fleshed out, you will now return to each observation and fill out the observation specifications in the selected observation template. For both the MIRI and NIRCam coronagraphic imaging modes, an observer has control over three primary parameters:
- coronagraphic mask + filter combination
- small grid dithering type
- detector read out mode and exposure time (via the number of frames and integrations).
The allowed values are documented and maintained in the MIRI Coronagraphic Imaging Template Parameters and NIRCam Coronagraphic Imaging Template Parameters pages, respectively.
NIRCam coronagraphic imaging observations
See also: NIRCam Coronagraphic Imaging APT Template
This example was created pre-launch. Starting in Cycle 2, NIRCam is able to obtain both the short and long wavelength coronagraphic data simultaneously. Users must include both a longwave filter and a shortwave filter for each science exposure in APT.
The NIRCam Coronagraphic Imaging Template Parameters article documents the allowed values for this template. Define these for your observations with the following template specific information (in accordance with the ETC). The strategy here is to generate as many frames as possible (RAPID, 10 Groups/Integration), avoid saturation and adjust the Number of Integrations per Exposure to yield a SNR of ~100 on HR 8799 b for all filters.
For the reference star which is taken with a 5-point small-grid-dither pattern (the maximum for the bar, to guarantee an optimal PSF subtraction), the Number of Integrations per Exposure is logically 5 times smaller, 4 when not divisible by 5, to keep the total time and photon count on the reference star approximately the same as on HR 8799).
Request astrometric confirmation images for the observation on the science target. Indeed, those are necessary to know the position of the star when it is behind the occulter (with respect to other stars in the field) and hence to get a precise astrometric calibration for the planet b whose orbital refinement is of interest for the community. This astrometric calibration is not necessary for the reference star. You will need to define a number of parameters, including Coronagraphic Mask, Acquisition Target Parameters (Brightness, Filter, Readout Pattern, Number of Groups/Integration), ETC Wkbk. Calc. ID, Astrometric Confirmation Image Parameters, Dither Pattern, Subarray, Science Filters, Science Readout Patterns, Number of Groups/Integration, Number of Integrations/Exposure, and NIRCam PSF Reference Observation. Choose the following parameters for the observations:
Observation Folder 1: Label: "NIRCam Coronagraphic observations"
MIRI coronagraphic Imaging observations
See also: MIRI Coronagraphic Imaging APT Template
In accordance with the advance work in the ETC (see Step-by-Step ETC Guide for NIRCam and MIRI Coronagraphy of HR8799 b article), define the MIRI observations with the template specific information for MIRI Coronagraphic Imaging. Unlike for NIRCam, it is allowed to use a large number of Groups/Int (recommended for sake of calibration) and thus you can fix the Number of Integrations/Exposure to 5 (1 for the reference star) and vary the Groups/Int to also achieve a SNR of ~100 on HR 8799 b for each of the 3 filer/mask setup. Use the same readout parameter for the reference star to guarantee the same frame background level. The reference star for MIRI is taken, as for NIRCam, with a 5-point small-grid-dither (9-point would be overshoot considering HR 8799 is an easy target at a separation where the SNR is limited by the background rather than by speckle noise). You will need to define a number of parameters, including Coronagraphic Filter/Mask, Acquisition Target Parameters (Brightness, Filter, Quadrant, Readout Pattern, Number of Groups/Integration), ETC Wkbk. Calc. ID, Dither Pattern, Science Readout Patterns, Number of Groups/Integration, Number of Integrations/Exposure, and MIRI PSF Reference Observation. Choose the following parameters for the observations:
For your own tracking purposes, it is recommended you include the ETC workbook and calculation ID number in the Acq ETC Wkbk Calc ID field so the TA SNR calculations can be verified by instrument scientists during technical reviews after the proposal is accepted. In this example, an ETC workbook ID number was not included in the provided APT file since a unique ID number is generated when an example workbook is added to a user's list of workbooks.
- Observation Folder 2: Label: "MIRI Coronagraphic observations"
Define special requirements
See also: APT Special Requirements
Adding Special Requirements in APT
In the APT, Special Requirements (SRs) are defined parameters used to observation scheduling for scientific reasons, or to indicate other situations requiring specific actions. In order to fulfill the guidelines of the proposed observing strategy (see parent article), you will use two kinda of special requirements: (1) timing special requirements, which are used to restrict the scheduling of JWST observations by timing constraints, and (2) aperture position angle special requirements, which are used to restrict the scheduling of observations by position angle constraints.
NIRCam Coronagraphic Observations (Special Requirements)
For the "NIRCam Coronagraphic observations" folder, the SRs placed are as follows:
Timing Special Requirements
To ensure the observations execute together and in the order provided:
- SEQUENCE OBSERVATIONS 1, 2, 3, NON-INTERRUPTIBLE
Select "Reference Star - NIRCam - MASKLWB (Obs 3)":
Add a Timing → Group/Sequence Observations Link:
In the Observation list, select observations 1, 2 and 3.
Check the Sequence and Non-interruptible checkboxes.
Aperture Position Angle Special Requirements
HR 8799 b is always well positioned with respect to NIRCam's MASKLWB axis (horizontal). Nevertherless, for training purposes, set two "Aperture PA Range" requirements which correspond roughly to the whole observability intervals and for both "Roll 1" and "Roll 2" (see parent article).
APERTURE PA RANGE: 59 to 75 Degrees (V3 58.599 to 74.599) AND 211 to 250 Degrees (V3 210.599 to 249.599)
Select
"HR 8799 - NIRCam - MASKLWB - Roll 1 (Obs 1)"
"HR 8799 - NIRCam - MASKLWB - Roll 2 (Obs 2)"
Add 2 Position Angle → PA Range special requirements:
Aperture PA Range: Define as "59" to "75" Degrees.
Aperture PA Range: Define as "211" to "250" Degrees.
- APERTURE PA OFFSET 2 from 1 by 7 to 14 Degrees (Same offsets in V3)
Select "HR 8799 - NIRCam - MASKLWB - Roll 1 (Obs 1)
Add a Position Angle → PA Offset Link:
Orient observation: "HR 8799 - NIRCam - MASKLWB - Roll 2 (Obs 2)"
Offset from: "HR 8799 - NIRCam - MASKLWB - Roll 1 (Obs 1)"
Min PA offset: Define as "7" Degrees
Max PA Offset Define as "14" Degrees
Reference Axis: Select "Aperture"
MIRI Coronagraphic Observations (Special Requirements)
For the "MIRI Coronagraphic observations" folder, the following special requirements are imposed on the observations:
Timing special requirements
To ensure the observations execute together and in the order provided—minimizing possible thermal variations differentially affecting the acquired PSFs, as well as the number of rolls and slews—you'll group all of the MIRI observations using a non-interruptible sequence:
- SEQUENCE OBSERVATIONS 4, 5, 6, 7, 8, 9, 10, 11, 12, NON-INTERRUPTIBLE
Select "HR 8799 - MIRI- 1065C - Roll 1 (Obs 4)"
Add a Timing → Group/Sequence Observations Link:
In the Observation list, select observations 4, 5, 6, 7, 8, 9, 10, 11 and 12.
Check the Sequence and Non-interruptible check boxes.
Aperture position angle special requirements
In order to position HR 8799 b in quadrant 1 at more than 30º from the 4QPM vertical most axis, restrict the aperture PA (APA) to > 89º and < 104º. According to previous work in the CVT (see parent article), you found that restricting the APA of the Roll Angle 1 to 89-103° yields good target positioning at Roll Angle 2. Additionally it allows a favorable positioning of planet c in quadrant 4. Set the aperture PA offsets from the minimum (~7º) to relax as much as possible the already stringent scheduling constraint for MIRI to the maximum (~14°). At the angular separation of b, ~7º is good enough.
Place the following APA special requirements on the observations:
APERTURE PA RANGE 89.20 to 103.55 Degrees (V3 84.750 to 99.100)
Select "HR 8799 - MIRI- 1065C - Roll 1 (Obs 4)"
Add a Position Angle → PA Range special requirement:
Aperture PA Range: Define as "89.20" to "103.55" Degrees.
APERTURE PA OFFSET 7 from 4 by 7 to 14 Degrees (Same offsets in V3)
Select "HR 8799 - MIRI- 1065C - Roll 1 (Obs 4)"
Add a Position Angle → PA Offset Link:
Orient observation: "HR 8799 - MIRI- 1065C - Roll 1 (Obs 4)"
Offset from: "HR 8799 - MIRI- 1065C - Roll 2 (Obs 7)"
Min PA offset: Define as "7" Degrees
Max PA Offset Define as "14" Degrees
Reference Axis: Select "Aperture"
Repeat 1. and 2. for Obs 5 & 8 and Obs 6 & 9
Run Visit Planner
See also: APT Visit Planner APT Visit Planner, Using Aladin and APT Visit Planner
With the targets, observations and special requirements of the proposal now defined, the next step is to verify that the observation sequences can be executed as specified. To do so, you will make use of the APT Visit Planner. The Visit Planner (VP) is a tool that performs detailed scheduability checks for observations in the APT, including visibility, constraints checking and guide star availability. The VP may be run on individual observations, collection of observations, and ultimately on the entire set of proposed observations prior to proposal submission.
In the form editor in APT, select the MIRI coronagraphic observations folder, and select the Visit Planner icon from the top tool bar. Clicking the Update Display button in the active GUI window, run the VP on all of the observations, and their associated visits, in the folder. Once the schedulability of the MIRI Coronagraphic observations is confirmed (the VP displaying green checks on the observations), repeat this process on the NIRCam coronagraphic imaging folder.
For an overall observation to be schedulable, the constraints for all visits need to have a window of schedulability at the same time. Running the Visit Planner, find that the observability of the targets (with respect to the observatory as a function of time) and guide star availability, combined with the overlap of all of the special requirements, results in a scheduling window of ~2 weeks in length for each instrument. Below are two screen captures (Figure 1 & 2) of the Visit Planner for both NIRCam and MIRI showing the available time intervals that satisfy the constraints of each observation in the program:
Click on the figure for a larger view.
Visit Planner screenshot: observability of the three NIRCam observations.
Click on the figure for a larger view.
Visit Planner screenshot: observability of the nine MIRI observations. The CVT was used to narrow down the timing constraints to avoid having planet b too close to the 4QPM vertical axis (5º from the detector axis).
Run Smart Accounting
See also: APT Smart Accounting, JWST Observing Overheads and Time Accounting Overview
With the schedulability of the coronagraphic sequences verified, you can now run the APT Smart Accounting on the proposed observations to see whether charged overhead time can be reduced. To run the Smart Accounting tool, select the main Observations folder in the Tree editor and select the Visit Planner tool in the top tool bar, providing access to the Run Smart Accounting button.
Because the set of observations is in a non-interruptible sequence, it will obviously only need one major slew at the beginning of the sequence. Smart Accounting will catch and correct this and reduce the reported overheads. Prior to running the Smart Accounting tool, the APT reports 1.66 hours of Science time and 13.86 hours of Charged time (as reported in the proposal cover page); once run, the total charged time is reduced to 11.17 hours.