Importing Data into Imviz

Imviz can load data in the form of a filename (FITS, JPEG, or PNG), an NDData object, or a NumPy array if the data is 2D. See jdaviz.configs.imviz.helper.Imviz.load_data() for more information.

Note

Loading too many datasets will cause performance problems due to the number of links necessary; see The linking framework for more information.

Importing data through the Command Line

When running the Imviz application via the command line, you must provide a path to a compatible file, which will be loaded into the app on initialization:

jdaviz imviz /my/image/data.fits

Importing data through the GUI

You can load your data into the Imviz application by clicking the Import Data button at the top left of the application’s user interface. This opens a dialogue where the user can select a file that can be parsed as a NDData, HDUList, or ImageHDU in the text field.

After clicking Import, the data file will be parsed and loaded into the application. A notification will appear to let users know if 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 Imviz helper class API. Using this API, users can load data into the application through code with the load_data() method, which takes as input either the name of a local file or an NDData, HDUList, or ImageHDU object.

FITS Files

The example below loads the first science extension of the given FITS file into Imviz:

from jdaviz import Imviz
imviz = Imviz()
imviz.load_data("/path/to/data/image.fits")
imviz.show()

Creating Your Own Array

You can create your own array to load into Imviz:

import numpy as np
from jdaviz import Imviz

arr = np.arange(100).reshape((10, 10))
imviz = Imviz()
imviz.load_data(arr, data_label='my_array')
imviz.show()

JWST datamodels

If you have a jwst.datamodels object, you can load it into Imviz as follows:

import numpy as np
from astropy.nddata import NDData
from jdaviz import Imviz

# mydatamodel is a jwst.datamodels object
ndd = NDData(np.array(mydatamodel.data), wcs=mydatamodel.get_fits_wcs())
imviz = Imviz()
imviz.load_data(ndd, data_label='my_data_model')
imviz.show()

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

Batch Loading Multiple Images

To save on performance while loading multiple images into Imviz, you can optionally use batch_load() to parse all of the data first (within a for loop or multiple calls to load_data, for example), and defer the linking and loading of the new data entries into the viewer until after the parsing is complete:

from jdaviz import Imviz
imviz = Imviz()
with imviz.batch_load():
    for filepath in filepaths:
        imviz.load_data(filepaths)
imviz.show()

Importing catalogs via the API

If you have a catalog file supported by astropy.table.Table, you can load the catalog into Imviz and add markers to Imviz viewers to show positions from the catalog. These markers are different than Imviz spatial regions as they are only meant to mark catalog positions. Loading markers can be done with the following commands:

viewer.marker = {'color': 'green', 'alpha': 0.8, 'markersize': 10, 'fill': False}
my_markers = Table.read('my_catalog.ecsv')
coord_i2d = Table({'coord': [SkyCoord(ra=my_catalog['sky_centroid'].ra.degree,
                                      dec=my_catalog['sky_centroid'].dec.degree,
                                      unit="deg")]})
viewer.add_markers(coord_i2d, use_skycoord=True, marker_name='my_markers')

If you have a large catalog, you might want to filter your table to the marks of interest before adding them to Imviz, in order to avoid performance issues associated with adding large numbers of markers. For instance, if your image has FITS WCS, you could use astropy.wcs.WCS.footprint_contains if you only want the marks within a footprint. Alternately, you could filter by relevant columns in your catalogs, such as brightness, distance, etc.

And to remove those markers:

viewer.remove_markers(marker_name='my_markers')

Importing regions via the API

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

imviz.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 = imviz.load_regions_from_file("/path/to/data/myregions.reg", return_bad_regions=True)

You could also define Region Shapes programmatically and load them; e.g.:

from regions import CirclePixelRegion, PixCoord
aper_1 = CirclePixelRegion(center=PixCoord(x=42, y=43), radius=4.2)
aper_2 = CirclePixelRegion(center=PixCoord(x=10, y=20), radius=3)
imviz.load_regions([aper_1, aper_2])

For more details on the API, please see load_regions_from_file() and load_regions() methods in Imviz.