JWST APT-ETC Connectivity
JWST APT contains boxes on exposure specification lines that permits users to to enter tracking information to specific ETC workbooks and calculations for reference. A handy link also allows users to enter the ETC directly from within APT, if desired.
APT contains data entry boxes (referred to here as the “ETC Wkbk.Calc ID boxes”) on the exposure specification lines in each observation template where the user can (at their discretion) add cross-reference information to a specific ETC workbook (WB) and calculation (CALC) ID within the notebook. For templates that include target acquisition (TA) exposures, entry of a cross reference to an ETC calculation is strongly encouraged to add confidence that the TA will be successful. For the science exposures, the user may find it useful for future reference to annotate one or more exposure specs with the ETC WB and CALC ID to inform the exposure information provided in APT, as described in more detail below.
Using the ETC Wkbk.Calc boxes
The use case assumed here is that the user has used the ETC to create one or more ETC WBs and generated any number of calculations within each; some CALCs may have been test calculations and others may represent the “final” CALC the user wants to transfer to a particular APT observation and exposure specification. It is the user’s responsibility to track which CALC(s) is (are) relevant for actual use in APT, perhaps using the “Notes” area within a given ETC WB and/or within APT Comment blocks.
While each ETC WB is given a name, it is also assigned an unique ID number; it is this number that is used for cross referencing in APT. Currently, the WB ID number can be found in the listing of your notebooks after you sign in to the ETC (Figure 1). Also, within each WB, each calculation is numbered (Figure 2). Hence, the combination of WB ID and CALC ID points to a unique calculation.
For example, if the WB ID is 1300 and the relevant calculation is #1, the user would enter 1300.1 into the relevant ETC Wkbk.Calc ID Box in APT.
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 by opening the ETC directly from within APT (Figure 3).
Connectivity between APT and ETC
As of version 26.1, 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: user is entering info into a new APT Observation template exposure specification
(a) If the user knows the relevant WB.CALC information for a given exposure, it can be entered directly into the relevant ETC Wkbk.Calc ID Box in APT.
(b) If the user only knows the WB ID but not the CALC ID to reference, enter only the WB ID and select the button to the right of the ETC Wkbk.Calc ID box. (Hovering over this button shows the pop up “Open ETC in separate browser window.”) Assuming it is a valid ETC WB ID number, the referenced WB will open in a separate browser window. You can then inspect the calculations and/or any tracking notes you may have entered in the ETC WB to identify the specific CALC you want to reference, and add that CALC ID to the entry in the ETC Wkbk.Calc ID Box in APT.
(c) If the user knows neither of these numbers, clicking on the "Open ETC" button will point the user to the ETC "Available Workbooks" pane (Figure 1) where a WB can be selected if desired. If an invalid ETC WB ID is entered, the user will see an error message “404: Not Found” in the browser. Of course, the user can just open the ETC separately on their own rather than using the APT-ETC connectivity capability to find the correct ETC WB to reference, if desired.
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 to inspect or confirm the information, select the button to the right of the ETC Wkbk.Calc ID box, and the referenced ETC WB (and CALC if provided) will open in the browser. You can then confirm the information in the referenced CALC.
Since 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.
Additional information and caveats
- Entering an ETC Wkbk.Calc ID into the box in APT is not validated unless the user tries to open the ETC from within APT. If the WB ID was valid but the CALC ID is not valid, the ETC WB will still be opened, and 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 Box in APT is independent and can point to different ETC WBs as needed. However, since each call to “Open ETC” will open a new instance of 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” blocks within APT. It is also up to the user as to whether they choose to indicate the ETC Wkbk.Calc ID in APT for this situation or track this information separately.
- The use of ETC Wkbk.Calc ID boxes in APT is optional (although strongly encouraged for any target acquisition specifications), and is primarily there to help the user 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. To reduce this risk, only "read" permissions are set by default when sharing workbooks.