API Reference

SpectroCube

Calibrated spectral dataset.

The intensity array can have any number of labeled dimensions, but "wavelength" must always be one of them. Common shapes:

(wavelength,)                        — single spectrum
(frame, wavelength)                  — time series / shot sequence
(chord, time, wavelength)            — multi-chord time-resolved

Use the class-method constructors rather than instantiating directly:

SpectroCube.from_arrays(wavelength, intensity, ...)
SpectroCube.from_dataset(ds)
SpectroCube.load(path)

The underlying xarray Dataset is always available as .ds.

wavelength property

intensity property

dims property

Ordered dimension names of the intensity array.

sizes property

Mapping of every dimension name to its size.

calibration_type property

from_arrays(wavelength, intensity, instrument_id, calibration_type, intensity_units, wavelength_medium='air', dims=None, coords=None, **attrs) classmethod

Construct a SpectroCube from numpy arrays.

Parameters:

Name	Type	Description	Default
wavelength	(array - like, shape(n_wavelengths))	Wavelength axis in nm.	required
intensity	array - like	Spectral intensity. Dimension inference rules: 1D → dims forced to ("wavelength",) 2D → dims inferred as ("frame", "wavelength") when dims is not supplied 3D or higher → dims must be provided explicitly	required
instrument_id	str	Short identifier for the instrument.	required
calibration_type	str	One of "counts", "relative", "absolute".	required
intensity_units	str	Physical units string, e.g. "counts", "a.u.", "ph/s/nm/sr".	required
wavelength_medium	str	"air" or "vacuum". Default: "air".	'air'
dims	tuple of str	Dimension names for intensity. Must include "wavelength".	None
coords	dict mapping dim-name → array-like	Coordinate arrays for non-wavelength dimensions. Dimensions not listed here receive auto-generated integer ranges.	None
**attrs	object	Additional metadata stored in ds.attrs, e.g. exposure_s=0.5, spectrometer="Echelle ESA-3".	{}

from_dataset(ds) classmethod

Wrap an existing xarray Dataset as a SpectroCube.

The caller is responsible for ensuring the Dataset has the expected structure (intensity data variable, wavelength coordinate, required global attributes). Use validate() to check.

load(path) classmethod

Load a SpectroCube from a NetCDF file.

Data is loaded eagerly so the file handle is released immediately.

save(path, validate=True)

Save to NetCDF (.nc).

Parameters:

Name	Type	Description	Default
path	str	Output file path. Should end in .nc.	required
validate	bool	If True, validate before saving. Prints a report on warnings; raises ValueError on errors.	True

validate()

Check the SpectroCube for required fields and consistency.

ValidationReport

ok property