Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

IRSA Notebooks

Using SPHEREx HiPS All-Sky Mosaic Cubes

1. Learning Goals

2. SPHEREx Overview

SPHEREx is a NASA Astrophysics Medium Explorer mission that launched in March 2025. During its planned two-year mission, SPHEREx will obtain 0.75-5 micron spectroscopy over the entire sky, with deeper data in the SPHEREx Deep Fields. SPHEREx data will be used to:

The community will also mine SPHEREx data and combine it with synergistic data sets to address a variety of additional topics in astrophysics.

More information is available in the SPHEREx Explanatory Supplement.

3. Imports

The following packages must be installed to run this notebook.

/home/runner/work/irsa-tutorials/irsa-tutorials/.tox/py312-buildhtml/lib/python3.12/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

4. Understanding the HiPS All-Sky Mosaic Cube

We first spend some time to understand the format of the HiPS All-Sky Mosaic Cube. To interact with the cube, we need an URL where it is hosted. There are two URLs:

We can first load the HiPS properties from the properties metadata. For this, we have to retrieve the HiPS from the above URL. We do this by using the requests library.

Once loaded, we can create a property dictionary.

From the properties, we can print the description of the HiPS mosaic cube for more information.

'SPHEREx DR1 all-sky data cube for visualization: 102 frames in ascending wavelength, one per band (1-6) and channel (1-17), frame index = 17*(band-1) + (channel-1). Frames 50 and 51 (band 3 channel 17, band 4 channel 1, the dichroic channels) are blank. See the SPHEREx Explanatory Supplement: https://irsa.ipac.caltech.edu/data/SPHEREx/docs/SPHEREx_Expsupp.pdf'

Another important property is the wavelength encoding of the cube layers. Let’s load these in a nice table.

Loading...

We see that each HiPS cube has 102 wavelength layers, which we have linked to wavelengths (in μm\mu m) in the table wavetab. Next, we use Firefly to visualize the All-Sky HiPS mosaic cube.

5. HiPS All-Sky Cube in Firefly

We first demonstrate how we can use Firefly to open and explore an All-Sky HiPS mosaic cube. For this, we first have to define the URL of the HiPS cube. This will then be loaded in Firefly.

First, let’s define some coordinates. These are later used to center the Firefly visualization and also retrieve the FITS cube.

Now start the Firefly server.

Now, we open the HiPS All-Sky Mosaic Cube in Firefly. We can also define the field of view of the visualizer.

{'success': True}

Let’s choose a wavelength to center the cube layer on.

... and select the correct layer.

Wavelength 3.3 um is closest to layer 62

With this separate dispatch, we can choose the wavelength layer.

Now that we know the layer that connects to the chosen wavelength, we can send an additional dispatch to Firefly to open the layer corresponding to the chosen wavelength.

{'success': True}

6. Download and Display HiPS FITS Cube

6.1 Download HiPS FITS Cube

Next, we show how to download a HiPS cube in FITS format for a given Healpix pixel. For this, we first have to find the Healpix pixel corresponding to our coordinates. Then we have to construct the URL to the corresponding FITS cube, which we then can load using the astropy package.

To find the Healpix pixel corresponding to the R.A./Decl. coordinates, we make use of the healpy package (which we imported above). Note that we are assuming her HiPS order 5, which is the smallest scale that is supported by the current SPHEREx All-Sky Mosaic. But in principle, you can choose an order, if available. We can directly check the properties dictionary that we have created above to find out what the minimum and maximum HiPS order is:

Minimum HiPS order (largest spatial scale): 0
Maximum HiPS order (smallest spatial scale): 5

Choose Norder:

Finally get the Healpix pixel number corresponding to our search coordinates.

Healpix pixel number corresponding to R.A. = 60.8109955 deg and Decl. = 51.3404038 deg: 445

Now that we know the Healpix pixel number, we can construct the URL leading to the FITS cube.

Cube URL: https://irsa.ipac.caltech.edu/ibe/data/spherex/dr1/hips5_cube/hips_20261026/Norder5/Dir0/Npix445_cube.fits

Once we have the cube URL, we can load the FITS cube directly.

6.2 Display HiPS FITS Cube

Next, we demonstrate how to load the FITS cube and how to display a specific layer of it.

The SPHEREx HiPS FITS cube consists of different extensions.

For more information on these layer and the FITS cube construction, we refer to the “Mosaics” Section of the SPHEREx Explanatory Supplement.

First, we open the FITS cube using the cube_url that we have defined above.

Filename: /tmp/astropy-download-4942-1tezud1k
No.    Name      Ver    Type      Cards   Dimensions   Format
  0  PRIMARY       1 PrimaryHDU      15   ()      
  1  IMAGE         1 ImageHDU        47   (512, 512, 102)   float32   
  2  NHITS         1 ImageHDU        47   (512, 512, 102)   int32   
  3  FLAGS         1 ImageHDU       114   (512, 512, 102)   int32   
  4  SPECTRAL_CHANNELS    1 BinTableHDU     35   102R x 8C   [I, I, E, E, E, E, E, E]   
  5  WCS-WAVE      1 BinTableHDU     18   1R x 3C   [102J, 102E, 102E]   

Let’s first check the dimensions of the cube. It should have 102 layers, corresponding to the wavelengths.

Cube shape: (102, 512, 512)

In addition, we can also read in the spectral channels table, that contains more information on the wavelength of the channels and their widths. Let’s look at it here.

Loading...

Let’s select again the same layers corresponding to the wavelength we want and plot the image. We extract the 2D image, hit map, and flag map at the requested layer.

Finally plot the image with the coordinates indicated. Note that we have to use the WCS transformation here.

<Figure size 1800x600 with 6 Axes>

6.3 Drill Through the FITS Cube

We can extract a very basic spectrum directly from the FITS cube.

To obtain the spectrum, we create a function that computes the sum of the fluxes in apertures and does a background subtraction using an annulus. Both aperture and annulus sizes are user-defined. We use the PhotUtils package for this (see here for more information). The measurements are done for each cube plane and the combined. Furthermore, the function creates a plot showing the collapsed cube and the apertures used (this output can be turned off).

<Figure size 500x500 with 1 Axes>
Loading...

Now that we have extracted the spectrum, let’s plot it. In this tutorial, we have targeted a cloud in the Milky Way, which is characterized by strong Polycyclic Aromatic Hydrocarbon (PAH) emission. We see that in the spectrum that we extracted.

We first define the default lines to plot...

And then define a handy function to plot the spectrum given the DEFAULT_LINES and the photometry table.

And finally, we can plot the spectrum

<Figure size 800x400 with 1 Axes>

6.4 Show Spectrum in Firefly

Finally, we can also show the spectrum in Firefly directly. The Firefly visualizer even allows to add certain emission lines ones the redshift is fixed. Before doing that, we have to convert our table phot_table in the correct format. To this end, we define a small function that does the conversion.

Before we convert the table, we convert mJy to μ\muJy since Firefly does not recognize it as flux unit.

Now we add a new Firefly instance to plot the spectrum, we call it fc_spec.

Loading...

And finally, we can load the spectrum.

{'success': True}

Acknowledgements

About this notebook

Updated: 4 November 2026

Contact: Contact IRSA Helpdesk with questions or problems.

Runtime: This notebook takes about 1-3 minutes to run to completion on a machine with 16GB RAM and 4 CPU. Note that the run time depends mostly on your internet connection, as the FITS cube (~300 MB) has to be downloaded by astropy.io.fits.