scikit-tda/ripser.py
A Lean Persistent Homology Library for Python
What is Ripser.py?
Ripser.py is a Python wrapper around the fast C++ library Ripser, providing a lightweight, easy‑to‑use toolkit for persistent homology – a core method in topological data analysis (TDA). It lets you turn point‑clouds, distance matrices, or images into persistence diagrams, which capture multi‑scale shape information useful in many machine‑learning pipelines.
Key capabilities
| Capability | What it does |
|---|---|
| Persistence cohomology | Computes Vietoris‑Rips (or lower‑star) filtrations for sparse or dense data and returns birth/death pairs. |
| Diagram visualisation | Simple plot_diagrams helper (via the persim package) to draw persistence diagrams. |
| Image filtrations | Generates lower‑star filtrations directly from grayscale images. |
| Representative cochains | Extracts concrete cochains that realise the homology classes shown in the diagrams. |
| Scikit‑learn compatible API | Provides an Rips transformer (fit_transform / plot) that plugs into pipelines. |
Installation
# From PyPI (pre‑built wheels for Windows, macOS, Linux)
pip install ripser
If you need to build from source (e.g., to edit the code) clone the repo and run pip install . or pip install -e . for an editable install. The only required dependencies are Cython, numpy, scipy, scikit‑learn, persim. On Windows you may need MinGW; on macOS ensure Xcode command‑line tools are up‑to‑date.
Optional speed boost: cloning the robin‑hood‑hashing repository into the project root enables a faster hash map implementation, giving up to ~30 % speed‑up.
Quick example
import numpy as np
from ripser import ripser, Rips
from persim import plot_diagrams
# Random 2‑D point cloud
X = np.random.random((100, 2))
# Functional API
dgms = ripser(X)['dgms']
plot_diagrams(dgms, show=True)
# Scikit‑learn style
rips = Rips()
dgms2 = rips.fit_transform(X)
rips.plot(dgms2)
The code above produces a persistence diagram (see the README image) showing the lifetimes of topological features across scales.
Documentation & resources
- Full docs: https://ripser.scikit-tda.org
- JOSS paper (citable): DOI 10.21105/joss.00925
- Related projects: original C++ library Ripser, GPU‑accelerated Ripser++.
License & citation
- License: MIT (both the Python wrapper and the underlying C++ code).
- When using the library in research, cite the JOSS article and the original Ripser paper (both BibTeX entries are provided in the README).
Who might use this?
- Data scientists applying TDA to point‑clouds, time‑series, or images.
- Researchers building features for classification, clustering, or anomaly detection.
- Anyone needing a fast, pure‑Python interface to persistent homology without dealing with C++ compilation hassles.
Related
- Project
- Project
- Project
- Project
- Project