Importing Data#

Learn how to import data into Jdaviz from various sources and in different formats.

Overview#

Jdaviz provides flexible data loading through a combination of sources and formats:

  • Sources define where your data comes from (file, URL, Python object, etc.)

  • Formats define how your data should be interpreted (1D spectrum, image, cube, etc.)

Using load()#

The recommended way to load data is to use the _load() method on the configuration helper, whether that’s the deconfigged mode as shown below, or a specific configuration such as Specviz, Cubeviz, etc. This provides a simple interface for loading data:

import jdaviz
jdaviz.show()
jdaviz.load('myspectrum.fits', format='1D Spectrum')

# Alternatively
from jdaviz import Specviz
specviz = Specviz()
specviz.show()
specviz.load('myspectrum.fits')

Using Loaders API (Interactive)#

For more control over the loading process, you can use the Loaders API. This provides an interactive way to:

  • Select specific loaders

  • Configure import options

  • Inspect available options from dropdowns, etc.

  • View API hints for available options

  • Preview data before importing

The loaders are accessed through the loaders property on the helper:

# Access loaders
loaders = jdaviz.loaders

# Get list of available loaders
print(loaders)

# Use a specific loader
ldr = loaders['object']  # Or file, file drop, or url

# Configure loading options
ldr.object = my_data  # or ldr.filename, ldr.url
ldr.format = '1D Spectrum'

# Import the data
ldr.load()

The loaders interface provides access to parameters and options that control how the data is loaded and processed.

Available Loaders#

Available formats#

Using API Hints#

Jdaviz provides an API hints feature that helps you discover available attributes and parameters for loaders. You can enable API hints:

jdaviz.toggle_api_hints()

Or in the UI, click the API Hints button in the top right.

v0.1
Click toolbar icons to toggle different sidebars
Data Menu

Control data and subset layer order and visibility for each viewer. Toggle layer visibility, reorder layers by dragging, and manage which data appears in the viewer. 

dm = jd.viewers[viewer].data_menu

When API hints are enabled, you’ll see Python code snippets showing how to access and set various loader attributes. For example:

# When selecting a file loader, you might see:
ldr = jdaviz.loaders['file']
ldr.format = '1D Spectrum'  # Set the format
ldr.filename = 'myfile.fits'  # Set the filename

The hints update as you interact with the UI, showing you the exact Python code needed to reproduce your actions programmatically.

Differences from the Loaders API#

For most use cases, load() provides a simpler interface. Use the Loaders API when you need:

  • More control over loading options

  • Interactive configuration

  • Data preview before loading

  • Access to specialized loader features

Creating Jdaviz-readable Products#

Spectroscopic data products (1D, 2D, and 3D) can be loaded in the different jdaviz configurations using essentially two methods, i.e., loading Spectrum objects or from FITS files. Here, we list a few ways in which data can be packaged to be easily loaded into a jdaviz configuration.

Data in a database#

If the data are stored in a database, we recommend storing a Spectrum object per entry. This would allow the user to query the data and visualize it in jdaviz with few lines of code; also see Providing scripts to load the data as Spectrum objects.

Data in FITS files#

If the data are stored as FITS files, we propose three options:

Using an available specutils loader#

Available loaders can be listed with the following commands:

from specutils import Spectrum
Spectrum.read.list_formats()

The majority are fairly specific to missions and instruments. Four formats are more generic and adaptable: ASCII, ECSV, tabular-fits, and wcs1d-fits. More information on how to create files that are readable by these loaders can be found on the specutils GitHub repository.

Creating a dedicated loader#

The specutils documentation on how to create a custom loader is available. We are working on the necessary documentation to prompt jdaviz to recognize a custom loader developed in specutils.

Providing scripts to load the data as Spectrum objects#

If none of the above is an acceptable option, the user can create the data products with their custom format and provide scripts or Jupyter Notebooks that show how to read the products and create Spectrum objects that can be read into jdaviz.

Learn More#