Importing Data into Cubeviz
By design, Cubeviz only supports data that can be parsed as
Spectrum1D
objects. Despite the name, Spectrum1D
now supports 3D cubes and allows the Python-level interface and parsing tools to
be defined in specutils
instead of being duplicated in Jdaviz.
Spectrum1D
objects are very flexible in their capabilities, however,
and hence should address most astronomical spectrum use cases.
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 Spectrum1D
uses WCS, please go to the Spectrum1D 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 Spectrum1D
. 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:
jdaviz cubeviz /my/directory/cube.fits
Importing data through the GUI
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 Spectrum1D
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_spectrum()
method, which takes as input a Spectrum1D
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()
Spectrum1D (from file)
For cases where the built-in parser is unable to understand your file format,
you can try the Spectrum1D
parser directly and then pass the object to the
load_data()
method:
from specutils import Spectrum1D
from jdaviz import Cubeviz
spec3d = Spectrum1D.read("/path/to/data/file.fits")
cubeviz = Cubeviz()
cubeviz.load_data(spec3d, data_label='My Cube')
cubeviz.show()
Spectrum1D (from array)
You can create your own Spectrum1D
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 Spectrum1D
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 = Spectrum1D(flux=flux, wcs=w)
cubeviz = Cubeviz()
cubeviz.load_data(cube, data_label='My Cube')
cubeviz.show()
JWST datamodels
If you have a jwst.datamodels object, you can load it into Cubeviz as follows:
import numpy as np
import astropy.wcs as fitswcs
from jdaviz import Cubeviz
# 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 Spectrum1D 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 = Spectrum1D(data, wcs=my_wcs)
cubeviz = Cubeviz()
cubeviz.load_spectrum(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.
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.load_regions_from_file("/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.load_regions_from_file("/path/to/data/myregions.reg", return_bad_regions=True)
Note
Sky regions are currently unsupported in Cubeviz, unlike Imviz.
For more details on the API, please see
load_regions_from_file()
and load_regions()
methods
in Cubeviz.