Contamination Overlap Tool
The Contamination Overlap Tool, used for planning JWST exoplanet observations, provides observing windows for targets and estimates a target's spectral contamination level due to neighboring sources in the field of view.
This tool, which helps users identify position angles that minimize potential contamination of target spectra from other nearby point sources, is comprised of 2 calculators
- The Visibility Calculator, which predicts the aperture position angles (APAs) that a target can be observed in, and their corresponding visibility windows (up to Dec 31, 2023).
- The Contamination Calculator, which determines the level of contamination on the target star from nearby point sources at each of these APAs.
Both calculators are available on the ExoCTK website with the Visibility Calculator available for all JWST instruments: NIRCam, MIRI, NIRISS, NIRSpec, and FGS 1 and 2. The Contamination Calculator on the website is currently available for the NIRISS SOSS mode.
If users have the ExoCTK package installed, the Contamination Calculator can also be called locally to calculate contamination for NIRCam grism time series (F322W2 and F444W) and MIRI low-resolution spectroscopy mode in addition to NIRISS SOSS. Note that the calculation for NIRCam and MIRI can take anywhere from 1–3 hours due to the complexity of their algorithms. We plan to provide optimized NIRCam and MIRI modes on the web version of ExoCTK prior to JWST Cycle 2.
Using the web interface
Clicking on the Contamination Overlap button under Observation Planning takes the user to the Contamination Overlap Tool in the "Contamination & Visibility Calculator" webpage.
Entering the target name and clicking Resolve Target will automatically fill in the R.A. and Decl. fields shown in Figure 2. Keep in mind that the target coordinates are retrieved from Exo.MAST. As such, if an input Target Name cannot be found in Exo.MAST, the webpage will return an error message from Resolve Target, and the R.A. and Decl. fields will need to be filled out manually.
Once all of the fields are complete, the final step is to submit! As shown below, users can choose to calculate the visibility windows of the target, or its visibility and contamination. The contamination calculation will take a while longer to run, as it generates a simulated field at every position angle.
Visibility Calculator (available online)
An example of the visibility results generated online are shown below for target WASP-18b using NIRISS. The green lines represent the aperture position angles (APAs) and time frames in which the target can be observed. Hovering over a region of the Bokeh plot on the website will show the maximum, nominal, and minimum aperture position angle corresponding to the telescope's maximum boresight roll for a given pointing and date. Users have the option to interact with the visibility plot using the toolbar on the right of the plot for zooming, panning, and saving the plot locally for future reference.
- Minimum V3 position angle (min_V3_PA), i.e., the angle of the entire spacecraft with maximum clockwise boresight (V1) roll
- Maximum V3 position angle (max_V3_PA), i.e., the angle of the entire spacecraft with maximum counter-clockwise boresight (V1) roll
- Minimum aperture position angle (min_Aperture_PA), i.e., the angle of the instrument with maximum clockwise boresight (V1) roll
- Maximum aperture position angle (max_Aperture_PA), i.e., the angle of the instrument with maximum counter-clockwise boresight (V1) roll
- Nominal aperture position angle (nom_Aperture_PA), i.e., the angle of the instrument with no roll
- Gregorian date (YYYY-MM-DD HH:MM:SS)
- Modified Julian Date (MJD)
Figure 6 shows an example .CSV file for the WASP-18 NIRISS observation opened with Mac Numbers. The output .CSV files can be opened with any data handling software.
Contamination Calculator for NIRISS SOSS mode (available online and locally)
If the user selects NIRISS - SOSS as their Instrument, there will be an option to calculate both visibility and contamination. The results page for this option will have another Bokeh plot at the bottom showing the target's contamination as a function of aperture position angle and wavelength (in μm). Figure 7 shows a screenshot taken from an example using WASP-18b observed in NIRISS's SOSS mode. The panels from left to right are:
- The % contamination in all wavelength channels for order 2 of the target trace. 100% would indicate total contamination of the target trace (in every channel), 0% would indicate no contamination. The green line represents a higher degree of contamination than the blue line.
- The contamination "map" for order 2 of the target trace.
- The contamination "map" for order 1 of the target trace.
- The % contamination in all wavelength channels for order 1 of the target trace. 100% would indicate total contamination of the target trace (in every channel), 0% would indicate no contamination.
Users can generate the plot below themselves with a local version of the ExoCTK package installed on their machine. For instructions on how to run the Contamination Calculator locally, continue onto the next section.
Contamination Calculator for NIRCam and MIRI modes (available locally)
The Contamination Overlap tool is available locally for NIRISS SOSS, NIRCam grism time series (F322W2 and F444W) and MIRI low-resolution spectroscopy mode.
Users can generate contamination plots locally using the Python magic module
make_contam_plot.py which can be found in the
contam_visibility/ folder in the ExoCTK repository. Each instrument/mode option uses their own contamination prediction algorithm. The NIRISS SOSS algorithm was developed by the University of Montreal, while the NIRCam and MIRI algorithms were developed at STScI and use the most up-to-date Science Instrument Aperture Files (SIAF) called from STScI's pySIAF package for more accurate contamination predictions.
Users can generate contamination plots for these modes with the following instructions:
make_contam_plot.htmlfor later use. Each time the Contamination Calculator is run locally, this HTML file is overwritten, so be sure to save a copy if you're planning to run it more than once. Depending on your browser of choice to open the HTML file, these can also be saved as PDFs.
Using the outputs
Once you have the outputs from the Contamination Overlap Tool, what do you do with them?
In the Astronomer's Proposal Tool (APT), there is a field in the Observation panel under Special Requirements that allows users to enter the Position Angle for the observations. Figure 11 shows the location of this field in APT version 27.2 (which is consistent with the latest APT version, which at the time of writing is 2020.4.1), using an example template of a NIRCam observation proposal.