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. 

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. 

---

Fill out Proposal Information

See also: APT Proposal Information

After opening APT, we selected "New JWST Proposal" under the "New Document" pull-down menu. On the proposal information page, we entered Title, Abstract, and Category of proposal and kept Cycle number at its default value. 

---

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:
  
  
  1.  Observation 1

     • Number: we assign an Observation Number of "1".

     • Label: we provide the Observation Label "Beta Pic - F2300C/Lyot Roll 1".

     • Instrument: we select "MIRI" as the Instrument.

     • Template: we select the "MIRI Coronagraphic Imaging" Template.

     • Target: we select "1 BETA-PIC" as the Target.

  2.  Observation 2

     • Number: we assign an Observation Number of "2".

     • Label: we provide the Observation Label "Beta Pic - F1550C/4QPM Roll 1".

     • Instrument: we select "MIRI" as the Instrument.

     • Template: we select the "MIRI Coronagraphic Imaging" Template.

     • Target: we select "1 BETA-PIC" as the Target.

  3.  Observation 3

     • Number: we assign an Observation Number of "3".

     • Label: we provide the Observation Label "Beta Pic - F1550C/4QPM Roll 2".

     • Instrument: we select "MIRI" as the Instrument.

     • Template: we select the "MIRI Coronagraphic Imaging" Template.

     • Target: we select "1 BETA-PIC" as the Target.

  4.  Observation 4

     • Number: we assign an Observation Number of "4".

     • Label: we provide the Observation Label "Beta Pic - F2300C/Lyot Roll 2".

     • Instrument: we select "MIRI" as the Instrument.

     • Template: we select the "MIRI Coronagraphic Imaging" Template.

     • Target: we select "1 BETA-PIC" as the Target.

  5.  Observation 5

     • Number: we assign an Observation Number of "5".

     • Label: we provide the Observation Label "Alpha Pic - F2300C/Lyot PSF".¹

     • Instrument: we select "MIRI" as the Instrument.

     • Template: we select the "MIRI Coronagraphic Imaging" Template.

     • Target: we select "2 ALPHA-PIC" as the Target.

  6.  Observation 6

     • Number: we assign an Observation Number of "6".

     • Label: we provide the Observation Label "Alpha Pic - F1550C/ 4QPM PSF".

     • Instrument: we select "MIRI" as the Instrument.

     • Template: we select the "MIRI Coronagraphic Imaging" Template.

     • Target: we select "2 ALPHA-PIC" as the Target.

Observation Folder 2:

• Label: "NIRCam Coronagraphic observations"
  
• Observations: 
  
  
  1.  Observation 7

     • Number: we assign an Observation Number of "7".

     • Label: we provide the Observation Label "Alpha Pic - LW PSF".

     • Instrument: we select "NIRCam" as the Instrument.

     • Template: we select the "MIRI Coronagraphic Imaging" Template.

     • Target: we select "2 ALPHA-PIC" as the Target.

  2.  Observation 8

     • Number: we assign an Observation Number of "8".

     • Label: we provide the Observation Label "Alpha Pic - SW PSF".

     • Instrument: we select "NIRCam" as the Instrument.

     • Template: we select the "NIRCam Coronagraphic Imaging" Template.

     • Target: we select "2 ALPHA-PIC" as the Target.

  3.  Observation 9

     • Number: we assign an Observation Number of "9".

     • Label: we provide the Observation Label "Beta Pic - SW Roll 1".

     • Instrument: we select "NIRCam" as the Instrument.

     • Template: we select the "NIRCam Coronagraphic Imaging" Template.

     • Target: we select "1BETA-PIC" as the Target.

  4.  Observation 10

     • Number: we assign an Observation Number of "10".

     • Label: we provide the Observation Label "Beta Pic - SW Roll 2".

     • Instrument: we select "NIRCam" as the Instrument.

     • Template: we select the "NIRCam Coronagraphic Imaging" Template.

     • Target: we select "1 BETA-PIC" as the Target.

  5.  Observation 11

     • Number: we assign an Observation Number of "11".

     • Label: we provide the Observation Label "Beta Pic - LW Roll 2".

     • Instrument: we select "NIRCam" as the Instrument.

     • Template: we select the "NIRCam Coronagraphic Imaging" Template.

     • Target: we select "1 BETA-PIC" as the Target.

  6.  Observation 12

     • Number: we assign an Observation Number of "12".

     • Label: we provide the Observation Label "Beta Pic - LW Roll 1".

     • Instrument: we select "NIRCam" as the Instrument.

     • Template: we select the "NIRCam Coronagraphic Imaging" Template.

     • Target: we select "1 BETA-PIC" as the Target.

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:

¹ 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

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

²As 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:

1. In the tree editor, we select an observation from the MIRI coronagraphic observations folder (e.g. "Beta Pic - F2300C/Lyot Roll 1 (Obs 1)").
2. In the observation's template, we click on the tab labeled "Special Requirements".
3. In the Special Requirements box, we click the Add... button and select the Timing → Group/Sequence Observations Link option.
4. 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. 
5. 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:

1. We select an observation from the NIRCam coronagraphic observations folder (e.g. "Alpha Pic - LW PSF (Obs 7)")
2. Under the Special Requirements tab, we Add... a Timing → Group/Sequence Observations Link 
3. We select Obs 7, 8, 9, 10, 11, and 12 from in the Observation list
4. 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.

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:

1. 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)"
       
       
2. 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)"

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:

1. We select observation 10 "Beta Pic - SW Roll 1 (Obs 10)" from the NIRCam coronagraphic observations folder,
   1. 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)"
        
        
   2. 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)"
        
        
2. We select observation 2    "Beta Pic - LW Roll 1 (Obs 12)" from the NIRCam coronagraphic observations folder
   1.     
      
      • 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)
        
        
   2. 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. 

---