Importing Data into Cubeviz

Note

This is the config-specific version of documentation and is deprecated. See the general documentation for the most up-to-date information.

By design, Cubeviz only supports data that can be parsed as Spectrum objects. Spectrum supports 3D cubes and allows the Python-level interface and parsing tools to be defined in specutils instead of being duplicated in Jdaviz. Spectrum objects are very flexible in their capabilities, however, and hence should address most astronomical spectrum use cases. If you are creating your own data products, please read the page Creating Jdaviz-readable Products.

Cubeviz will automatically parse the data into the multiple viewers as described in Displaying Cubes. For the best experience, data loaded into Cubeviz should contain valid WCS keywords. For more information on how Spectrum uses WCS, please go to the Spectrum defining WCS section. To check if your FITS file contains valid WCS keywords, please use Astropy WCS validate. For an example on loading a cube with valid WCS keywords, please see the Importing data via the API section below.

Loading data without WCS is also possible as long as they are compatible with Spectrum. However, not all plugins will work with this data.

In Cubeviz, two image viewers at the top display your data:

Top Left: flux-viewer

Top Right: uncert-viewer

There is also a third viewer called spectrum-viewer at the bottom that will display the collapsed spectrum from flux-viewer.

Note

Only a single cube can be displayed in an instance of Cubeviz at a given time. To open a second cube, you must first initiate a second instance of Cubeviz.

To then extract your data from Cubeviz, please see the Exporting Data from Cubeviz section.

Importing data through the Command Line

You can load your data into the Cubeviz application through the command line. Specifying a data product is optional:

jdaviz --layout=cubeviz /my/directory/cube.fits

Importing data through the UI

Users may load data into the Cubeviz application by clicking the Import Data button at the top left of the application’s user interface. This opens a dialogue with a prompt to select a file that can be parsed as a Spectrum object.

After clicking Import, the data file will be parsed and loaded into the application. A notification will appear to confirm whether the data import was successful. Afterward, the new data set can be found in the Data tab of each viewer’s options menu as described in Selecting a Data Set.

Importing data via the API

Alternatively, users who work in a coding environment like a Jupyter notebook can access the Cubeviz helper class API. Using this API, users can load data into the application through code with the load_data() method, which takes as input a Spectrum object.

FITS Files

The example below loads a FITS file into Cubeviz:

from jdaviz import Cubeviz
cubeviz = Cubeviz()
cubeviz.load_data("/path/to/data/file.fits")
cubeviz.show()

Spectrum (from file)

For cases where the built-in parser is unable to understand your file format, you can try the Spectrum parser directly and then pass the object to the load_data() method:

from specutils import Spectrum
from jdaviz import Cubeviz
spec3d = Spectrum.read("/path/to/data/file.fits")
cubeviz = Cubeviz()
cubeviz.load_data(spec3d, data_label='My Cube')
cubeviz.show()

Spectrum (from array)

You can create your own Spectrum object by hand to load into Cubeviz:

import numpy as np
from astropy import units as u
from astropy.wcs import WCS
from specutils import Spectrum
from jdaviz import Cubeviz

flux = np.arange(16).reshape((2, 2, 4)) * u.Jy
wcs_dict = {"CTYPE1": "WAVE-LOG", "CTYPE2": "DEC--TAN", "CTYPE3": "RA---TAN",
            "CRVAL1": 4.622e-7, "CRVAL2": 27, "CRVAL3": 205,
            "CDELT1": 8e-11, "CDELT2": 0.0001, "CDELT3": -0.0001,
            "CRPIX1": 0, "CRPIX2": 0, "CRPIX3": 0}
w = WCS(wcs_dict)

cube = Spectrum(flux=flux, wcs=w)
cubeviz = Cubeviz()
cubeviz.load_data(cube, data_label='My Cube')
cubeviz.show()

JWST datamodels

If you have a stdatamodels.datamodels object, you can load it into Cubeviz as follows:

import numpy as np
from astropy.wcs import wcs
import astropy.units as u
from specutils import Spectrum
from jdaviz import Cubeviz
from jwst import datamodels

file = "/path/to/data/file.fits"
mydatamodel = datamodels.open(file)

# mydatamodel is a jwst.datamodels object
# Due to current schema in jwst.datamodels, you'll need to create your own WCS object before you create your Spectrum object
wcs_dict = {"CTYPE1": mydatamodel.meta.wcsinfo.ctype3, "CTYPE2": mydatamodel.meta.wcsinfo.ctype2,
        "CTYPE3": mydatamodel.meta.wcsinfo.ctype1,
        "CRVAL1": mydatamodel.meta.wcsinfo.crval3, "CRVAL2": mydatamodel.meta.wcsinfo.crval2,
        "CRVAL3": mydatamodel.meta.wcsinfo.crval1,
        "CDELT1": mydatamodel.meta.wcsinfo.cdelt3, "CDELT2": mydatamodel.meta.wcsinfo.cdelt2,
        "CDELT3": mydatamodel.meta.wcsinfo.cdelt1,
        "CRPIX1": mydatamodel.meta.wcsinfo.crpix3, "CRPIX2": mydatamodel.meta.wcsinfo.crpix2,
        "CRPIX3": mydatamodel.meta.wcsinfo.crpix1}
my_wcs = WCS(wcs_dict)

# Next, you need to make sure your spectral axis is the 3rd dimension
data = mydatamodel.data * (u.MJy / u.sr)
data = np.swapaxes(data, 0, 1)
data = np.swapaxes(data, 1, 2)

# Create your spectrum1
spec3d = Spectrum(data, wcs=my_wcs)
cubeviz = Cubeviz()
cubeviz.load_data(spec3d, data_label='My Cube')
cubeviz.show()

There is no plan to natively load such objects until datamodels is separated from the jwst pipeline package.

Numpy array

To load a plain Numpy array without WCS:

import numpy as np
from jdaviz import Cubeviz
flux = np.arange(16).reshape((2, 2, 4))  # x, y, z
cubeviz.load_data(flux, data_label='My Cube')
cubeviz.show()

Importing regions via the API

If you have a region file supported by Reading/Writing Region Files, you can load the regions into Cubeviz as follows:

cubeviz.plugins['Subset Tools'].import_region("/path/to/data/myregions.reg")

Unsupported regions will be skipped and trigger a warning. Those that failed to load, if any, can be returned as a list of tuples of the form (region, reason):

bad_regions = cubeviz.plugins['Subset Tools'].import_region("/path/to/data/myregions.reg", return_bad_regions=True)

Note

Sky regions are currently unsupported in Cubeviz, unlike Imviz.

Loading from a URL or URI

See also

Load from URL or URI

Imviz documentation describing load from URI/URL.