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.
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.
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.
The JWST background cache
The JBT accesses a precompiled cached background model that was prepared by 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:
JBT can then be installed using pip:
If you have installed the tool previously and want to check for and install updates,
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:
3) Install jwst_backgrounds:
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:
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.
This command will open a GUI plot window and cause the background data to be plotted for RA=53.1625 degrees and DEC=-27.7914 degrees; 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.
Note that if you want to save one or both plots to a file, each GUI plot window has controls at lower left; select the disk icon to save the plot (png 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:
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().
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 micron, for the first day in the year for which they are visible.