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.

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.

Installation

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.

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().

python                                                      
>>>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':83.8187,'dec':-5.3872,'name':'Trapezium'},
             {'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