Geometric statistics on manifolds
Project description
Geomstats
.. list-table:: :header-rows: 0
-
- Code
- |PyPI version|\ |Downloads|\ |Zenodo|\
-
- Continuous Integration
- |Build Status|\ |python|\
-
- Code coverage (numpy)
- |Coverage Status np|\
-
- Code coverage (autograd, tensorflow, pytorch)
- |Coverage Status autograd|\ |Coverage Status tf|\ |Coverage Status torch|
-
- Documentation
- |doc|\ |binder|\ |tutorial|\
-
- Community
- |contributions|\ |Slack|\ |Twitter|\
NEWS:
-
Geomstats is recruiting an engineer for a start early 2022! If interested, details can be found
here <https://gstats.inria.fr/files/2021/10/Research_engineer_gs-1.pdf>
_. -
The white paper summarizing the findings from our
ICLR 2021 challenge of computational differential geometry and topology <https://gt-rl.github.io/challenge>
__ is out.Read it here <https://arxiv.org/abs/2108.09810>
__. -
Check out our new
information_geometry <https://github.com/geomstats/geomstats/tree/master/geomstats/information_geometry>
_ module.
Geomstats is an open-source Python package for computations and
statistics on manifolds. The package is organized into two main modules:
geometry
and learning
.
The module geometry
implements concepts in differential geometry,
and the module learning
implements statistics and learning
algorithms for data on manifolds.
.. raw:: html
<img src="https://raw.githubusercontent.com/ninamiolane/geomstats/master/examples/imgs/h2_grid.png" height="120px" width="120px" align="left">
- To get an overview of
geomstats
, see ourintroductory video <https://www.youtube.com/watch?v=Ju-Wsd84uG0&list=PLYx7XA2nY5GejOB1lsvriFeMytD1-VS1B&index=3>
__. - To get started with
geomstats
, see theexamples <https://github.com/geomstats/geomstats/tree/master/examples>
__ andnotebooks <https://github.com/geomstats/geomstats/tree/master/notebooks>
__ directories. - The documentation of
geomstats
can be found on thedocumentation website <https://geomstats.github.io/>
__. - Interested in information geometry? Go to our
information_geometry <https://github.com/geomstats/geomstats/tree/master/geomstats/information_geometry>
_ module. - To follow the scientific literature on geometric statistics, follow
our twitter-bot
@geomstats <https://twitter.com/geomstats>
__!
Citing Geomstats
If you find geomstats
useful, please kindly cite:
- our research
paper <https://jmlr.org/papers/v21/19-027.html>
__ :
::
@article{JMLR:v21:19-027,
author = {Nina Miolane and Nicolas Guigui and Alice Le Brigant and Johan Mathe and Benjamin Hou and Yann Thanwerdas and Stefan Heyder and Olivier Peltre and Niklas Koep and Hadi Zaatiti and Hatem Hajri and Yann Cabanes and Thomas Gerald and Paul Chauchat and Christian Shewmake and Daniel Brooks and Bernhard Kainz and Claire Donnat and Susan Holmes and Xavier Pennec},
title = {Geomstats: A Python Package for Riemannian Geometry in Machine Learning},
journal = {Journal of Machine Learning Research},
year = {2020},
volume = {21},
number = {223},
pages = {1-9},
url = {http://jmlr.org/papers/v21/19-027.html}
}
- and
Geomstats software version <https://zenodo.org/record/5558028>
__ (citation automatically generated by Zenodo at the bottom right of this link).
We would sincerely appreciate citations to both the original research paper and the software version, to acknowledge authors who started the codebase and made the library possible, together with the crucial work of all contributors who are continuously implementing pivotal new geometries and important learning algorithms, as well as refactoring, testing and documenting the code to democratize geometric statistics and (deep) learning and foster reproducible research in this field.
Install geomstats via pip3
From a terminal (OS X & Linux), you can install geomstats and its
requirements with pip3
as follows:
::
pip3 install geomstats
This method installs the latest version of geomstats that is uploaded on PyPi. Note that geomstats is only available with Python3.
Install geomstats via Git
From a terminal (OS X & Linux), you can install geomstats and its
requirements via git
as follows:
::
git clone https://github.com/geomstats/geomstats.git
pip3 install -r requirements.txt
This method installs the latest GitHub version of geomstats.
To add the requirements.txt
into a conda environment, you can use the
enviroment.yml
file as follows:
::
conda env create --file environment.yml
Note that this only installs the minimum requirements. To add the optional,
development, continuous integration and documentation requirements,
refer to the files *-requirements.txt
.
Install geomstats : Developers
Developers should git clone the master branch of this repository, together with the development requirements
and the optional requirements to enable tensorflow
and pytorch
backends:
::
pip3 install -r dev-requirements.txt -r opt-requirements.txt
Additionally, we recommend installing our pre-commit hook, to ensure that your code follows our Python style guidelines:
::
pre-commit install
Choose the backend
Geomstats can run seamlessly with numpy
, tensorflow
or
pytorch
. Note that pytorch
and tensorflow
requirements are
optional, as geomstats can be used with numpy
only. By default, the
numpy
backend is used. The visualizations are only available with
this backend.
To get the tensorflow
and pytorch
versions compatible with
geomstats, install the optional requirements <https://github.com/geomstats/geomstats/blob/master/opt-requirements.txt>
__:
::
pip3 install -r opt-requirements.txt
You can choose your backend by setting the environment variable
GEOMSTATS_BACKEND
to numpy
, tensorflow
or pytorch
, and
importing the backend
module. From the command line:
::
export GEOMSTATS_BACKEND=pytorch
and in the Python3 code:
::
import geomstats.backend as gs
Getting started
To use geomstats
for learning algorithms on Riemannian manifolds,
you need to follow three steps: - instantiate the manifold of interest,
- instantiate the learning algorithm of interest, - run the algorithm.
The data should be represented by a gs.array
. This structure
represents numpy arrays, or tensorflow/pytorch tensors, depending on the
choice of backend.
The following code snippet shows the use of tangent Principal Component
Analysis on simulated data
on the space of 3D rotations.
.. code:: python
from geomstats.geometry.special_orthogonal import SpecialOrthogonal
from geomstats.learning.pca import TangentPCA
so3 = SpecialOrthogonal(n=3, point_type="vector")
metric = so3.bi_invariant_metric
data = so3.random_uniform(n_samples=10)
tpca = TangentPCA(metric=metric, n_components=2)
tpca = tpca.fit(data)
tangent_projected_data = tpca.transform(data)
All geometric computations are performed behind the scenes. The user only needs a high-level understanding of Riemannian geometry. Each algorithm can be used with any of the manifolds and metric implemented in the package.
To see additional examples, go to the
examples <https://github.com/geomstats/geomstats/tree/master/examples>
__
or
notebooks <https://github.com/geomstats/geomstats/tree/master/notebooks>
__
directories.
Contributing
See our
contributing <https://github.com/geomstats/geomstats/blob/master/docs/contributing.rst>
__
guidelines!
Interested? Contact us and join the next hackathons. Previous Geomstats events include:
- January 2020: hackathon at Inria Sophia-Antipolis, Nice, France
- April 2020: remote online hackathon
- March - April 2021: hackathon, hybrid at Inria Sophia-Antipolis / remotely with contributors from around the world
- July 2021: hackathon at the Geometric Science of Information (GSI) conference, Paris, France
- August 2021: International Coding Challenge at the International Conference on Learning Representations (ICLR), remotely
- December 2021: Fixit hackathon at the Sorbonne Center for Artificial Intelligence, Paris, France.
Acknowledgements
This work is supported by:
- the Inria-Stanford associated team
GeomStats <http://www-sop.inria.fr/asclepios/projects/GeomStats/>
__, - the European Research Council (ERC) under the European Union's Horizon 2020 research and innovation program (grant agreement
G-Statistics <https://team.inria.fr/epione/en/research/erc-g-statistics/>
__ No. 786854), - the French society for applied and industrial mathematics (
SMAI <http://smai.emath.fr/>
__), - the National Science Foundation (grant NSF DMS RTG 1501767).
.. |Twitter| image:: https://img.shields.io/twitter/follow/geomstats?label=Follow%20%40geomstats%20%20%20%20&style=social :target: https://twitter.com/geomstats .. |PyPI version| image:: https://badge.fury.io/py/geomstats.svg :target: https://badge.fury.io/py/geomstats .. |Build Status| image:: https://github.com/geomstats/geomstats/actions/workflows/test.yml/badge.svg :target: https://github.com/geomstats/geomstats/actions/workflows/test.yml .. |Slack| image:: https://img.shields.io/badge/Slack-Join-yellow :target: https://geomstats.slack.com/ .. |Coverage Status np| image:: https://codecov.io/gh/geomstats/geomstats/branch/master/graph/badge.svg?flag=numpy :target: https://codecov.io/gh/geomstats/geomstats .. |Coverage Status autograd| image:: https://codecov.io/gh/geomstats/geomstats/branch/master/graph/badge.svg?flag=autograd :target: https://codecov.io/gh/geomstats/geomstats .. |Coverage Status tf| image:: https://codecov.io/gh/geomstats/geomstats/branch/master/graph/badge.svg?flag=tensorflow :target: https://codecov.io/gh/geomstats/geomstats .. |Coverage Status torch| image:: https://codecov.io/gh/geomstats/geomstats/branch/master/graph/badge.svg?flag=pytorch :target: https://codecov.io/gh/geomstats/geomstats .. |Zenodo| image:: https://zenodo.org/badge/108200238.svg :target: https://zenodo.org/badge/latestdoi/108200238 .. |Downloads| image:: https://static.pepy.tech/personalized-badge/geomstats?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=Downloads :target: https://pepy.tech/project/geomstats .. |python| image:: https://img.shields.io/badge/python-3.7+-blue?logo=python :target: https://www.python.org/ .. |tutorial| image:: https://img.shields.io/youtube/views/Ju-Wsd84uG0?label=watch&style=social :target: https://www.youtube.com/watch?v=Ju-Wsd84uG0 .. |doc| image:: https://img.shields.io/badge/docs-website-brightgreen?style=flat :target: https://geomstats.github.io/?badge=latest .. |binder| image:: https://mybinder.org/badge_logo.svg :target: https://mybinder.org/v2/gh/geomstats/geomstats/master?filepath=notebooks .. |contributions| image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat :target: https://geomstats.github.io/contributing.html
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for geomstats-2.4.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bdc65d64a6fdd4773367ddb1f2fcc3adb2d9e6801589399a19fd2ab6b1c759cc |
|
MD5 | 16987b555eb4d630b1fa2c37e6f83d40 |
|
BLAKE2b-256 | 09596b50fc15f62138642602659825c73172df1d4c6870d74768cbddbd642be3 |