`pytorch-topological`: A topological machine learning framework for `pytorch`

pytorch-topological (or torch_topological) is a topological machine learning framework for PyTorch. It aims to collect loss terms and neural network layers in order to simplify building the next generation of topology-based machine learning tools.

Topological machine learning in a nutshell

Topological machine learning refers to a new class of machine learning algorithms that are able to make use of topological features in data sets. In contrast to methods based on a purely geometrical point of view, topological features are capable of focusing on connectivity aspects of a data set. This provides an interesting fresh perspective that can be used to create powerful hybrid algorithms, capable of yielding more insights into data.

This is an emerging research field, firmly rooted in computational topology and topological data analysis. If you want to learn more about how topology and geometry can work in tandem, here are a few resources to get you started:

Amézquita et al., The Shape of Things to Come: Topological Data Analysis and Biology, from Molecules to Organisms, Developmental Dynamics Volume 249, Issue 7, pp. 816--833, 2020.
Hensel et al., A Survey of Topological Machine Learning Methods, Frontiers in Artificial Intelligence, 2021.

Installation and requirements

torch_topological requires Python 3.9. More recent versions might work but necessitate building some dependencies by yourself; Python 3.9 currently offers the smoothest experience. It is recommended to use the excellent poetry framework to install torch_topological:

poetry add torch-topological

Alternatively, use pip to install the package:

pip install -U torch-topological

A note on older versions. Older versions of Python are not explicitly supported, and things may break in unexpected ways. If you want to use a different version, check pyproject.toml and adjust the Python requirement to your preference. This may or may not work, good luck!

Usage

torch_topological is still a work in progress. You can browse the documentation or, if code reading is more your thing, dive directly into some example code.

Here is a list of other projects that are using torch_topological:

SHAPR, a method for for predicting the 3D cell shape of individual cells based on 2D microscopy images

This list is incomplete---you can help expanding it by using torch_topological in your own projects! 😇

Contributing

Check out the contribution guidelines or the road map of the project.

Acknowledgements

Our software and research does not exist in a vacuum. pytorch-topological is standing on the shoulders of proverbial giants. In particular, we want to thank the following projects for constituting the technical backbone of the project:

`giotto-tda`	`gudhi`

Furthermore, pytorch-topological draws inspiration from several projects that provide a glimpse into the wonderful world of topological machine learning:

difftda by Mathieu Carrière
Ripser by Ulrich Bauer
Teaspoon by Elizabeth Munch and her team
TopologyLayer by Rickard Brüel Gabrielsson
topological-autoencoders by Michael Moor, Max Horn, and Bastian Rieck
torchph by Christoph Hofer and Roland Kwitt

Finally, pytorch-topological makes heavy use of POT, the Python Optimal Transport Library. We are indebted to the many contributors of all these projects.