HyperSpy

Common errors

• ModuleNotFoundError: No module named 'hyperspy.eds'

  cause Specific signal classes and functionalities for domains like EDS (Energy-Dispersive X-ray Spectrometry) were moved out of the core `hyperspy` library in version 2.0.
  fix Install the relevant HyperSpy extension package, e.g., `pip install hyperspy-eds`. Check the HyperSpy documentation for a list of available extensions.

• AttributeError: 'BaseSignal' object has no attribute 'gui'

  cause The GUI components for HyperSpy were split into separate packages (`hyperspy-gui-ipywidgets`, `hyperspy-gui-traitsui`) since version 1.3 and are no longer installed by default.
  fix Install the desired GUI package, e.g., `pip install hyperspy-gui-ipywidgets`, then restart your Python environment. Ensure you have the necessary GUI backend installed (e.g., `ipywidgets` for Jupyter Notebooks).

• TypeError: 'AxesManager' object is not subscriptable

  cause Direct indexing of Signal objects (e.g., `s[0, 0]`) was deprecated in older versions in favor of `s.isig` and `s.inav` for explicit signal and navigation axis indexing. While some direct indexing might still work for specific cases, misusing it can lead to this error.
  fix Use the explicit indexing methods: `s.isig[...]` for signal dimensions and `s.inav[...]` for navigation dimensions to avoid ambiguity and ensure correct slicing and access.

• MemoryError: Unable to allocate array with shape (..., ...) and data type float64

  cause This often occurs when working with very large datasets, especially when performing memory-intensive operations like calculating errors during model fitting, which by default requires large memory.
  fix For fitting, pass `calculate_errors=False` to `multifit()` if errors are not immediately needed, or consider using a nonlinear optimizer in a second pass once parameters are optimized. When possible, use lazy loading or Dask arrays for out-of-core processing of large datasets, which HyperSpy supports implicitly through its `BaseSignal` abstraction. Consider increasing available RAM or processing data in smaller chunks.

Warnings

• breaking Breaking changes in HyperSpy 2.0+: The library was split into a core package and `RosettaSciIO` for I/O operations. Many domain-specific signal classes (e.g., EELS, EDS, Holography) were moved out of the core library into specialized HyperSpy extensions. Direct imports or functionality relying on these classes within the main `hyperspy` package will fail.
  Fix: For I/O, ensure `RosettaSciIO` is installed (it's a dependency of `hyperspy`). For domain-specific signals, install the relevant HyperSpy extension package (e.g., `hyperspy-eels`, `hyperspy-eds`). Check the official documentation for specific migration paths.
• breaking Python 2 support was dropped with HyperSpy 0.8.4. All versions since require Python 3.
  Fix: Ensure your environment uses Python 3.10 or newer (as per current PyPI requirements). If you must use Python 2, install HyperSpy 0.8.3 or earlier.
• deprecated GUI elements based on `traitsui` and `ipywidgets` are no longer included in the core HyperSpy package by default since version 1.3. These functionalities are now provided by separate packages, `hyperspy-gui-ipywidgets` and `hyperspy-gui-traitsui`.
  Fix: If you rely on interactive GUI elements, explicitly install the necessary GUI package: `pip install hyperspy-gui-ipywidgets` or `pip install hyperspy-gui-traitsui` (or `conda install` equivalent).
• deprecated The direct `hspy` API (e.g., `import hspy`) was deprecated in favor of `hyperspy.api` in version 0.8.4. While older versions might still tolerate it, it's considered an outdated pattern.
  Fix: Always use `import hyperspy.api as hs` for importing HyperSpy functionalities.
• gotcha HyperSpy distinguishes between 'navigation' and 'signal' dimensions for multidimensional arrays. Most functions operate on signal axes and iterate on navigation axes. This is a core concept that can be confusing if not understood.
  Fix: Familiarize yourself with HyperSpy's axis management (e.g., `s.axes_manager`, `s.metadata.axes`). Understand that `s.data` is the underlying NumPy array, but HyperSpy's methods operate on the `Signal` object which handles these distinctions automatically.

Install

• pip install hyperspy PyPI (recommended)
• conda install hyperspy -c conda-forge Anaconda/Conda

Imports

• hs

  import hyperspy.api as hs

  The recommended way to import HyperSpy, making all public packages, functions, and classes available via the 'hs' alias.
• Signal1D, Signal2D, BaseSignal

  from hyperspy.signals import Signal1D

  Directly importing specific Signal classes for creating signals from NumPy arrays when not using `hs.load`.

Quickstart

This quickstart demonstrates how to import HyperSpy, load an example dataset, and plot it. It also includes commented-out code to illustrate how to create a signal directly from a NumPy array and set its axes properties, which is useful for custom data.

import hyperspy.api as hs
import numpy as np

# Load example data (e.g., an EDS spectrum image)
s = hs.datasets.example_signals.EDS_TEM_Spectrum()

# Or create a signal from a numpy array
# data = np.random.rand(10, 10, 1024) # e.g., 10x10 image of 1024-channel spectra
# s_from_array = hs.signals.Signal1D(data)
# s_from_array.set_axes(axis=0, name='X', units='nm')
# s_from_array.set_axes(axis=1, name='Y', units='nm')
# s_from_array.set_signal_axis(0, name='Energy', units='eV')

print(s)
s.plot()