ExoCTK Phase Constraint Calculator Tool

The Phase Constraint Calculator provides phase-constraint observation windows for exoplanet transits and eclipses for use in the Astronomers Proposal Tool (APT).

On this page

See also: JWST Astronomers Proposal Tool Overview, APT Special RequirementsStep-by-Step ETC Guide for NIRSpec BOTS Observations of WASP-79b

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

Scheduling start times for visits targeting periodic events such as exoplanetary transits and eclipses with JWST typically requires one to define a range of times—through a window in phase-space — that the observatory should aim to target. Due to uncertainties on the exact scheduling time of JWST observations, these windows are strongly encouraged to be of one hour or larger in order to not incur direct scheduling overheads. The Phase Constraint Calculator provides a simple interface for calculating possible JWST observation windows for direct input to APT.

The web-based version of this tool is part of the STScI's Exoplanet Characterization ToolKit (ExoCTK) suite of web-based services. The tool is also available as an importable python module through the ExoCTK python library.



Using the web interface

The web-based interface for the Phase Constraint Calculator has several options to retrieve phase constraints for a given system. First, orbital data (such as the Period, Eccentricity, Argument of periastron and Inclination) can be ingested directly by the user or chosen to be retrieved directly from exo.MAST by entering the exoplanet name in the Target Name box, and clicking the Resolve Target button; an example for WASP-18b is shown in Figure 1. In addition, the user has to decide if phase constraints are to be calculated for Primary Transit (i.e., when the planet passes in front of the star from our point of view at Earth/JWST) or Secondary Eclipses (i.e., when the planet passes behind of the star). The example in Figure 1 shows the default case which is PrimaryTransit.

Figure 1. Orbital data interface for the Phase Constraint Calculator

Next, in the Pre mid-transit/eclipse time on target field, the user needs to define the time to be spent, in hours, on the target prior to mid-transit or mid-eclipse. By default, if the user used the Resolve Target button to obtain the properties of the desired exoplanet in the example above, this time is automatically set to 0.75 Hr + Max(1 Hr + T14/2, T14), where T14 is the total transit duration (which is retrieved from exo.MAST). This time is actually the recommended amount of time to be spent prior to mid-transit (see some example science use cases), as it allows time to obtain sufficient baseline pre-transit/eclipse data to account for possible systematic effects that might need to be modeled to obtain precise transit/eclipse depths from JWST data. Finally, the user can also enter a Window Size which will define the phase constraint window the observatory should target to start the observations; the default is one hour, as seen below. 
Figure 2. Window and target time interface for Phase Constraint Calculator

Once the data have been input, the user can hit the green Calculate Phase Constraint button to perform the calculation, as has been done in the example below:
Figure 3. Calculation Button and Output of Phase-Constrain Calculator


Here, the Minimum Phase and the Maximum Phase are the ranges in phase space (where phase equals to zero is assumed to be the time-of-transit) that define the one hour windows in order to spend at least the amount of time defined above prior to mid-transit/eclipse. These values can be input directly into the appropriate fields in APT. If the user retrieved the data from exo.MAST using the Resolve Target button presented above, the value under Transit Mid-Point is the value one has to input under Zero Phase in APT.  Note this is the case even if the Target Observation mentioned above was Secondary Eclipse instead of Primary Transit: for the Phase Constraint Calculator the "Zero Phase" is always defined as the time of Primary Transit. Inserting those values into APT is described below.



Using the Phase Constraint Calculator output parameters in APT

Once results have been obtained with the Phase Constraint Calculator tool, they can be placed in the APT proposal. To do this, go to the APT Observation Folder, select the Observation, and click Special Requirements. Here, under Add, select TimingPhase, which will in turn open the Phase window where you will be able to enter the results from the calculator. The example in Figure 4 shows how results obtained above for the Primary Transit of WASP-18b were entered in the APT Phase fields.

Figure 4. APT input using Phase Constraint Calculator output 




Latest updates
Originally published