Skip to main content

Geometric statistics on manifolds

Project description

Geomstats

Code PyPI versionDownloads Zenodo
Continuous Integration Build Statuspython
Code coverage (numpy) Coverage Status np
Code coverage (autograd, tensorflow, pytorch) Coverage Status autogradCoverage Status tfCoverage Status torch
Documentation doc bindertutorial
Community contributions Slack Twitter

NEWS:

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.

Keep in touch with the community by joining us on our slack workspace!

Citing Geomstats

If you find geomstats useful, please kindly cite:

@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}
}

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
cd geomstats
pip3 install .

This method installs the latest GitHub version of geomstats.

To add the requirements 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 file setup.cfg.

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 geomstats[dev,opt]

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, autograd, tensorflow or pytorch. Note that autograd, tensorflow and pytorch and 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 autograd, tensorflow and pytorch versions compatible with geomstats, install the optional requirements:

pip3 install geomstats[opt]

To install only the requirements for a given backend do:

pip3 install geomstats[<backend_name>]

You can choose your backend by setting the environment variable GEOMSTATS_BACKEND to numpy, autograd, tensorflow or pytorch, and importing the backend module. From the command line:

export GEOMSTATS_BACKEND=<backend_name>

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.

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 or notebooks directories.

Contributing

See our contributing 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.
  • February 2022: hackathon, hybrid at Inria Sophia-Antipolis / remotely with contributors from around the world
  • April 2022: in-person hackathon at the Villa Cynthia, Saint Raphael, France.
  • August 2022: international Coding Challenge at the International Conference on Learning Representations (ICLR), remotely
  • October 17-21, 2022: hackathon during the trimester Geometry and Statistics in Data Sciences, in Paris.

Acknowledgements

This work is supported by:

  • the Inria-Stanford associated team GeomStats,
  • the European Research Council (ERC) under the European Union’s Horizon 2020 research and innovation program (grant agreement G-Statistics No. 786854),
  • the French society for applied and industrial mathematics (SMAI),
  • the National Science Foundation (grant NSF DMS RTG 1501767).

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

geomstats-2.5.0.tar.gz (7.0 MB view hashes)

Uploaded source

Built Distribution

geomstats-2.5.0-py3-none-any.whl (7.5 MB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page