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.
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.
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 italics are also buttons
or parameters in GUI tools. Bold
style represents GUI menus/
panels & data software packages.
When you log into ETC, all workbook IDs associated with your account are listed in the front page (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.
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.
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 ETC Wkbk.Calc ID button to the right of the 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 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.