Step-by-Step APT Guide for MIRI and NIRCam Coronagraphy of the Beta Pictoris Debris Disk
Example Science Program #35: 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 the Beta Pictoris Debris Disk, 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 "MIRI and NIRCam Coronagraphy of the Beta Pictoris Debris Disk" Example Science Program.
A filled out APT file can be accessed via the menu options File → JWST Example Science Proposals → Multi-Inst → 35 MIRI and NIRCam Coronagraphy of the Beta Pictoris Debris Disk in APT. The APT file was created with version 27.3. There may be inconsistencies or additional warnings or errors with other versions of APT.
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
Target information is entered by selecting Targets in the Tree Editor, which provides options in the Active GUI window.
Our program consists of two fixed targets: the science target star Beta Pictoris (i.e., * bet Pic) and PSF reference star Alpha Pictoris (* alf Pic). Using the APT Fixed Target Resolver tool, we retrieve both targets from the SIMBAD database using their archival names and commit them to our proposal.
Once resolved, we select the new target entry for Beta Pic ("-BET-PIC") and change the Name in the Proposal to "Beta-Pic"; select the "Star" Category and assign it with relevant Keywords (e.g. "A stars", "Debris Disks" etc.). Likewise, we re-define the Name in the Proposal for our Alpha Pic target as be "Alpha-Pic", and then select the "Calibration" Category and appropriate description Keywords (e.g. "Coronagraphic", "Point Spread Function", "A stars", etc.).
Create Observations
See also: APT Observations
With our targets now specified, we can now begin fleshing out our proposal. In the APT, Observations are the basic proposal design element, consisting of one astronomical target and one JWST observing mode using a corresponding APT Observing Template. Any number of observations involving one or more instruments can be entered into a given proposal, as required by the proposed science, and may be lined together in time and/or position angle if necessary, using special requirements. In APT, observations reside in one or more observation folders, located under the main Observations folder in the tree editor.
Because we have decided to split our MIRI and NIRCam coronagraphic observations into two different coronagraphic observation sequences (at different epochs; see parent article), we will organize the respective sequences into separate observation folders. To create a new folder, we click on Observations in the tree editor and click the New Observation Folder button—this creates a new observation folder containing a new blank observation. These folders and observations can be rearranged simply by dragging them.
For ease, we will create each of the desired observation folders and observations 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 for us to specify various connections, such as PSF reference observations and special requirement links, as we craft our individual observations.
As such, we create two observation folders, each containing 6 observations, specified as follows:
Observation Folder 1:
- Label: "MIRI Coronagraphic observations"
- Observations:
Observation Folder 2:
- Label: "NIRCam Coronagraphic observations"
- Observations:
Note that while we may create these observations in any order, it is essential that we assign the "Observation number" for each observation as stated above (i.e., organized according to the observing strategy we previously devised). This is because within the APT, observations occur according to increasing observation number.
Specify Observations
See also: JWST APT Observation Templates
With our proposal fleshed out, we 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.
MIRI Coronagraphic Imaging Observations
See also: MIRI Coronagraphic Imaging APT Template, APT Target Acquisition
We will need to define a number of parameters, including Coronagraphic Filter/Mask, Acquisition Target Parameters (Brightness, Filter, Quadrant, Readout Pattern, Number of Groups/Integration), Dither Pattern, Science Readout Patterns, Number of Groups/Integration, Number of Integrations/Exposure, and MIRI PSF Reference Observation. In accordance with out advance work in the ETC (see Step-by-Step ETC Guide for NIRCam and MIRI Coronagraphy of the Beta Pictoris Debris Disk article), we define the MIRI observations with the template specific information for MIRI Coronagraphic Imaging as follows:
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, we do not include an ETC workbook ID number 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.
1 According to our previous work in the CVT, our chosen orientations for the MIRI coronagraphic observations place the disk midplane in quadrants 2 and 4, therefore we chose to perform the initial TA in Quadrant 1.
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.
We will need to define a number of parameters, including Coronagraphic Mask, Acquisition Target Parameters (Brightness, Filter, Readout Pattern, Number of Groups/Integration), 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. The NIRCam Coronagraphic Imaging Template Parameters article documents the allowed values for this template. We define these for our observations with the following template specific information (in accordance with our advance work in the ETC).
2As mentioned previously (see parent article) Beta Pictoris is one of the brightest disks in the sky, and so we do not require the use of small grid dithers—for this reason, we keep the default option of "NONE" for the Dither Type.
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 our proposed observing strategy (see parent article), we will require the use of two kinda of special requirements: Timing Special Requirements, which are used to restrict the scheduling of JWST observations by timing constraints, and Aperture Position Angle Special Requirements, which are used to restrict the scheduling of observations by position angle constraints.
Timing SRs
In order to minimizing possible thermal variations differentially affecting the acquired PSFs, as well as the number of rolls and slews, we need to ensure that our observations execute together and in the order we have defined. To achieve this, we will use the Group/Sequence Observations Link timing SR to link the each sequence of observations together, so that they are scheduled in a non-interruptible manner and executed in order of their observation number.
As per our observing strategy (see parent article), we have decided to split our program such that the observations made in each instrument are scheduled together in their own non-interruptible sequence (as opposed to one long non-interruptible sequence for all observations). Starting with the MIRI coronagraphic observations, we apply a Timing SR with the SEQUENCE OBSERVATIONS and NON-INTERRUPTIBLE constraints as follows:
- In the tree editor, we select an observation from the MIRI coronagraphic observations folder (e.g. "Beta Pic - F2300C/Lyot Roll 1 (Obs 1)").
- In the observation's template, we click on the tab labeled "Special Requirements".
- In the Special Requirements box, we click the Add... button and select the Timing → Group/Sequence Observations Link option.
- In the pop-up box that appears, we select Obs 1, 2, 3, 4, 5, and 6 from in the Observation list and check the Sequence and Non-interruptible checkboxes.
- Clicking on the OK button, the SR is then displayed in the Special Requirements box in the GUI, where it reads as follows: "Sequence Observations 1, 2, 3, 4, 5, 6, Non-interruptible"
Likewise, for our NIRCam sequence of observations:
- We select an observation from the NIRCam coronagraphic observations folder (e.g. "Alpha Pic - LW PSF (Obs 7)")
- Under the Special Requirements tab, we Add... a Timing → Group/Sequence Observations Link
- We select Obs 7, 8, 9, 10, 11, and 12 from in the Observation list
- We check the Sequence and Non-interruptible checkboxes and hit the OK button, resulting in a "Sequence Observations 7, 8, 9, 10, 11, 12, Non-interruptible" SR, displayed in the Special Requirements box.
Note that APT will execute the observations in a Sequence Observations ... Non-interruptible grouping in the order of increasing observation number.
Aperture Position Angle SRs
With our previous work with the Coronagraph visibility tool (CVT; see parent article), we have already identified the desired position angles and offsets for our observations. For our MIRI observations, we determined that restricting the APA of the science observations at the initial spacecraft orient (i.e. "Roll Angle 1") in the range of 340-355° yields good target positioning at the second spacecraft orient (i.e. "Roll Angle 2"), assuming a spacecraft roll of 10 to 14°. To enter these position angle constraints into the APT, we take the following steps:
- We select observation 1 "Beta Pic - F2300C/Lyot Roll 1 (Obs 1)" from the MIRI coronagraphic observations folder,
- Under the Special Requirements tab, we click Add... and select the Position Angle → PA Range option.
- In the pop-up box, we define an Aperture PA Range of "340" to "355" Degrees.
- Clicking on the OK button, the SR is displayed in the Special Requirements box, where it reads:
"Aperture PA Range 340 to 355 Degrees (V3 335.550295 to 350.550295)"
- Under the Special Requirements tab, we click Add... and select the Position Angle → PA Offset Linkoption.
- in the pop-up box, we select the Orient observation to be "Beta Pic - F2300C/Lyot Roll 2 (Obs 4)" and define it as Offset from: "Beta Pic – F2300C/Lyot Roll 1 (Obs 1)".
- We define a Min PA offset of "10" Degrees and Max PA offset of "14" Degrees.
- Clicking on the OK button, the SR is displayed in the Special Requirements box, where it reads:
"Aperture PA offset 4 from 1 by 10 to 14 Degrees (Same offsets in V3)"
- Under the Special Requirements tab, we click Add... and select the Position Angle → PA Range option.
- We select observation 2 "Beta Pic - F1500C/Lyot Roll 1 (Obs 2)" from the MIRI coronagraphic observations folder
- Under the Special Requirements tab, we click Add... and select the Position Angle → PA Range option.
- In the pop-up box, we define an Aperture PA Range of "340" to "355" Degrees.
- Clicking on the OK button, the SR is displayed in the Special Requirements box, where it reads:
"Aperture PA Range 340 to 355 Degrees (V3 335.550295 to 350.550295)"
- Under the Special Requirements tab, we click Add... and select thePosition Angle → PA Offset Linkoption.
- in the pop-up box, we select the Orient observation to be "Beta Pic - F1550C/4QPM Roll 2 (Obs 4)" and define it as Offset from: "Beta Pic – F1550C/4QPM Roll 1 (Obs 1)".
- We define a Min PA offset of "10" Degrees and Max PA offset of "14" Degrees.
- Clicking on the OK button, the SR is displayed in the Special Requirements box, where it reads:
"Aperture PA offset 3 from 2 by 10 to 14 Degrees (Same offsets in V3)"
- Under the Special Requirements tab, we click Add... and select the Position Angle → PA Range option.
For our NIRCam observations, we determined that an aperture position angle in the range of 345°–360° for the science observations at the initial spacecraft orient (i.e. "Roll Angle 1"), will also yield good target positioning at the second spacecraft orient (i.e. "Roll angle 2"; see parent article). As with our MIRI observations, we enter these position angle constraints on our NIRCam observations as follows:
- We select observation 10 "Beta Pic - SW Roll 1 (Obs 10)" from the NIRCam coronagraphic observations folder,
- Under the Special Requirements tab, we click Add... and select the Position Angle → PA Range option.
- In the pop-up box, we define an Aperture PA Range of "345" to "360" Degrees.
- Clicking on the OK button, the SR is displayed in the Special Requirements box, where it reads:
"Aperture PA Range 345 to 360 Degrees (V3 345.186639 to 0.186639)"
- Under the Special Requirements tab, we click Add... and select thePosition Angle → PA Offset Link option.
- in the pop-up box, we select the Orient observation to be "Beta Pic - SW Roll 2 (Obs 10)" and define it as Offset from: "Beta Pic – SW Roll 1 (Obs 9)".
- We define a Min PA offset of "10" Degrees and Max PA offset of "14" Degrees.
- Clicking on the OK button, the SR is displayed in the Special Requirements box, where it reads:
"Aperture PA offset 10 from 9 by 10 to 14 Degrees (Same offsets in V3)"
- Under the Special Requirements tab, we click Add... and select the Position Angle → PA Range option.
- We select observation 2 "Beta Pic - LW Roll 1 (Obs 12)" from the NIRCam coronagraphic observations folder
-
- In the pop-up box, we define an Aperture PA Range of "345" to "360" Degrees.
- Clicking on the OK button, the SR is displayed in the Special Requirements box, where it reads:
Aperture PA Range 345 to 360 Degrees (V3 345.186639 to 0.186639)
- Under the Special Requirements tab, we click Add... and select thePosition Angle → PA Offset Linkoption.
- in the pop-up box, we select the Orient observation to be "Beta Pic - LW Roll 2 (Obs 12)" and define it as Offset from: "Beta Pic – LW Roll 1 (Obs 11)".
- We define a Min PA offset of "10" Degrees and Max PA offset of "14" Degrees.
- Clicking on the OK button, the SR is displayed in the Special Requirements box, where it reads:
"Aperture PA Offset 11 from 12 by 10 to 14 Degrees (Same offsets in V3)"
-
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 our proposal now defined, our next step is to verify that our observation sequences can be executed as specified. To do so, we 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, we first 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, we 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), we repeat this process on the NIRCam coronagraphic imaging folder.
For the overall observation to be schedulable, all constraints for all visits need to have a window of schedulability at the same time. The bar graph at the observation level shows a roll up of the available times that satisfy the constraints at the visit level. Running the Visit Planner, we find that the observability of our targets (w.r.t. the observatory as a function of time) and guide star availability, combined with the overlap of all of our special requirements, results in a scheduling window of ~2 weeks in length for each instrument.
Run Smart Accounting
See also: APT Smart Accounting, JWST Observing Overheads and Time Accounting Overview
With the scheduability of our coronagraphic sequences verified, we can now run the APT Smart Accounting on our proposed observations to see whether charged overhead time can be reduced.
Because of the piecemeal approach used by the APT to calculate the total time needed to execute a proposal (tallying the resource estimate as each new observation is entered), there is the possibility of overestimating the overheads a given proposal requires. Thus, after designing an observing program in its entirety, it is important for all proposers to re-run a full accounting on their proposal to remove any excess overhead charges and obtain a final, improved resource estimate. This step is called Smart Accounting.
With the Visit Planner active and green checks indicating all observations are schedulable, select Visit Planner → Force Run Smart Accounting from the main APT menu at the top of our screen. After running Smart Accounting, we can view the revised total resource assessment in the proposal cover page.
Because our 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 our reported overheads. Prior to running the Smart Accounting tool, the APT reports 9.33 hours of Science time and 23.69 hours of Charged time (as reported in the proposal cover page); once run, the total charged time is reduced to 19.12 hours.