Machine learning for multivariate data through the Riemannian geometry of positive definite matrices in Python
Machine learning for multivariate data through the Riemannian geometry of positive definite matrices in Python
pyRiemann is a Python machine learning package based on scikit-learn API. It provides a high-level interface for processing and classification of real (resp. complex)-valued multivariate data through the Riemannian geometry of symmetric (resp. Hermitian) positive definite (SPD) (resp. HPD) matrices.
The documentation is available on http://pyriemann.readthedocs.io/en/latest/
This code is BSD-licensed (3 clause).
pyRiemann aims at being a generic package for multivariate data analysis but has been designed around biosignals (like EEG, MEG or EMG) manipulation applied to brain-computer interface (BCI), estimating covariance matrices from multichannel time series, and classifying them using the Riemannian geometry of SPD matrices [1].
For BCI applications, studied paradigms are motor imagery [2] [3], event-related potentials (ERP) [4] and steady-state visually evoked potentials (SSVEP) [5]. Using extended labels, API allows multisource transfer learning between sessions or subjects [6].
Another application is remote sensing, estimating covariance matrices over spatial coordinates of radar images using a sliding window, and processing them using the Riemannian geometry of SPD matrices for hyperspectral images, or HPD matrices for synthetic-aperture radar (SAR) images.
pyRiemann's core utility functions support both NumPy and PyTorch backends transparently through the Python Array API, enabling optional GPU acceleration and autograd when PyTorch tensors are passed in directly.
pip install pyriemannor using pip+git for the latest version of the code:
pip install git+https://github.com/pyRiemann/pyRiemannThe package is distributed via conda-forge. You could install it in your working environment, with the following command:
conda install -c conda-forge pyriemannFor the latest version, you can install the package from the sources using pip:
pip install .or in editable mode to be able to modify the sources:
pip install -e .Most of the functions mimic the scikit-learn API, and therefore can be directly used with sklearn. For example, for cross-validation classification of EEG signal using the MDM algorithm described in [2], it is easy as:
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())
You can also pipeline methods using sklearn pipeline framework. For example, to classify EEG signal using a SVM classifier in the tangent space, described in [3]:
from pyriemann.estimation import Covariances
from pyriemann.tangentspace import TangentSpace
from sklearn.pipeline import make_pipeline
from sklearn.model_selection import cross_val_score
from sklearn.svm import SVC
# load your data
X = ... # EEG data, in format n_epochs x n_channels x n_times
y = ... # labels
# build your pipeline
clf = make_pipeline(
Covariances(),
TangentSpace(),
SVC(kernel="linear"),
)
# cross validation
accuracy = cross_val_score(clf, X, y)
print(accuracy.mean())
Check out the example folder for more examples.
The package aims at adopting the scikit-learn and MNE-Python conventions as much as possible. See their contribution guidelines before contributing to the repository.
If you make a modification, run the test suite before submitting a pull request
pytest…[1] M. Congedo, A. Barachant and R. Bhatia, "Riemannian geometry for EEG-based brain-computer interfaces; a primer and a review". Brain-Computer Interfaces, 4.3, pp. 155-174, 2017. link
[2] A. Barachant, S. Bonnet, M. Congedo and C. Jutten, "Multiclass Brain-Computer Interface Classification by Riemannian Geometry". IEEE Transactions on Biomedical Engineering, vol. 59, no. 4, pp. 920-928, 2012. link
[3] A. Barachant, S. Bonnet, M. Congedo and C. Jutten, "Classification of covariance matrices using a Riemannian-based kernel for BCI applications". Neurocomputing, 112, pp. 172-178, 2013. link
[4] A. Barachant and M. Congedo, "A Plug&Play P300 BCI Using Information Geometry". Research report, 2014. link
[5] EK. Kalunga, S. Chevallier, Q. Barthélemy, K. Djouani, E. Monacelli and Y. Hamam, "Online SSVEP-based BCI using Riemannian geometry". Neurocomputing, 191, pp. 55-68, 2014. link
[6] PLC. Rodrigues, C. Jutten and M. Congedo, "Riemannian Procrustes analysis: transfer learning for brain-computer interfaces". IEEE Transactions on Biomedical Engineering, vol. 66, no. 8, pp. 2390-2401, 2018. link
No open issues yet, or sync has not completed.