JWST APT-ETC Connectivity

The JWST Astronomer's Proposal Tool (APT) allows users to enter tracking information referencing specific Exposure Time Calculator (ETC) workbooks and calculations.

On this page

        See also: JWST ETC to APT Interface Support Information

APT contains data entry boxes, called ETC Wkbk.Calc ID boxes, at the exposure specification lines in each observation template where users can (at their discretion) add cross-reference information to a specific ETC workbook (WB) and calculation (CALC) ID within the workbook.

For templates that include target acquisition (TA) exposures, an ETC calculation is strongly encouraged to add confidence that the TA will be successful. Adding a cross-reference to this calculation may prove useful in the event that the acquisition fails for some reason. For the science exposures, the user may also find it useful to annotate one or more exposure specs with the ETC WB and CALC ID for future reference, as described in more detail below.

All JWST ETC WBs are confidential. A user must have permission to view the indicated WB; if not, an error message ("404: Not Found") is produced in the browser. If you are a collaborator, contact the ETC workbook owner and have them provide permission to the ETC WB.

Using the ETC Wkbk.Calc boxes

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

It is assumed that a user has created one or more ETC WBs and generated several calculations in each; some CALCs may have been test calculations and others may represent the “final” CALC for a particular APT observation and exposure specification. It is the user’s responsibility to track which CALCs are relevant for actual use in APT, perhaps using the Notes section in an ETC WB and/or the APT Comment block.

When you log into the ETC, all workbook IDs associated with your account are listed in the Available Workbooks list (Figure 1); it is this number that is used for cross referencing in APT. When you load a workbook, its ID is displayed in the top left of the window and the Calculation IDs can be viewed in the Calculations tab (Figure 2). Hence, the combination of WB ID and CALC ID points to a unique calculation.

Figure 1. Locating the ETC Workbook ID

On the Available Workbooks pane, the workbook ID number is located on the far left, before the workbook name (denoted by the red box). Each workbook receives an unique ID number; this value cannot be changed by the user. The arrow indicates the example science program used in Figure 2.
Figure 2. Locating the Calculation ID

After opening a workbook, the calculation ID number can be found on the far left in the Calculations tab, as shown by the red box. This calculation ID is unique to each workbook and cannot be changed by the user. If a calculation is deleted, the ID number of that calculation will not be re-used within the workbook. Note that the workbook ID is shown at upper left, also highlighted by a red box.
The format expected for the ETC Wkbk.Calc ID boxes in APT are a combination of the WB ID and the CALC ID, separated by a decimal point: NNNNN.mmm, where NNNNN is the WB ID and mmm is the CALC ID (no leading zeroes needed).

If the user has kept track of the relevant WB.CALC numbers separately, they can be entered directly into the ETC Wkbk.Calc ID boxes in APT. The user can also validate these entries, as further explained below, by opening the ETC directly from within APT.

For the example shown in Fig. 3, the WB ID is 101013 and the relevant calculation for the referenced NIRCam observation is calculation #1; in this case the user would enter 101013.1 into the relevant ETC Wkbk.Calc ID box in APT as shown by the red highlight. Likewise, to annotate the MIRI calculation #10, Fig. 3 (bottom) shows the appropriate entry for the MIRI coordinated parallel observation.

Figure 3. ETC Wkbk.Calc ID examples in APT

Examples of the ETC Wkbk.Calc ID boxes filled out in APT for a NIRCam imaging observation (top) and a MIRI observation (bottom). Clicking on the button  below ETC, in both cases, will take the user to the specified workbook and calculation.

Connectivity between APT and ETC

APT provides a way to open a relevant ETC WB directly from within APT, and even open a specific CALC if the number is known. Here are some example use cases where this functionality might be useful.

Use case 1: A user is entering information into a new APT observation template exposure specification

  • If the user knows the relevant WB.CALC information for a given exposure, it can be entered directly into the corresponding ETC Wkbk.Calc ID field in APT.  

  • If the user only knows the WB ID but not the CALC ID, enter the WB ID and click the  button to the right of the ETC Wkbk.Calc ID field. (Hovering over this button shows the pop up “Open ETC in separate browser window.”) Assuming you entered a valid ETC WB ID number, the workbook will open in a separate browser window. You can then inspect the calculations and/or tracking notes you may have entered in the ETC WB to identify the specific Calc ID you want to reference in the ETC Wkbk.Calc ID field.

  • If the user knows neither of these numbers, clicking the  button in the ETC column will open an ETC window showing the Available Workbooks pane (Figure 1); a workbook ID can be entered in APT from that list.

  • If an invalid ETC WB ID is entered, an error message, “404: Not Found,” is displayed in the browser. In that case, open the ETC separately in another window, instead of using the APT-ETC connectivity capability, to find the correct ETC WB ID. 

Use case 2: Validating a previously entered ETC Wkbk.Calc ID entry in APT

If the user wants to open a specified ETC Wkbk.Calc ID entry to inspect the information, click the  button to the right of that field—this will open the referenced ETC WB (and CALC if provided) in the browser. You can then confirm the information in that referenced CALC.

Note: An ETC Wkbk.Calc ID number in APT is not validated until the user opens that calculation in the ETC from within APT.

Additional information and caveats

  • If the WB ID was valid but the CALC ID is not valid, the ETC WB will still be opened but it will be up to the user to select and enter a valid CALC ID in APT. If the entered ETC WB ID is invalid, you will receive an error message in the browser ("404: Not Found").

  • Some users may have multiple ETC WBs and want to reference CALCs from them. This is not a problem as each ETC Wkbk.Calc ID entry in APT is independent and can point to different ETC WBs. However, since each call to open the ETC will open a new instance of the ETC in a separate browser window, users should take care to avoid confusion with multiple WBs being open.

  • Another situation that may arise for some users is that a particular ETC calculation may be used as a template for scaling to additional target/observation combinations (as opposed to running a separate calculation for each target/observation combination). It is up to the user to track any such situations, either with annotations in the ETC WB or using the Comment block in APT. It is also up to the user to determine if they want to enter the ETC Wkbk.Calc ID number in APT for this situation or track this information separately.

  • Using the ETC Wkbk.Calc ID number in APT is optional (although strongly encouraged for any target acquisition specifications), and is primarily there to help users keep track of their assumptions, especially when looking back at the proposal after the fact. ETC workbooks are considered proprietary and will not be made available to reviewers of JWST proposals. However, for accepted proposals, users may be contacted by technical review staff requesting more information about the assumptions used so they can be verified (again, especially for target acquisitions) and having this information documented in APT will be beneficial and will speed up the review process for accepted proposals.

There are no protections in place to keep a user from changing a referenced CALC after the fact. To maintain the viability of the cross-referencing from APT to ETC, users should take care not to change or update calculations that they are cross-referencing to APT. Hence, users may want to wait until near the end of their proposal preparations to add the relevant links to the appropriate calculations.

If you share a notebook with collaborators, you should alert them to this concern. To reduce the risk of unintentional changes, permission is set to "read-only" by default when sharing workbooks.

Latest updates
    Revised figures and minor text updates for clarification.
Originally published