JWST Backgrounds Tool

The JWST Backgrounds Tool (JBT) is a a simple command line tool that accesses the JWST background models to return the total background intensity and its components as a function of time. This can be useful for estimating and visualizing the impact of the background on the schedulability of JWST observations. It can also be used to retrieve the background intensity spectra and their components.

On this page

See also: JWST Background Model and JWST Background-Limited Observations

The JWST Backgrounds Tool (JBT) offers a convenient way to display observing dates for which the JWST background is within a given fraction of the minimum possible background for a given position on the celestial sphere. The tool is written in Python and accesses an online repository of the same background model cache that is used by the JWST ETC and the JWST scheduling system.

What does the JBT do?

For a given target (RA, Dec in decimal degrees), and wavelength (in microns), the JBT can do the following:

  • Plot the spectrum of the background for that target on a given calendar day.
  • Plot the total background for that target versus calendar day.
  • Compute and plot the number of days per year that the target is observable at low background, for a given wavelength and a selectable threshold. (We refer to this plot as a "bathtub curve" or "bathtub plot.")
  • Write the ASCII data for the background spectrum and bathtub curves to output files for use by other programs you may have or develop.

Bathtub curves

A bathtub curve is the total background intensity (in MJy/sr) at a single wavelength of interest as a function of day of the year. These curves often have steep sides with a central trough, reminiscent of a bathtub shape.

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

Limiting the background impacts the target visibility (hence, schedulability). These impacts can be assessed directly using a command line flag in the General Target Visibility Tool. To invoke a limited background for scheduling, set the Background Limited special requirement in APT.

The JWST background cache

The JBT accesses a precompiled cached background model that was prepared by the Space Telescope Science Institute. The background cache is hosted by the Mikulski Archive for Space Telescopes (MAST), so you need internet access to run the tool with the remote cache. For offline use, it is possible to download the full background cache to your local machine, although it is a large file (~50 GB). Instructions for downloading the background cache can be found in this MAST Newsletter article from August 2017.


The easiest way to install the JBT is to first install healpy, a required dependency, via:

$ conda config --add channels conda-forge
$ conda install healpy

JBT can then be installed using pip: 

$ pip install jwst_backgrounds

If you have installed the tool previously and want to check for and install updates,

$ pip install jwst_backgrounds --upgrade

Alternatively, you can also install the JBT manually as follows:

(1) Download jwst_backgrounds source code from https://github.com/spacetelescope/jwst_backgrounds

(2) Unpack the archive:

gunzip jwst_backgrounds_xx.tar.gz
tar -xvf jwst_backgrounds_xx.tar

3) Install jwst_backgrounds:

cd jwst_backgrounds
python setup.py install

Running the JBT from the command line

You can run the tool from the command line (easiest for casual use), or you can import it as a Python module, which is useful for writing scripts to carry out more detailed parameter studies. A complete description of available command line options and arguments can be displayed using the command:

jwst_backgrounds --help

Using the command line, the following command will plot the bathtub curve for a given RA, DEC and wavelength, and will also plot the background intensity spectrum for day 268 (where day=1 is January 1st). Note that the options (identified with "--") must come first.

 jwst_backgrounds --day 268 --showsubbkgs 53.1625 -27.7914 4.4

This command will open a GUI plot window and cause the background data to be plotted for RA = 53.1625° and Dec = -27.7914°; closing this plot will expose the second plot of the bathtub curve at 4.4 μm (in this example). Closing this plot will return control to the command line. Figure 1 shows the plots resulting from this example.

Figure 1. Example of JBT output

Top: The total background intensity spectrum and its components for the specified day of the year.
Bottom: The bathtub curve for the pointing at a specific wavelength. Only days for which the pointing is observable with JWST are displayed. The 2 horizontal lines mark the minimum value of the total background and the minimum value times the threshold factor. 

Note that if you want to save one or both plots to a file, each GUI plot window has controls at the lower left; select the disk icon to save the plot (png format, by default). Other controls in the GUI allow you to pan and zoom within a given plot as desired.

Some users may find it useful to have the data generated by the tool in ASCII files for use by other programs. By default, the tool outputs files "background.txt" and "background_versus_day.txt" to the current working directory. However, if you want to redirect this output to file names of your choosing, the tool help contains instructions to do this. Here is an example:

jwst_backgrounds --day 268 --showsubbkgs --background_file targ1_bkgd.txt --bathtub_file targ1_bathtub.txt  53.1625 -27.7914 4.4

Scripting the JBT

The JBT can be more flexible when imported into Python as a module. For instance, the following lines will replicate the command line example using the convenience method bg_tools.get_background().

>>>from jwst_backgrounds import jbt  
>>>jbt.get_background(223.555, -54.395, 2.15, thresh=1.1, plot_background=True, plot_bathtub=True, write_bathtub=True)

However, a primary reason to use the JBT Python module, rather than the command line, is to explore a parameter space. For that, we can access the background class, which will return the data, but will not create the plots. For instance, the following script will retrieve the backgrounds for the Hubble Ultra Deep Field, the Orion Trapezium cluster, and the Galactic Center and print their relative values at 4.4 μm, for the first day in the year for which they are visible.

from jwst_backgrounds import jbt 

pointings = [{'ra':53.1625,'dec':27.7914,'name':'HUDF'},
             {'ra':266.41683,'dec':-29.00781,'name':'Galactic Center'}]

wavelength = 4.4 #micron

for pointing in pointings:
    bg = jbt.background(pointing['ra'],pointing['dec'],wavelength)
    print(pointing['name'], bg.bathtub['total_thiswave'][0], 'MJy/sr')

Which returns:

HUDF 0.295932846194 MJy/sr
Trapezium 0.9383086522 MJy/sr
Galactic Center 13.2075661373 MJy/sr

Latest updates

  • Added clarifications to these instructions based of actual testing of the tool 
Originally published