3D Spectral Extraction#

Plugin Availability

This plugin works with 3D spectral cubes.

The plugin will be visible when at least one 3D spectral cube dataset is loaded.

Extract 1D spectra from 3D spectral cubes.

Description#

The 3D Spectral Extraction plugin collapses the spatial dimensions of a spectral cube to produce a 1D spectrum. This is useful for extracting integrated spectra over spatial regions or collapsing entire cubes.

Key Features:

  • Extract 1D spectra from cubes

  • Multiple extraction functions (Sum, Mean, Min, Max)

  • Spatial region (aperture) support

  • Wavelength-dependent apertures (cone extraction)

  • Uncertainty propagation

  • Background spectrum extraction

Details#

Extraction Functions#

The plugin supports several collapse operations:

  • Sum: Total flux across spatial region (most common)

  • Mean: Average flux per pixel

  • Min: Minimum flux value

  • Max: Maximum flux value

Sum is typically used for total flux, while Mean gives flux per unit area.

Spatial Regions (Apertures)#

You can extract spectra from:

  • Entire cube: All spatial pixels (no aperture)

  • Spatial subset: Defined region of interest

Apertures can be circular, elliptical, rectangular, or any drawn subset.

Wavelength-Dependent Apertures#

For circular subsets with spatial axes in angular units, you can enable wavelength-dependent apertures to create a cone that scales with wavelength:

$text{radius}(lambda) = text{radius}_0 times (lambda / lambda_0)$

where $lambda_0$ is the reference wavelength (current slice by default). This is useful for matching PSF size variations with wavelength.

Aperture Masking Methods#

The plugin supports different aperture masking methods (see photutils aperture documentation):

  • Center: Use only pixels whose centers fall within the aperture

  • Exact: Calculate exact overlap between aperture and pixels (slower)

  • Subpixel: Subdivide pixels for approximate overlap calculation

Exact method provides most accurate results but is computationally expensive. For most cases, center or subpixel methods are sufficient.

Note: Exact masking with Min/Max functions is not supported.

Uncertainty Propagation#

When uncertainty data is available in the cube, uncertainties are automatically propagated to the extracted 1D spectrum following standard error propagation rules. For spatial sum, uncertainties add in quadrature. For mean, uncertainties are scaled appropriately.

Background Extraction#

An optional background spectrum can be extracted from a separate spatial region and scaled relative to the source aperture area. This is useful for background subtraction in subsequent analysis.

UI Access#

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

Opening the Plugin#

Cubeviz:

Click the 3D Spectral Extraction icon in the plugin toolbar.

Workflow#

  1. Load cube into Cubeviz

  2. (Optional) Draw spatial region for aperture

  3. Select dataset from Data dropdown

  4. Select function from Function dropdown

  5. Select aperture from Aperture dropdown (or use Entire Cube)

  6. (Optional) For circular apertures:

    • Enable Wavelength dependent if desired

    • Click Adopt Current Slice to set reference wavelength

  7. Select aperture masking method from Aperture masking method dropdown

  8. Set output options:

    • Output data label

    • Viewer to add spectrum to

  9. Click Extract to create 1D spectrum

Background Extraction#

To extract a background spectrum:

  1. Define a background region (separate subset)

  2. Select background region from Background dropdown

  3. Click Extract Background button

The background spectrum is scaled by the aperture area ratio and can be subtracted from the source spectrum.

Results#

The extracted spectrum is:

  • Added to the spectrum viewer

  • Available in the data dropdown menus

  • Can be analyzed with spectroscopic plugins (line analysis, model fitting, etc.)

API Access#

Accessing the Plugin#

from jdaviz import Cubeviz

cubeviz = Cubeviz()
cubeviz.show()
cubeviz.load('cube.fits', format='3D Spectrum')

# Access plugin
plg = cubeviz.plugins['3D Spectral Extraction']

Basic Extraction#

# Extract from entire cube
plg.dataset = 'cube[FLUX]'
plg.function = 'Sum'

spectrum = plg.extract(add_data=True)

Aperture Extraction#

# Extract from spatial subset
plg.aperture = 'Subset 1'
plg.function = 'Sum'

spectrum = plg.extract(add_data=True)

Wavelength-Dependent Aperture#

# Enable cone extraction
plg.aperture = 'Subset 1'  # Must be circular
plg.wavelength_dependent = True
plg.reference_wavelength = 5000  # Angstroms

spectrum = plg.extract(add_data=True)

Aperture Masking Method#

# Use exact masking for highest accuracy
plg.aperture_method = 'Exact'

spectrum = plg.extract(add_data=True)

Background Subtraction#

# Extract source spectrum
plg.aperture = 'Subset 1'
source_spec = plg.extract(add_data=True)

# Extract background spectrum
plg.background = 'Subset 2'
bg_spec = plg.extract_bg_spectrum(add_data=True)

# Background is auto-scaled by aperture area ratio
# Subtract in subsequent analysis

Custom Output#

# Control output
extraction.add_results.label = 'source_spectrum'
extraction.add_results.viewer = 'spectrum-viewer'

# Or get without adding
spectrum = extraction.extract(add_data=False)

# Access data
wavelength = spectrum.spectral_axis
flux = spectrum.flux
uncertainty = spectrum.uncertainty

Batch Extraction#

# Extract from multiple apertures
apertures = ['Subset 1', 'Subset 2', 'Subset 3']

for i, ap in enumerate(apertures, 1):
    plg.aperture = ap
    plg.add_results.label = f'spectrum_{i}'
    plg.extract(add_data=True)

API References#

See the 3D Spectral Extraction Plugin Documentation

for more details.

Only the following attributes and methods are available through the public plugin API:

  • show()

  • open_in_tray()

  • close_in_tray()

  • show_live_preview Whether to show a live preview of the extracted spectrum.

  • dataset (DatasetSelect) Dataset to use for spectral extraction.

  • aperture (ApertureSubsetSelect): Subset to use for the spectral extraction, or Entire Cube.

  • wavelength_dependent: Whether the aperture should be considered wavelength-dependent. The cone is defined to intersect aperture at reference_spectral_value.

  • reference_spectral_value: The wavelength that will be used to calculate the radius of the cone through the cube.

  • background (ApertureSubsetSelect): Subset to use for background subtraction, or None.

  • bg_wavelength_dependent: Whether the background aperture should be considered wavelength-dependent (requires wavelength_dependent to also be set to True). The cone is defined to intersect background at reference_spectral_value.

  • `bg_spec_per_spaxel:

    Whether to normalize the background per spaxel when calling extract_bg_spectrum. Otherwise, the spectrum will be scaled by the ratio between the areas of the aperture and the background aperture. Only applicable if function is ‘Sum’.

  • bg_spec_add_results (AddResults)

  • extract_bg_spectrum()

  • aperture_method (SelectPluginComponent): Method to use for extracting spectrum (and background, if applicable).

  • add_results (AddResults)

  • extract()

For detailed API documentation, see SpectralExtraction3D.

Example Notebooks#

See Also#