PyRiemann: the object of classification is a covariance matrix
Machine learning for multivariate data through the Riemannian geometry of positive definite matrices in Python
At a glance
- What is it?
- A scikit-learn shaped Python package that estimates covariance matrices from multichannel time series and classifies them with the geometry of positive definite matrices. Built for EEG and BCI, extended to radar imagery, and readable end to end from the README.
- Who is it for?
- PyRiemann fits signal researchers who already have trials of multichannel data and want a classification stage that respects the geometry of covariance matrices instead of flattening them. Skip it if your features are already vectors, since the whole package assumes a covariance step first.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 11 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- pyRiemann/pyRiemann786 ★ · +11
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| pyRiemann/pyRiemann | 775 | 786 |
11 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The API is scikit-learn's, so pipelines come for free
The design decision is that nothing in the package looks unusual to somebody who has used scikit-learn. Most functions mimic that API, which means cross-validation, pipelines and estimators work without adapters. The shortest complete example is this:
import pyriemann
from sklearn.model_selection import cross_val_score
# load your data
X = ... # EEG data, in format n_epochs x n_channels x n_times
y = ... # labels
# estimate covariance matrices
cov = pyriemann.estimation.Covariances().fit_transform(X)
# build your classifier
mdm = pyriemann.classification.MDM()
# cross validation
accuracy = cross_val_score(mdm, cov, y)
print(accuracy.mean())Read the middle two lines carefully, because they are the whole idea. The input is not the signal, it is one covariance matrix per epoch, computed by a `Covariances` estimator. The classifier then receives that array of matrices, and cross-validation runs on the matrices rather than on the raw trials.
The second example shows the other half of the package: composing the covariance estimation with a tangent space projection and an SVM into a single `make_pipeline`, so that `cross_val_score` can take raw trials and do the estimation inside each fold. Getting that ordering right inside cross-validation is exactly the kind of leak the pipeline API exists to prevent.
Covariances are what gets classified, not the signal
The package processes real-valued or complex-valued multivariate data through the Riemannian geometry of symmetric, or for complex data Hermitian, positive definite matrices. That is the technical core, and the practical consequence is that every method here takes a matrix and returns a matrix.
The domain it was designed around is biosignal work. That means EEG, MEG and EMG manipulation, applied to brain-computer interfaces, with covariance matrices estimated from multichannel time series and then classified with the Riemannian geometry of SPD matrices. The paradigms the documentation names are motor imagery, event-related potentials and steady-state visually evoked potentials, each with its own paper cited in the references.
The reason this is not just a shape convenience is worth stating plainly. Two covariance matrices that differ only by a linear transform are, in the Riemannian setting, closer than their raw entries suggest, and the distance used for classification is the geodesic one rather than a flat entrywise distance. A classifier trained in that space sees trials that a flattened representation would treat as unrelated, which is why the same estimator names appear throughout the package.
For complex-valued data the object is a Hermitian positive definite matrix instead, and the same code paths handle both, which is what lets remote sensing share the machinery.
Extended labels turn classification into cross-session transfer
Beyond single-session classification there is a transfer story, and it uses labels rather than a separate model class. With extended labels the API supports multisource transfer learning between sessions or subjects, meaning data recorded on different days or from different people can be pooled.
The method behind it is Riemannian Procrustes analysis, cited as reference six in the documentation. The mechanism is what makes this practical for brain signals: session and subject effects in EEG show up as a consistent geometric transformation of the covariance matrices, so aligning sessions in the Riemannian space before classifying removes a nuisance factor that would otherwise be baked into the model.
The practical reading is that a pipeline built for one session does not silently transfer to another. Estimating covariance per trial handles within-trial structure; extended labels are what let the classifier see which session each trial came from and align accordingly. BCI work is exactly the setting where this matters, because the same subject on a different day produces noticeably different covariance geometry.
The examples tree carries a `transfer/` directory, so this is exercised in the repository rather than only described.
NumPy and PyTorch both work through the Array API
The core utility functions support both the NumPy and the PyTorch backends transparently, through the Python Array API standard. The stated payoff is optional GPU acceleration and autograd, available when PyTorch tensors are passed in directly rather than converted.
That is implemented through two small compatibility packages in the dependency list, `array-api-compat>=1.14` and `array-api-extra>=0.6`, which sit alongside NumPy, SciPy, scikit-learn, joblib and matplotlib. The design intent is that a researcher does not rewrite an analysis to move it onto a GPU, and that a differentiability path exists for anyone who wants gradients through the covariance and projection steps.
The version floors are worth reading before you pin anything. NumPy has to be 1.25 or newer and Python has to be 3.11 or newer, with the project badge advertising 3.11, 3.12 and 3.13. But scikit-learn is pinned only at 0.24, a floor from years ago, while the optional documentation extra pulls in MNE, seaborn, pandas and IPython alongside Sphinx and its gallery extensions. So the runtime requirements are current and the library floor is deliberately permissive.
Contributors are asked to follow scikit-learn and MNE-Python conventions as closely as possible, and to run `pytest` before opening a pull request.
Four install routes, and the version is parsed out of a Python file
Installation is offered four ways, and they differ in what they actually give you.
pip install pyriemannThat is the release. For the current code the documented alternative is pip straight from git, `pip install git+https://github.com/pyRiemann/pyRiemann`, and conda-forge carries the package too, installed with `conda install -c conda-forge pyriemann`. From a checkout you get either `pip install .` or, if you intend to modify the sources, `pip install -e .` in editable mode.
The packaging is worth one look because it is old-fashioned in a way that is still functional. The version is not declared in `setup.py`. Instead the file opens `pyriemann/_version.py`, scans its lines for one starting with `__version__`, and splits the value out by hand, raising a RuntimeError with the message that it could not determine the version if the pattern is not found. A refactor that renames that variable therefore breaks the build rather than producing a bad version number.
Alongside `setup.py` there is a `setup.cfg`, a `requirements.txt` that restates the same runtime dependencies, a `MANIFEST.in`, a `CITATION.cff`, a `.coveragerc` and a pre-commit configuration. Three places listing the same dependencies is duplication, but it also means the dependency set is easy to audit by eye.
Examples cover radar imagery as well as brain signals
The second application area is remote sensing, and it is the reason the package handles Hermitian matrices at all. Covariance matrices are estimated over the spatial coordinates of radar images with a sliding window, then processed with the same geometry. For hyperspectral imagery the objects are SPD matrices; for synthetic-aperture radar imagery they are HPD matrices.
The examples tree shows how broad the surface has become: `biosignal-erp/`, `biosignal-mi/` and `biosignal-ssvep/` for the three BCI paradigms, `covariance-estimation/` for the estimators themselves, `fnirs/` for functional near-infrared spectroscopy, `image-radar/` for the remote sensing path, `nlp/` for text, `stats/`, `simulated/`, `transfer/`, `data/` and an `artifacts/` directory. There is also an `examples/README.txt` as the entry point.
That range tells you something about the library's character. The stated goal is to be a generic package for multivariate data analysis, but the design was built around biosignals, and the extras accreted around that core: radar imaging because the same covariance-over-a-window idea transfers, text because the array utilities are language agnostic, transfer because sessions are the normal unit of BCI data.
Documentation is built with Sphinx and the gallery, with a readthedocs configuration at the root, and the package cites a 2017 primer and review on Riemannian geometry for BCI as the entry point for the theory.
Quarterly releases on master, and the theory is cited in full
Maintenance is regular and easy to follow. Releases come at roughly a quarterly rhythm: v0.10 on 2026-01-06, v0.11 on 2026-04-16 and v0.12 on 2026-07-01, with the last push to the repository on 2026-10-01. The default branch is `master` rather than `main`, which is worth knowing if you script anything against it.
Version numbering is still in the 0.x line, so there is no compatibility promise yet even though the project is old enough to have a Zenodo DOI, a CITATION.cff file and a pepy badge. The citation itself is a BibTeX software entry listing fourteen authors, and the reference list behind it names the specific papers the methods come from: the 2012 multiclass BCI classification paper for the MDM classifier, the 2013 Riemannian kernel paper for the SVM variant, a 2014 P300 report, a 2014 SSVEP paper, the 2017 primer and review, and the Riemannian Procrustes paper for transfer.
Coverage is tracked, with a codecov badge and a `.coveragerc` at the root. The package is BSD 3-clause, the docs are hosted at pyriemann.readthedocs.io, and the project has been built by people including Alexandre Barachant, Quentin Barthélemy, Jean-Rémi King, Alexandre Gramfort and Sylvain Chevallier among others, which is a reasonable guide to who the code is written for.
Editorial conclusion
PyRiemann fits signal researchers who already have trials of multichannel data and want a classification stage that respects the geometry of covariance matrices instead of flattening them. Skip it if your features are already vectors, since the whole package assumes a covariance step first. Before you build on it, check which estimator your paradigm needs against the per-language support that does not apply here, note that the scikit-learn floor is still 0.24 while Python must be 3.11 or newer, and pin a release rather than tracking the master branch.
Frequently asked questions
What does pyRiemann do with EEG data?
It estimates one covariance matrix per epoch from multichannel time series and classifies those matrices with the Riemannian geometry of SPD matrices. The paradigms covered are motor imagery, event-related potentials and steady-state visually evoked potentials.
Can pyRiemann transfer a model between sessions or subjects?
Yes. Extended labels let the API do multisource transfer learning between sessions or subjects, using Riemannian Procrustes analysis to align the covariance geometry before classification.
Does pyRiemann work with PyTorch and a GPU?
The core utilities support NumPy and PyTorch backends transparently through the Python Array API, so GPU acceleration and autograd are available when PyTorch tensors are passed in directly.
How do I install pyRiemann?
With pip install pyriemann for a release, pip straight from the git URL for current code, conda install -c conda-forge pyriemann, or pip install . and pip install -e . from a checkout. Python 3.11 or newer is required.
What does pyRiemann do outside brain signals?
Remote sensing. It estimates covariance matrices over the spatial coordinates of radar images with a sliding window, using SPD matrices for hyperspectral imagery and HPD matrices for synthetic-aperture radar imagery.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/pyriemann-pyriemann)Star history chart for your README
[](https://hysenlabs.com/projects/pyriemann-pyriemann)Was this useful?