ExoCTK Contamination Overlap Tool

The Contamination Overlap Tool is an observation planning tool that will provide the windows of time in which a given target may be observed and will also provide the levels of estimated contamination on the target's spectra 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 is comprised of 2 calculators:

1. 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, 2024).

2. The Contamination Calculator, which determines the level of contamination on the target star from nearby point sources at each of these APAs.

These tools will aid the user in deciding which Position Angles to observe in, which will minimize potential contamination of target spectra from other point sources.

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.

Preliminary results from observatory commissioning indicate that distortion corrections need to be applied to precisely predict the final positioning of (contaminating) sources in the detector. The current version of the Contamination Overlap tool does not account for those distortions. Updates needed for Cycle 2 proposal preparation will be available in early December 2022.




Using the web interface

The Contamination Overlap tool can be found on the main page of the ExoCTK website under Observation Planning. 

Figure 1. The ExoCTK Website 


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

The Contamination Overlap page will provide a field where users can input either the target name or its coordinates (in decimal degrees). Putting in the target name and clicking Resolve Target will automatically fill in the R.A. and Decl. fields below. 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. Defining the target properties in the Contamination Overlap tool


The next required field is the Instrument - Mode field. This will tell our tool 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. Defining the instrument properties in the Contamination Overlap tool


There is an optional field for adding an extra target companion or neighbor to be included in the contamination results. 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, filling out this field will add the companion/neighbor to be considered in 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 Visibility and Contamination option will take a few seconds longer to run, as it generates a simulated field at every position angle of the instrument. 

Figure 4. Defining optional target companions on the Contamination Overlap tool


Visibility Calculator (available online)


After completing the steps above, the first result you should see is the Visibility Calculator result. An example of the Visibility Calculator output is shown below for target WASP-18b using the NIRISS instrument. The green lines represent the Aperture Position Angles (APAs) in which the target can be observed, and the corresponding date (YYYY-MM-DD) the target can be observed in said angle. Hovering over a region of the bokeh plot on the website will show the maximum, nominal, and minimum Aperture Position Angle, given the maximum boresight roll1 of the telescope for a given point, as well as the corresponding date. Users have the option to interact with the Visibility plot using the toolbar to the right of the plot which allows for zooming, panning, and saving the plot locally for future reference. 

Figure 5. Output of the Target Visibility tool


Users also have the option to download a .CSV file that contains a table with the data used to generate the visibility plot. By pressing the Download CSV File button below the plot, 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 JWST spacecraft with maximum clockwise boresight (V1) roll
  2. Maximum V3 Position Angle (max_V3_PA), i.e. the angle of the entire JWST spacecraft with maximum counter-clockwise boresight (V1) roll
  3. Minimum Aperture Position Angle (min_Aperture_PA), i.e. the angle of the JWST instrument with maximum clockwise boresight (V1) roll
  4. Maximum Aperture Position Angle (max_Aperture_PA), i.e. the angle of the JWST instrument with maximum counter-clockwise boresight (V1) roll
  5. Nominal Aperture Position Angle (nom_Aperture_PA), i.e. the angle of the JWST instrument with no roll
  6. Gregorian date (YYYY-MM-DD HH:MM:SS)
  7. Modified Julian Date (MJD)

Below is 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 output of the target visibility tool


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 the visibility and contamination on the target. 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 microns). The following is a screenshot taken from an example using WASP-18 b observed in NIRISS's SOSS mode. The following is an explication of the key features in the contamination plot: 

  1. Panel 1 (Left-most): The % contamination of all spectral channels that are contaminated for Order 2 at a level of at least 0.01 (green) or 0.001 (blue). 100% would indicate total contamination of the target trace (in every channel), 0% would indicate no contamination. 
  2. Panel 2: The contamination for order 2 of the target trace: The contamination level is defined as the ratio of the extracted flux coming from all field stars over the extracted flux coming from the target star, using the proper extraction weighing function for the target trace. The deeper the color, the higher the degree of contamination, with white representing no contamination. The corresponding wavelength is in microns.
  3. Panel 3: The contamination for order 1 of the target trace. 
  4. Panel 4 (Right-most): The % contamination of all spectral channels that are contaminated for Order 1 at a level of at least 0.01 (green) or 0.001 (blue). 100% would indicate total contamination of the target trace (in every channel), 0% would indicate no contamination. 
  5. The grey semi-transparent regions represent APAs that the target cannot be observed in. 
  6. The scale below the plot is the color scale denoting the levels of contamination, with white representing no contamination on the target. 

Users can generate the plot below themselves with a local version of the ExoCTK package installed. For instructions on how to run the Contamination calculator locally, continue onto the next section.

Figure 7. Outputs of the Contamination Overlap tool



Using the outputs

Once you have your outputs from Contamination Overlap, 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 input what Position Angles the observations should be taken in. A demonstration of where this field is in APT is below. The figures below are of the APT version 27.2, using an example template of a NIRCam observation proposal.

Figure 10.  Using outputs of the Contamination Overlap tool in APT


Links

JWST Position Angles, Ranges, and Offsetshttps://jwst-docs.stsci.edu/jwst-observatory-functionality/jwst-position-angles-ranges-and-offsets

 NIRISS Single Object Slitless Spectroscopyhttps://jwst-docs.stsci.edu/near-infrared-imager-and-slitless-spectrograph/niriss-observing-modes/niriss-single-object-slitless-spectroscopy

NIRCam Grism Time Series

MIRI Low Resolution Spectroscopy




Latest updates
Originally published