A type of scattered light known as claws appears in NIRCam images when bright stars land in a susceptibility region outside the instrument's field of view. This light enters via a rogue path and, after multiple internal reflections, contaminates the shortwave detectors. Because the strength and morphology of claws change with the telescope V3 position angle (PA) (Sunnquist et al., 2022), users can run planned observations through the JWST Rogue Path Tool to predict claw flux at all possible PAs and adjust their APT settings to minimize or avoid them.

Installation

Installation instructions are available on the JWST Rogue Path Tool GitHub repository and are summarized below. The tool can be installed using pip in a new Conda environment:

$ conda create -n claws python=3.11
$ source activate claws
$ pip install jwst_rogue_path_tool

Alternatively, it can be installed from source:

$ git clone git@github.com:spacetelescope/jwst_rogue_path_tool.git
$ pip install .

Running the JWST Rogue Path Tool

This example demonstrates how to use the JWST Rogue Path Tool to identify PA ranges that minimize or are free from claws and how to adjust the observation in APT to ensure it is scheduled only within those ranges. A similar process is outlined in an example notebook available in the GitHub repository.

The tool requires the APT records file as input, which is a JSON file that contains various information on the pointing and instrument configuration for each observation in the program. This file can be obtained by opening the program in APT then File→Export→records.json file. For this example, we use the example records file contained in the GitHub repository.

To run the tool on an observation:

import os
import pathlib
from jwst_rogue_path_tool.detect_claws import aptProgram
from jwst_rogue_path_tool.plotting import create_v3pa_vs_flux_plot
from jwst_rogue_path_tool.constants import PROJECT_DIRNAME

# The program records file
apt_json_filename = pathlib.Path(PROJECT_DIRNAME) / "data" / "APT_test_4RPtool.records.json"

# The observation number of interest
obs_number = 5

# Run the tool
program = aptProgram(apt_json_filename, angular_step=1.0, usr_defined_obs=[obs_number])
program.run()

# Make plot of claws flux vs position angle
create_v3pa_vs_flux_plot(program.observations.data[obs_number], output_directory=pathlib.Path(os.getcwd()))

# Make file containing good position angles
program.make_background_report(program.observations.data[obs_number], output_directory=os.getcwd())

Figure 1 shows the output of the create_v3pa_vs_flux_plot() function—a plot of the predicted claw flux at each position angle for every filter. The horizontal orange and green lines indicate signal levels at 10% (based on minimum background throughout the year) and 20% (based on mean background throughout the year) of the predicted background levels, respectively. These thresholds help identify position angles with minimal or no claw contamination. Typically, the 20% threshold is sufficient, but for certain targets—such as faint, high-redshift objects—observers may prefer the more conservative 10% threshold.

Figure 2 shows the output of the make_background_report() function—a text file containing the PA ranges that minimize or avoid claws based on each threshold. The PA ranges in this file are determined conservatively by considering all filters together. If the predicted claw flux in any filter exceeds the threshold, the corresponding position angle is excluded from these ranges.

Once the PA ranges that minimize or avoid claws are determined, users can add them to their APT files as a PA Special Requirement to ensure their observations are only taken within those PA ranges. To do this, select the observation in APT, then go to Special Requirement→Add→Position Angle→PA Range and input each good PA range in the V3PA Range boxes. Each PA range should be entered as a separate Special Requirement. For example, using the 20% threshold, the first Special Requirement for the example observation above would be:

Aperture PA Range 359.92542306 to 80.92542306 Degrees (V3 0.0 to 81.0)

Currently, the tool does not take into account target visibility, so some of the PA ranges shown may not need to be considered. For example, if a strong claw is predicted at a PA that is never available in the roll analysis, users don't have to include special requirements to avoid that PA as it will never be used anyway. To check which PA ranges are actually available for a given visit, users can go to Visit Planner→Reports→Visitx.x→Total Roll Analysis For Visit.

Additional example use cases and functionality, such as running on all observations in a program and using custom thresholds, are available in the example notebook.

References

Sunnquist, B., Willmer, C., Brooks, B., et al., 2022, JWST-STScI-008304
NIRCam Commissioning Results NRC-10: Flat Fields, Scattered Light, and Backgrounds