{"id":9042,"library":"hyperspy","title":"HyperSpy","description":"HyperSpy is an open-source Python library, currently at version 2.4.0, providing a comprehensive framework for the interactive analysis of multidimensional datasets, particularly within scientific domains like electron microscopy. It offers tools for efficient exploration, manipulation, and visualization of complex data arrays, including those larger than available memory. The project maintains an active development pace with several minor releases annually, and significant architectural changes in major versions like 2.0.","status":"active","version":"2.4.0","language":"en","source_language":"en","source_url":"https://github.com/hyperspy/hyperspy","tags":["scientific computing","data analysis","microscopy","spectroscopy","signal processing","materials science","electron microscopy"],"install":[{"cmd":"pip install hyperspy","lang":"bash","label":"PyPI (recommended)"},{"cmd":"conda install hyperspy -c conda-forge","lang":"bash","label":"Anaconda/Conda"}],"dependencies":[{"reason":"Recommended for full functionality, especially for HDF5-based file formats.","package":"h5py","optional":true},{"reason":"Recommended for advanced image processing functionalities, such as subpixel alignment and peak finding. Also for blockfile support via RosettaSciIO.","package":"scikit-image","optional":true},{"reason":"Recommended for machine learning features.","package":"scikit-learn","optional":true},{"reason":"Recommended for full functionality, likely related to metadata parsing.","package":"lxml","optional":true},{"reason":"Required for the lowess filter since version 0.7.2.","package":"statsmodels","optional":true},{"reason":"Provides Jupyter Notebook GUI elements; split from core HyperSpy in v1.3.","package":"hyperspy-gui-ipywidgets","optional":true},{"reason":"Provides TraitsUI-based GUI elements; split from core HyperSpy in v1.3.","package":"hyperspy-gui-traitsui","optional":true}],"imports":[{"note":"The recommended way to import HyperSpy, making all public packages, functions, and classes available via the 'hs' alias.","symbol":"hs","correct":"import hyperspy.api as hs"},{"note":"Directly importing specific Signal classes for creating signals from NumPy arrays when not using `hs.load`.","symbol":"Signal1D, Signal2D, BaseSignal","correct":"from hyperspy.signals import Signal1D"}],"quickstart":{"code":"import hyperspy.api as hs\nimport numpy as np\n\n# Load example data (e.g., an EDS spectrum image)\ns = hs.datasets.example_signals.EDS_TEM_Spectrum()\n\n# Or create a signal from a numpy array\n# data = np.random.rand(10, 10, 1024) # e.g., 10x10 image of 1024-channel spectra\n# s_from_array = hs.signals.Signal1D(data)\n# s_from_array.set_axes(axis=0, name='X', units='nm')\n# s_from_array.set_axes(axis=1, name='Y', units='nm')\n# s_from_array.set_signal_axis(0, name='Energy', units='eV')\n\nprint(s)\ns.plot()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Python 2 support was dropped with HyperSpy 0.8.4. All versions since require Python 3.","severity":"breaking","affected_versions":">=0.8.4"},{"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).","message":"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`.","severity":"deprecated","affected_versions":">=1.3.0"},{"fix":"Always use `import hyperspy.api as hs` for importing HyperSpy functionalities.","message":"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.","severity":"deprecated","affected_versions":">=0.8.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the relevant HyperSpy extension package, e.g., `pip install hyperspy-eds`. Check the HyperSpy documentation for a list of available extensions.","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.","error":"ModuleNotFoundError: No module named 'hyperspy.eds'"},{"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).","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.","error":"AttributeError: 'BaseSignal' object has no attribute 'gui'"},{"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.","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.","error":"TypeError: 'AxesManager' object is not subscriptable"},{"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.","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.","error":"MemoryError: Unable to allocate array with shape (..., ...) and data type float64"}]}