KeplerMapper: the Mapper algorithm for high-dimensional data in Python

Mapper, the algorithm and the paper behind it

The README describes the project as a Python implementation of the TDA Mapper algorithm for visualization of high-dimensional data, with the full documentation hosted at kepler-mapper.scikit-tda.org. The name comes from Johannes Kepler, who is quoted at the top of the README saying that nature uses as little as possible of anything.

The method comes from Singh et al., and the README names the paper: Topological Methods for the Analysis of High Dimensional Data Sets and 3D Object Recognition. That provenance matters for a reader deciding whether to trust the implementation, because the Mapper algorithm is not a visualisation trick but a specific construction with a specific definition, and the README is explicit that KeplerMapper employs approaches based on that algorithm as first described in the paper rather than an interpretation of it.

The problem it addresses is real and unglamorous. You have data with many dimensions, a projection to two dimensions is lossy in ways that hide structure, and a scatter plot of the first two columns tells you about two columns. Mapper instead covers the space with overlapping clusters, pulls each cluster back through a chosen projection, and lays those out as nodes with edges between them, so a shape in the data becomes a shape in the graph you can navigate.

The alternative approach a reader should hold in mind is a plain dimensionality reduction, PCA or UMAP, which produces one embedding. Mapper produces many small ones, and the graph is what carries the structure.

fit_transform, map, visualize

The usage example is the whole API in twenty lines, and it is worth reading closely because the three steps are not the three steps you might expect.

# Import the class
import kmapper as km

# Some sample data
from sklearn import datasets
data, labels = datasets.make_circles(n_samples=5000, noise=0.03, factor=0.3)

# Initialize
mapper = km.KeplerMapper(verbose=1)

# Fit to and transform the data
projected_data = mapper.fit_transform(data, projection=[0,1]) # X-Y axis

`fit_transform` takes the data and a projection, which here is the list of dimension indices `[0,1]`, and the comment marks it as the X-Y axis. So the projection is a choice of which original dimensions to draw the clusters in, not a learned embedding.

The next step builds the graph:

graph = mapper.map(projected_data, data, cover=km.Cover(n_cubes=10))

and the README describes the result as a dictionary called graph with nodes, edges and meta-information. The cover is the object that controls the clustering of the space into overlapping cubes, and here it is constructed with ten cubes.

Finally the visualisation writes an HTML file:

mapper.visualize(graph, path_html="make_circles_keplermapper_output.html",
                 title="make_circles(n_samples=5000, noise=0.03, factor=0.3)")

So the output is a self-contained page you open in a browser, not a figure you embed in a paper.

The scikit-learn shape is the reason it feels familiar

The README says KeplerMapper adopts the scikit-learn API as much as possible, so it should feel familiar to anyone who has used these libraries, and it can make use of Scikit-Learn API compatible cluster and scaling algorithms.

That sentence carries more weight than it looks. The Mapper construction has two places where a modelling choice enters: how the space is covered and clustered, and how the data is scaled. If the library takes the estimators from scikit-learn, then the clustering algorithm is the one you already use, with the parameters you already know, and the scaling is a scikit-learn transformer in your pipeline.

That is a substantial design decision. The alternative is a library with its own clustering defaults, which would mean the result depends on choices you cannot see and cannot easily change. With the scikit-learn approach, the algorithm's output is a function of your choices, and swapping K-means for a different clustering algorithm is a parameter rather than a fork.

It also means the dependencies are the ones you already have, which is the subject of the next section. The example even generates its data with `datasets.make_circles` from scikit-learn, which keeps the whole example inside one familiar ecosystem.

Three required dependencies, three for the plotly path

The dependency list is short and is split by what you actually need.

KeplerMapper requires Python of version 3.6 or newer, NumPy and Scikit-learn. That is the whole core requirement, and it is a small footprint for a visualisation tool, because the drawing is done by the browser rather than by a rendering library.

Using the plotly visualizations requires a few extra libraries: igraph, Plotly and Ipywidgets. And additionally, running some of the examples requires matplotlib and umap-learn.

That split tells you something about the architecture. The algorithm needs only the numerics, and the interactive output needs the graph library and the plotting library, with ipywidgets there so the widgets can be driven from a notebook. The extra requirements for examples are the giveaway that the examples reach beyond the core: matplotlib for static figures, and umap-learn so an example can use UMAP as the projection in place of a plain dimension selection.

So the cost of adoption is the core plus three libraries if you want the interactive output, and the ability to run the gallery of examples depends on two more that the algorithm itself does not need.

Install with pip, or clone the repository yourself

Installation from PyPI is one command:

pip install kmapper

The source route is three lines:

git clone https://github.com/MLWave/kepler-mapper
cd kepler-mapper
pip install -e .

There is a documentation wrinkle in those instructions. The clone URL points at the MLWave organisation, while the repository this project lives in is under scikit-tda, and the package is published on PyPI as `kmapper` with the badge in the README pointing at the PyPI project page. The clone URL is the historical one from when the project was developed at MLWave, and it is the kind of detail that costs a contributor a confused minute if they follow it literally.

The packaging is plain setuptools. The setup script reads the version out of `kmapper/_version.py` with a regular expression at build time rather than hard-coding it, and the script raises an error if it cannot find the version string. That is the pattern that lets a tag-driven release flow work without editing the setup file, and the repository carries a RELEASE.md alongside it.

The project also defines extras, so testing and documentation dependencies are installable on demand rather than by default.

Alpha status, and a paper with a DOI

The Disclaimer section of the README is short and says two things. The standard MIT disclaimer applies, with the full text in DISCLAIMER.txt, and the development status is Alpha.

Alpha is worth taking seriously for a library at version 2.1.0. It is not a statement that the code is broken, but it is a statement from the maintainers that the API may still change and that they do not consider the surface frozen.

The other half of the Disclaimer section points at the citation instructions, and the README's badges show that the paper has been published in the Journal of Open Source Software, with a DOI badge for 10.21105/joss.01315 and a separate Zenodo badge for 10.5281/zenodo.1002377. The repository carries the paper sources as `paper.md` and `paper.bib`, and the how-to-cite link points into the documentation site.

Those two facts together are the best summary of the project. There is a citable paper, which means the algorithm and the implementation have been reviewed as a scientific contribution, and there is an alpha status, which means the code is a research tool that happens to be packaged well rather than a supported library with a stability promise.

The repository holds the paper, the examples and an old folder

The top-level layout is a good map of what the project contains. There is the `kmapper` package itself, a `docs` directory for the documentation site, an `examples` directory, a `test` directory with a tox.ini and a .coveragerc, and the usual project files, including setup.py, MANIFEST.in and a .zenodo.json for the archive metadata.

The examples directory is the part worth browsing. It holds datasets as CSV files, with breast-cancer.csv, cat-reference.csv and horse-reference.csv, and matching directories for breast-cancer, cat and horse, plus digits, makecircles, data, gallery and output directories. Alongside them are the plotting scripts, `plot_breast_cancer.py`, `plot_cat.py`, `plot_digits.py` and `plot_horse.py`, and a readme.md describing them.

The breast cancer example is the interesting one to know about, because the scikit-learn dataset it uses is a standard, small and well-known classification dataset, which makes it a convenient check that the pipeline behaves as you expect before you point the tool at something larger.

One thing in the layout deserves a raised eyebrow: there is a directory called `depricated/`, with the misspelling. It is not described in the README, so what it holds and whether it is still maintained is not something the documentation answers. For a project with a paper and a Zenodo archive, a stray directory with an unclear name is a small signal to look before you rely on anything inside it.

The last tagged release is two years behind the branch

The recent releases tell a story of a long gap. The versions are v2.1.0 from 2024-07-06, v2.0.1 from 2021-05-12 and v2.0.0 from 2021-03-15, and the release notes are written in the release message rather than in a changelog file, with v2.0.1 described as fixing plotlyviz colours, fixing agglomerative clustering and changing the searchbar default, and v2.0.0 as brand new visualizations with a colour picker.

So the 2.0 line shipped in March and May 2021, and then there is a single release in July 2024. The repository is not archived and the last push was on 2026-08-02, which puts the branch a couple of years ahead of the newest tag.

For a library like this, that is a normal and mostly healthy pattern. The 2.0 releases carried a visible set of changes to the visualisation layer, the 2.1 release was a smaller step forward, and the work since then appears to be maintenance rather than a stream of new versions. The implication for a user is the same as for any library with an infrequent release train: read the documentation site for the current behaviour rather than assuming the tag you install matches the documentation you read.

The licence is MIT, and the project sits under the scikit-tda organisation, with the authors listed in the setup script as HJ van Veen, Nathaniel Saul, David Eargle and Sam Mangham, and a longer list in AUTHORS.md and CONTRIBUTORS.md.

Editorial conclusion

KeplerMapper fits an analyst who has a high-dimensional dataset and wants a navigable picture of its structure rather than a static projection, and who is comfortable with scikit-learn's estimator conventions. It is the wrong choice if you need a production pipeline with guaranteed stability, since the project states its development status is Alpha and its last tagged release predates its most recent push by two years. Verify first which clustering and scaling implementations you will plug in, since the algorithm's result depends entirely on those choices, and read the documentation site for the cover and projection options beyond the ones shown in the README example.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. scikit-tda/kepler-mapper on GitHub