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. 

On this page

See also: JWST Position Angles, Ranges, and Offsets and JWST Observatory Coordinate System and Field of Regard

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.

Figure 1. ExoCTK home page

The "Contamination & Visibility Calculator" page has fields for providing either the target name or its coordinates (in decimal degrees).

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. 

Figure 2. ExoCTK Contamination Overlap Tool

Contamination Overlap Tool target resolver fields in the Contamination & Visibility Calculator page.
Next, the Instrument - Mode field tells the algorithm which instrument and observing mode the visibility and contamination are being calculated for. The Visibility Calculator is available for all JWST instruments, while the Contamination Calculator is available on the website for NIRISS SOSS observations.
Figure 3. Instrument mode field for the Contamination Overlap Tool

There is an optional field for target companions that are not already in the contamination results: Add a close binary companion not present in 2MASS. If there is a point source near the target that is not part of IRSA's 2MASS Point-Source Catalog, but should be considered for the contamination calculation, users can complete this field and the companion will be considered for the final results.

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. 

Figure 4. Field for adding a close binary companion not in the 2MASS catalog

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. 

Figure 5. ExoCTK website example of visibility results for WASP-18b using NIRISS 

Users have the option to download a .CSV file that contains a table of the data used to generate the visibility plot. By clicking the Download CSV File button, a .CSV file will be downloaded with the following columns of data:

  1. Minimum V3 position angle (min_V3_PA), i.e., the angle of the entire spacecraft with maximum clockwise boresight (V1) roll
  2. Maximum V3 position angle (max_V3_PA), i.e., the angle of the entire spacecraft with maximum counter-clockwise boresight (V1) roll
  3. Minimum aperture position angle (min_Aperture_PA), i.e., the angle of the instrument with maximum clockwise boresight (V1) roll
  4. Maximum aperture position angle (max_Aperture_PA), i.e., the angle of the instrument with maximum counter-clockwise boresight (V1) roll
  5. Nominal aperture position angle (nom_Aperture_PA), i.e., the angle of the instrument with no roll
  6. Gregorian date (YYYY-MM-DD HH:MM:SS)
  7. 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. 

Figure 6. Example .CSV file for the WASP-18 NIRISS observation

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: 

  1. 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.
  2. The contamination "map" for order 2 of the target trace. 
  3. The contamination "map" for order 1 of the target trace. 
  4. 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.

Figure 7. ExoCTK website example of visibility and contamination for WASP-18b observed by NIRISS SOSS

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 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: 

Figure 8. Instructions for generating contamination plots
The first step after installing the ExoCTK package is to go (using the cd command) into the ExoCTK repository's contam_visibility/ folder within your local clone of the ExoCTK repository. Initiate your ExoCTK Python environment and run the script called located in this folder like so:

The script will prompt you with a series of inputs needed to query for sources near your target and calculate their contamination. 

The first input will be the right ascension (RA) of your target, as shown below. Please do not round off the value; enter as many decimal places as possible for improved accuracy, especially if there is a close companion star of the target. If you receive an "Exception error message," you will need to add more decimal places to your coordinates. Otherwise, please contact the JWST help desk.

The next input is the declination (DEC) of your target in decimal degrees. Again, please do not round the value. More decimal places means more precision. 

The algorithms search for nearby sources using IRSA's 2MASS Point-Source Catalog. If there are any potentially contaminating stars near your target that are not part of this catalog, please input their information in the next field as instructed below. This nearby point source will be added to the final calculation. 

Lastly, enter the instrument (or in NIRCam's case, instrument and filter) that will be used for your observation. This field is case-sensitive and the script will prompt you to start over if the incorrect case is used. 

When all inputs are submitted, the algorithm will perform the calculation. The script will return progress updates so users can keep track of how much is left until completion. A field will be generated for all 360 aperture position angles (APAs) for the contamination calculation. 

Figure 9.  Example output HTML of the local version of the Contamination Calculator

The output HTML will automatically be saved in the contam_visibility/ folder as make_contam_plot.html for 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.
Figure 10. Exporting the contamination plot to a PDF file

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.

Figure 11. Entering the position angle in APT

Latest updates