# pyRiemann
[](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11-blue)
[](https://badge.fury.io/py/pyriemann)
[](https://github.com/pyRiemann/pyRiemann/actions)
[](https://codecov.io/gh/pyRiemann/pyRiemann)
[](http://pyriemann.readthedocs.io/en/latest/?badge=latest)
[](https://doi.org/10.5281/zenodo.593816)
[](https://pepy.tech/project/pyriemann)
pyRiemann is a Python machine learning package based on [scikit-learn](http://scikit-learn.org/stable/modules/classes.html) 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](https://en.wikipedia.org/wiki/Definite_matrix) (SPD) (*resp*. HPD) matrices.
The documentation is available on http://pyriemann.readthedocs.io/en/latest/
This code is BSD-licensed (3 clause).
# Description
pyRiemann aims at being a generic package for multivariate data analysis
but has been designed around [biosignals](https://en.wikipedia.org/wiki/Biosignal) (like EEG, MEG or EMG)
manipulation applied to [brain-computer interface](https://en.wikipedia.org/wiki/Brain%E2%80%93computer_interface) (BCI),
estimating [covariance matrices](https://en.wikipedia.org/wiki/Covariance_matrix) from multichannel time series,
and classifying them using the Riemannian geometry of SPD matrices [[1]](#1).
For BCI applications, studied paradigms are motor imagery [[2]](#2) [[3]](#3),
event-related potentials (ERP) [[4]](#4) and steady-state visually evoked potentials (SSVEP) [[5]](#5).
Using extended labels, API allows transfer learning between sessions or subjects [[6]](#6).
Another application is [remote sensing](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/Hyperspectral_imaging) images,
or HPD matrices for [synthetic-aperture radar](https://en.wikipedia.org/wiki/Synthetic-aperture_radar) (SAR) images.
# Installation
#### Using PyPI
```
pip install pyriemann
```
or using pip+git for the latest version of the code:
```
pip install git+https://github.com/pyRiemann/pyRiemann
```
#### Using conda
The package is distributed via [conda-forge](https://conda-forge.org).
You could install it in your working environment, with the following command:
```shell
conda install -c conda-forge pyriemann
```
#### From sources
For the latest version, you can install the package from the sources using ``pip``:
```shell
pip install .
```
or in editable mode to be able to modify the sources:
```shell
pip install -e .
```
# How to use
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]](#2), it is easy as:
```python
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]](#3):
```python
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.
# Contribution Guidelines
The package aims at adopting the [scikit-learn](http://scikit-learn.org/stable/developers/contributing.html#contributing-code)
and [MNE-Python](https://mne.tools/stable/install/contributing.html) conventions as much as possible.
See their contribution guidelines before contributing to the repository.
# Testing
If you make a modification, run the test suite before submitting a pull request
```
pytest
```
# How to cite
```bibtex
@software{pyriemann,
author = {Alexandre Barachant and
Quentin Barthélemy and
Jean-Rémi King and
Alexandre Gramfort and
Sylvain Chevallier and
Pedro L. C. Rodrigues and
Emanuele Olivetti and
Vladislav Goncharenko and
Gabriel Wagner vom Berg and
Ghiles Reguig and
Arthur Lebeurrier and
Erik Bjäreholt and
Maria Sayu Yamamoto and
Pierre Clisson and
Marie-Constance Corsi and
Igor Carrara and
Apolline Mellot and
Bruna Junqueira Lopes and
Brent Gaisford and
Ammar Mian and
Anton Andreev and
Gregoire Cattan and
Arthur Lebeurrier},
title = {pyRiemann},
month = oct,
year = 2024,
version = {v0.7},
publisher = {Zenodo},
doi = {10.5281/zenodo.593816},
url = {https://doi.org/10.5281/zenodo.593816}
}
```
# References
<a id="1">[1]</a>
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](https://hal.science/hal-01570120/document)
<a id="2">[2]</a>
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](https://hal.archives-ouvertes.fr/hal-00681328)
<a id="3">[3]</a>
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](https://hal.archives-ouvertes.fr/hal-00820475/)
<a id="4">[4]</a>
A. Barachant and M. Congedo, "A Plug&Play P300 BCI Using Information Geometry".
Research report, 2014. [link](http://arxiv.org/abs/1409.0107)
<a id="5">[5]</a>
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](https://hal.science/hal-01351623/file/Kalunga-Chevallier-Barthelemy-Online%20SSVEP-based%20BCI%20using%20Riemannian%20Geometry-Neurocomputing-16.pdf)
<a id="6">[6]</a>
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](https://hal.archives-ouvertes.fr/hal-01971856)
Raw data
{
"_id": null,
"home_page": "https://pyriemann.readthedocs.io",
"name": "pyriemann",
"maintainer": null,
"docs_url": "https://pythonhosted.org/pyriemann/",
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Alexandre Barachant",
"author_email": "alexandre.barachant@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c4/50/e551da680538e4e2add83d77c3dd201fc216900b5bfa9b9f215cabdfef5f/pyriemann-0.7.tar.gz",
"platform": "any",
"description": "# pyRiemann\n\n[](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11-blue)\n[](https://badge.fury.io/py/pyriemann)\n[](https://github.com/pyRiemann/pyRiemann/actions)\n[](https://codecov.io/gh/pyRiemann/pyRiemann)\n[](http://pyriemann.readthedocs.io/en/latest/?badge=latest)\n[](https://doi.org/10.5281/zenodo.593816)\n[](https://pepy.tech/project/pyriemann)\n\npyRiemann is a Python machine learning package based on [scikit-learn](http://scikit-learn.org/stable/modules/classes.html) API.\nIt provides a high-level interface for processing and classification of real (*resp*. complex)-valued multivariate data\nthrough the Riemannian geometry of symmetric (*resp*. Hermitian)\n[positive definite](https://en.wikipedia.org/wiki/Definite_matrix) (SPD) (*resp*. HPD) matrices.\n\nThe documentation is available on http://pyriemann.readthedocs.io/en/latest/\n\nThis code is BSD-licensed (3 clause).\n\n# Description\n\npyRiemann aims at being a generic package for multivariate data analysis\nbut has been designed around [biosignals](https://en.wikipedia.org/wiki/Biosignal) (like EEG, MEG or EMG)\nmanipulation applied to [brain-computer interface](https://en.wikipedia.org/wiki/Brain%E2%80%93computer_interface) (BCI),\nestimating [covariance matrices](https://en.wikipedia.org/wiki/Covariance_matrix) from multichannel time series,\nand classifying them using the Riemannian geometry of SPD matrices [[1]](#1).\n\nFor BCI applications, studied paradigms are motor imagery [[2]](#2) [[3]](#3),\nevent-related potentials (ERP) [[4]](#4) and steady-state visually evoked potentials (SSVEP) [[5]](#5).\nUsing extended labels, API allows transfer learning between sessions or subjects [[6]](#6).\n\nAnother application is [remote sensing](https://en.wikipedia.org/wiki/Remote_sensing),\nestimating covariance matrices over spatial coordinates of radar images using a sliding window,\nand processing them using the Riemannian geometry of\nSPD matrices for [hyperspectral](https://en.wikipedia.org/wiki/Hyperspectral_imaging) images,\nor HPD matrices for [synthetic-aperture radar](https://en.wikipedia.org/wiki/Synthetic-aperture_radar) (SAR) images.\n\n# Installation\n\n#### Using PyPI\n\n```\npip install pyriemann\n```\nor using pip+git for the latest version of the code:\n\n```\npip install git+https://github.com/pyRiemann/pyRiemann\n```\n\n#### Using conda\n\nThe package is distributed via [conda-forge](https://conda-forge.org).\nYou could install it in your working environment, with the following command:\n\n```shell\nconda install -c conda-forge pyriemann\n```\n\n#### From sources\n\nFor the latest version, you can install the package from the sources using ``pip``:\n\n```shell\npip install .\n```\n\nor in editable mode to be able to modify the sources:\n\n```shell\npip install -e .\n```\n\n# How to use\n\nMost of the functions mimic the scikit-learn API, and therefore can be directly used with sklearn.\nFor example, for cross-validation classification of EEG signal using the MDM algorithm described in [[2]](#2), it is easy as:\n\n```python\nimport pyriemann\nfrom sklearn.model_selection import cross_val_score\n\n# load your data\nX = ... # EEG data, in format n_epochs x n_channels x n_times\ny = ... # labels\n\n# estimate covariance matrices\ncov = pyriemann.estimation.Covariances().fit_transform(X)\n\n# build your classifier\nmdm = pyriemann.classification.MDM()\n\n# cross validation\naccuracy = cross_val_score(mdm, cov, y)\n\nprint(accuracy.mean())\n\n```\n\nYou can also pipeline methods using sklearn pipeline framework.\nFor example, to classify EEG signal using a SVM classifier in the tangent space, described in [[3]](#3):\n\n```python\nfrom pyriemann.estimation import Covariances\nfrom pyriemann.tangentspace import TangentSpace\nfrom sklearn.pipeline import make_pipeline\nfrom sklearn.model_selection import cross_val_score\nfrom sklearn.svm import SVC\n\n# load your data\nX = ... # EEG data, in format n_epochs x n_channels x n_times\ny = ... # labels\n\n# build your pipeline\nclf = make_pipeline(\n Covariances(),\n TangentSpace(),\n SVC(kernel=\"linear\"),\n)\n\n# cross validation\naccuracy = cross_val_score(clf, X, y)\n\nprint(accuracy.mean())\n\n```\n\nCheck out the example folder for more examples.\n\n# Contribution Guidelines\n\nThe package aims at adopting the [scikit-learn](http://scikit-learn.org/stable/developers/contributing.html#contributing-code)\nand [MNE-Python](https://mne.tools/stable/install/contributing.html) conventions as much as possible.\nSee their contribution guidelines before contributing to the repository.\n\n# Testing\n\nIf you make a modification, run the test suite before submitting a pull request\n\n```\npytest\n```\n\n# How to cite\n\n```bibtex\n@software{pyriemann,\n author = {Alexandre Barachant and\n Quentin Barth\u00e9lemy and\n Jean-R\u00e9mi King and\n Alexandre Gramfort and\n Sylvain Chevallier and\n Pedro L. C. Rodrigues and\n Emanuele Olivetti and\n Vladislav Goncharenko and\n Gabriel Wagner vom Berg and\n Ghiles Reguig and\n Arthur Lebeurrier and\n Erik Bj\u00e4reholt and\n Maria Sayu Yamamoto and\n Pierre Clisson and\n Marie-Constance Corsi and\n Igor Carrara and\n Apolline Mellot and\n Bruna Junqueira Lopes and\n Brent Gaisford and\n Ammar Mian and\n Anton Andreev and\n Gregoire Cattan and\n Arthur Lebeurrier},\n title = {pyRiemann},\n month = oct,\n year = 2024,\n version = {v0.7},\n publisher = {Zenodo},\n doi = {10.5281/zenodo.593816},\n url = {https://doi.org/10.5281/zenodo.593816}\n}\n```\n\n# References\n\n<a id=\"1\">[1]</a>\nM. Congedo, A. Barachant and R. Bhatia, \"Riemannian geometry for EEG-based brain-computer interfaces; a primer and a review\".\nBrain-Computer Interfaces, 4.3, pp. 155-174, 2017. [link](https://hal.science/hal-01570120/document)\n\n<a id=\"2\">[2]</a>\nA. Barachant, S. Bonnet, M. Congedo and C. Jutten, \"Multiclass Brain-Computer Interface Classification by Riemannian Geometry\".\nIEEE Transactions on Biomedical Engineering, vol. 59, no. 4, pp. 920-928, 2012. [link](https://hal.archives-ouvertes.fr/hal-00681328)\n\n<a id=\"3\">[3]</a>\nA. Barachant, S. Bonnet, M. Congedo and C. Jutten, \"Classification of covariance matrices using a Riemannian-based kernel for BCI applications\".\nNeurocomputing, 112, pp. 172-178, 2013. [link](https://hal.archives-ouvertes.fr/hal-00820475/)\n\n<a id=\"4\">[4]</a>\nA. Barachant and M. Congedo, \"A Plug&Play P300 BCI Using Information Geometry\".\nResearch report, 2014. [link](http://arxiv.org/abs/1409.0107)\n\n<a id=\"5\">[5]</a>\nEK. Kalunga, S. Chevallier, Q. Barth\u00e9lemy, K. Djouani, E. Monacelli and Y. Hamam, \"Online SSVEP-based BCI using Riemannian geometry\".\nNeurocomputing, 191, pp. 55-68, 2014. [link](https://hal.science/hal-01351623/file/Kalunga-Chevallier-Barthelemy-Online%20SSVEP-based%20BCI%20using%20Riemannian%20Geometry-Neurocomputing-16.pdf)\n\n<a id=\"6\">[6]</a>\nPLC. Rodrigues, C. Jutten and M. Congedo, \"Riemannian Procrustes analysis: transfer learning for brain-computer interfaces\".\nIEEE Transactions on Biomedical Engineering, vol. 66, no. 8, pp. 2390-2401, 2018. [link](https://hal.archives-ouvertes.fr/hal-01971856)\n",
"bugtrack_url": null,
"license": "BSD (3-clause)",
"summary": "Machine learning for multivariate data with Riemannian geometry",
"version": "0.7",
"project_urls": {
"Documentation": "https://pyriemann.readthedocs.io",
"Homepage": "https://pyriemann.readthedocs.io",
"Source": "https://github.com/pyRiemann/pyRiemann",
"Tracker": "https://github.com/pyRiemann/pyRiemann/issues/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e8a7ff6e622c57fec2526a9b3ee56b8dd6c6b143a5ee57620eeb98687a9caf78",
"md5": "2b804b74c7dcd29d686afb95b2ad38af",
"sha256": "6ad9c00a583fdab9472f433eb54730d8f55852300fec834e00b32daa295c4089"
},
"downloads": -1,
"filename": "pyriemann-0.7-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b804b74c7dcd29d686afb95b2ad38af",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.9",
"size": 115577,
"upload_time": "2024-10-03T19:58:27",
"upload_time_iso_8601": "2024-10-03T19:58:27.306240Z",
"url": "https://files.pythonhosted.org/packages/e8/a7/ff6e622c57fec2526a9b3ee56b8dd6c6b143a5ee57620eeb98687a9caf78/pyriemann-0.7-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c450e551da680538e4e2add83d77c3dd201fc216900b5bfa9b9f215cabdfef5f",
"md5": "37ccd172c3cd027eb08a300664051654",
"sha256": "f1889f3aec02c4148dec5458299ade2b4a0f28063312c00180a8dfeeea9d9b8e"
},
"downloads": -1,
"filename": "pyriemann-0.7.tar.gz",
"has_sig": false,
"md5_digest": "37ccd172c3cd027eb08a300664051654",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 129218,
"upload_time": "2024-10-03T19:58:30",
"upload_time_iso_8601": "2024-10-03T19:58:30.739083Z",
"url": "https://files.pythonhosted.org/packages/c4/50/e551da680538e4e2add83d77c3dd201fc216900b5bfa9b9f215cabdfef5f/pyriemann-0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-03 19:58:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyRiemann",
"github_project": "pyRiemann",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"!=",
"1.24.0"
]
]
},
{
"name": "scipy",
"specs": []
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"0.24"
]
]
},
{
"name": "joblib",
"specs": []
},
{
"name": "matplotlib",
"specs": []
}
],
"lcname": "pyriemann"
}
JSON
