HyperSpy: interactive analysis of multidimensional datasets

Data as an array of signals

HyperSpy is an open source Python library for the interactive analysis of multidimensional datasets that can be described as multidimensional arrays of a given signal, and the README gives the example that makes the model concrete, a 2D array of spectra, also known as a spectrum image. That framing is the whole design. A dataset is not a table with columns, it is a stack of things that each have the same internal structure, and the library then does two kinds of work with it. It makes it straightforward to apply analytical procedures that operate on an individual signal to multidimensional arrays, and it provides easy access to analytical tools that exploit the multidimensionality of the dataset. The project topics name the domains this comes from, with life sciences, materials science and physical sciences, plus data analysis, data visualisation and multi-dimensional. The homepage is hyperspy.org, the primary language is Python, and the licence is GPL v3.

The modular structure is the extension point

The README is explicit that the modular structure makes it easy to add features to analyse many different types of signals, and it points at the extension packages for instructions on installing the package and getting started. That is the argument for choosing HyperSpy over a general purpose array library. If your instrument produces data that is not spectra, then your interest is almost certainly in writing or using an extension that teaches the library how to read and interpret that signal type, and the library is designed around that being possible. The examples directory in the repository is a good picture of what that means in practice, with directories for Markers, create_signal, data_visualization, extensions, io, model_fitting, plotting, processing, region_of_interest and simple_simulations, and its own AGENTS.md, which suggests the examples are maintained with the same care as the library.

The dependency list explains the architecture

The project metadata in pyproject.toml is a reasonably honest map of how the library is built. The runtime dependencies include dask for arrays, with the comment on the jinja2 line explaining that it improves the representation of lazy signals by dask, which tells you the data model is lazy and dask backed rather than eagerly loaded into memory. numpy is there for the ContratEditorTool, matplotlib is the plotting layer, and the framework classifier in the metadata names Matplotlib. The scientific stack around it is scipy and sympy, the I/O layer is rosettasciio with the hdf5 and image extras, pint is the unit handling library, and traits is the configuration system, with natsort, tqdm, pyyaml, prettytable and cloudpickle filling in the rest. The Python classifiers cover 3.10 through 3.14, and the development status is marked as Beta. Since version 0.8.4 the library supports only Python 3, and the README says that if you need Python 2.7 you should install version 0.8.3, which is a small reminder of how long this project has been around.

Versioning from the git tag, with a twist

The setup.py in the repository is short and its whole job is the version number, and the mechanism is worth a paragraph because it explains how the release branches work. The build backend is setuptools with setuptools_scm at version 8 or newer, so the version comes from the git tag rather than from a number written in the file, and the whole setup call is a single line:

setup(use_scm_version={"version_scheme": custom_version_scheme})

The custom version scheme takes the tag, splits it, and keeps the number of parts the branch is supposed to retain, with the comment explaining that on RELEASE_next_major the retain value needs to be 1, on RELEASE_next_minor it needs to be 2, and on RELEASE_next_patch it needs to be 3. The last part is bumped, and missing parts are padded with zeros. So the branch you are on determines the next version number, which is how a project with a maintenance branch and a development branch produces the right sequence from one mechanism. The default branch here is RELEASE_next_minor, and the release history shows v2.5.0 on 2026-10-06, v2.4.0 in January 2026 and v2.3.0 in March 2025.

How the project is built and released

The repository is set up for a multi-channel release, and the configuration tells you what that means in practice. There is an azure-pipelines.yml at the top level with a build status badge, alongside a GitHub Actions workflow for tests, a Read the Docs configuration with a documentation status badge, and a Codecov badge for coverage. There are three separate conda environment files, conda_environment.yml for the runtime, conda_environment_dev.yml for development and conda_environment_doc.yml for building the documentation, which is the pattern of a project that supports pip, conda-forge and a documentation build as distinct environments. The release process has its own script, prepare_release.py, and a releasing_guide.md, and there is an upcoming_changes/ directory for the changelog fragments, plus a CHANGES.rst for the accumulated history. The package is published both to PyPI and to conda-forge, with a Zenodo DOI badge for citation, which is the convention for a research tool that people cite in papers.

Where this is the wrong choice

The limits are mostly about the data model. First, HyperSpy is for arrays of signals, so a project whose data is a flat table or an irregular collection will find the model awkward, and a plain dataframe library is a better fit. Second, the dependencies declare version floors, with numpy at 1.25 or newer, scipy at 1.10 or newer and matplotlib at 3.6 or newer, and the package still declares a development status of Beta, so you should check your environment against those minimums before upgrading. Third, the interactive analysis story rests on matplotlib and on the Jupyter style workflow, so if you want a server side pipeline with no interactive layer, much of the value is not there. Fourth, the extension mechanism, which is the main reason to adopt it, is also the main source of fragility, because extensions are separate packages maintained outside the core and they track the core's API. And fifth, the licence is GPL v3, which for a research tool used internally is rarely a problem, and for a research tool embedded in a commercial product is a conversation you should have before you start.

Editorial conclusion

HyperSpy fits a microscopy or spectroscopy user whose data is a stack of signals and who wants signal level processing, plotting and interactive exploration in one tool rather than a bespoke script per instrument. It is the wrong choice if your data is a plain table with no signal dimension, because the whole model is built around arrays of signals, and a poor fit if your environment cannot meet the declared dependency floors, such as numpy 1.25, scipy 1.10 and matplotlib 3.6. Before you install, read the extension package documentation, because adding support for a new instrument type is the usual reason to adopt it, and check the Python version you have against the supported 3.10 to 3.14 range. The last push was on 2026-10-06 with v2.5.0 released the same day, and the code is GPL-3.0 licensed.

Frequently asked questions

Official sources

1. hyperspy/hyperspy on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases