Step-by-Step APT Guide for NIRCam and MIRI Coronagraphy of the Beta Pictoris Debris Disk
Instructions for filling out the MIRI and NIRCam Coronagraphic Imaging observing templates in the Astronomers Proposal Tool (APT) for the Beta Pictoris Debris Disk example science program are presented and discussed.
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.
On this page
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.
The 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, retrieve both targets from the SIMBAD database using their archival names and commit them to the proposal.
Once resolved, 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, re-define the Name in the Proposal for the 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 the targets now specified, you can now begin fleshing out the 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 you have decided to split the MIRI and NIRCam coronagraphic observations into two different coronagraphic observation sequences (at different epochs; see parent article), you will need to organize the respective sequences into separate observation folders. To create a new folder, 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, you 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 to specify various connections, such as PSF reference observations and special requirement links, as you craft your individual observations.
As such, 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 you may create these observations in any order, it is essential that you 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.
MIRI Coronagraphic Imaging Observations
See also: MIRI Coronagraphic Imaging APT Template, APT Target Acquisition
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), Dither Pattern, Science Readout Patterns, Number of Groups/Integration, Number of Integrations/Exposure, and MIRI PSF Reference Observation. In accordance with advance work in the ETC (see Step-by-Step ETC Guide for NIRCam and MIRI Coronagraphy of the Beta Pictoris Debris Disk article), 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. This example does 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 previous work in the CVT, the chosen orientations for the MIRI coronagraphic observations place the disk midplane in quadrants 2 and 4; therefore choose 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.
You 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. Define these for the observations with the following template specific information (in accordance with the advance work in the ETC).
2As mentioned previously (see parent article) Beta Pictoris is one of the brightest disks in the sky, and so you do not require the use of small grid dithers—for this reason, 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 the proposed observing strategy (see parent article), 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.
Timing SRs
In order to minimizing possible thermal variations differentially affecting the acquired PSFs, as well as the number of rolls and slews, you need to ensure that your observations execute together and in the order you have defined. To achieve this, 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 the observing strategy (see parent article), you have decided to split the 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, apply a Timing SR with the SEQUENCE OBSERVATIONS and NON-INTERRUPTIBLE constraints as follows:
- In the tree editor, select an observation from the MIRI coronagraphic observations folder (e.g. "Beta Pic - F2300C/Lyot Roll 1 (Obs 1)").
- In the observation's template, click on the tab labeled "Special Requirements".
- In the Special Requirements box, click the Add... button and select the Timing → Group/Sequence Observations Link option.
- In the pop-up box that appears, 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 the NIRCam sequence of observations:
- Select an observation from the NIRCam coronagraphic observations folder (e.g. "Alpha Pic - LW PSF (Obs 7)")
- Under the Special Requirements tab, Add... a Timing → Group/Sequence Observations Link
- Select Obs 7, 8, 9, 10, 11, and 12 from in the Observation list
- 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 the previous work with the Coronagraph visibility tool (CVT; see parent article), you have already identified the desired position angles and offsets for your observations. For the MIRI observations, you 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, take the following steps:
- Select observation 1 "Beta Pic - F2300C/Lyot Roll 1 (Obs 1)" from the MIRI coronagraphic observations folder,
- Under the Special Requirements tab, click Add... and select the Position Angle → PA Range option.
- In the pop-up box, 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, click Add... and select the Position Angle → PA Offset Linkoption.
- in the pop-up box, 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)".
- 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, click Add... and select the Position Angle → PA Range option.
- Select observation 2 "Beta Pic - F1500C/Lyot Roll 1 (Obs 2)" from the MIRI coronagraphic observations folder
- Under the Special Requirements tab, click Add... and select the Position Angle → PA Range option.
- In the pop-up box, 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, click Add... and select thePosition Angle → PA Offset Linkoption.
- in the pop-up box, 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)".
- 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, click Add... and select the Position Angle → PA Range option.
For the NIRCam observations, you 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 the MIRI observations, enter these position angle constraints on the NIRCam observations as follows:
- Select observation 10 "Beta Pic - SW Roll 1 (Obs 10)" from the NIRCam coronagraphic observations folder,
- Under the Special Requirements tab, click Add... and select the Position Angle → PA Range option.
- In the pop-up box, 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, click Add... and select thePosition Angle → PA Offset Link option.
- in the pop-up box, 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)".
- 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, click Add... and select the Position Angle → PA Range option.
- Select observation 2 "Beta Pic - LW Roll 1 (Obs 12)" from the NIRCam coronagraphic observations folder
-
- In the pop-up box, 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, click Add... and select the Position Angle → PA Offset Link option.
- in the pop-up box, 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)".
- 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 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 schedulability 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 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, you will find that the observability of the targets (w.r.t. the observatory as a function of time) and guide star availability, combined with the overlap of all special requirements, results in a scheduling window of ~2 weeks in length for each instrument.
Visit Planner GUI showing all observations active
Click on the figure for a larger view.
With the main Observation folder in the tree editor selected and the VP active, running the VP indicates that all of the observations are schedulable
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.
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 the screen. After running Smart Accounting, you can view the revised total resource assessment in the proposal cover page.
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 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.