specutils

2.3.0 verified Fri May 01 auth: no python

A Python package for spectroscopic astronomical data analysis, part of the Astropy ecosystem. Version 2.3.0 supports Python >=3.11. It provides classes for representing spectra (Spectrum1D, SpectrumList), spectral regions, and operations like resampling, fitting, and combining spectra. Release cadence is irregular with major version bumps about every 2 years.

pip install specutils

Common errors

error AttributeError: module 'specutils' has no attribute 'Spectrum1D' ↓

cause Outdated specutils version (<1.20) where Spectrum1D was not yet exposed at top level.

fix

Upgrade specutils to >=1.20: pip install --upgrade specutils

error ValueError: The spectral axis must be monotonically increasing. ↓

cause Spectral axis values are not sorted in ascending order.

fix

Ensure spectral_axis is sorted: spec = Spectrum1D(spectral_axis=np.sort(spectral_axis), flux=flux)

error ImportError: No module named 'gwcs' ↓

cause Missing optional dependency for GWCS support.

fix

Install gwcs: pip install gwcs

Warnings

breaking In specutils 2.x, the class previously known as Spectrum1D is now Spectrum and Spectrum1D is an alias. Code relying on Spectrum1D subclassing may break if using isinstance checks against old class hierarchy. ↓

fix Use 'from specutils import Spectrum' for new code, or continue using Spectrum1D as an alias.

breaking Support for Python 3.10 dropped in specutils 2.2.0. Python 3.11 or later is required. ↓

fix Upgrade to Python >=3.11.

deprecated The 'spectral_axis_index' keyword argument introduced in 2.0 is deprecated in favor of automatic detection. Using it may emit deprecation warnings. ↓

fix Remove spectral_axis_index and rely on automatic axis ordering.

gotcha When passing a SpectralRegion to extract_region, if the units of the region do not match the spectrum's spectral axis units, an error may not be raised immediately but results can be incorrect. Always ensure consistent units. ↓

fix Use equivalencies if needed, e.g., via astropy.units.equivalencies.spectral().

Imports

Spectrum1D

wrong

from specutils import Spectrum1D as Spectrum1D

correct

from specutils import Spectrum1D

No common mistake; classic import is correct.

SpectralRegion
wrong
```
import SpectralRegion
```
correct
```
from specutils import SpectralRegion
```
SpectralRegion is a class in specutils, not a top-level module.

Quickstart

Basic usage: create a Spectrum1D and extract a spectral region.

import numpy as np
from specutils import Spectrum1D, SpectralRegion
from specutils.manipulation import extract_region
from astropy import units as u

# Create a simple spectrum
flux = np.array([1.0, 2.0, 3.0]) * u.Jy
spectral_axis = np.array([5000, 5010, 5020]) * u.Angstrom
spec = Spectrum1D(spectral_axis=spectral_axis, flux=flux)

# Extract a region
region = SpectralRegion(5005 * u.Angstrom, 5015 * u.Angstrom)
extracted = extract_region(spec, region)
print(extracted)