The Problem
Data scientists often need to extract global shape information from high‑dimensional point clouds, but implementing the Mapper algorithm from scratch is error‑prone and slow. Existing libraries either lack scalability or are hard to embed in standard ML pipelines.
What This Does
tda-mapper delivers a pure‑Python implementation of the Mapper pipeline with a focus on speed. Core logic lives in src/tdamapper/core.py (graph construction) and src/tdamapper/cover.py (lens‑space covering). Spatial queries are delegated to the V‑tree modules under src/tdamapper/utils/vptree, which provide fast k‑NN and ball‑search operations.
The package follows the scikit‑learn estimator contract (src/tdamapper/learn.py), allowing it to be dropped into pipelines like Pipeline([('mapper', TdaMapper(...))]). Visualization back‑ends are abstracted in src/tdamapper/plotbackends/ and exposed through src/tdamapper/plot.py, supporting Matplotlib, Plotly, and PyVis.
An interactive Streamlit UI (app/streamlitapp.py) renders the same graphs in a browser, useful for exploratory analysis.
How To Use It
Setup
Install the library in an editable environment pip install -e .
Optional: build the Docker image for the Streamlit UI docker build -t tda-mapper-app -f app/Dockerfile .
Dependencies are listed in app/requirements.txt (UI) and pyproject.toml (core). No lockfile is provided, so pin versions manually if reproducibility is required.
Configuration
No external configuration files are required for the core library. The UI reads its parameters from Streamlit widgets; the library itself accepts arguments to the TdaMapper class (e.g., lens, cover, clusterer).
Running
Library:
from tdamapper.learn import TdaMapper mapper = TdaMapper(lens='pca', ncubes=10, overlap=0.3) graph = mapper.fittransform(X) # X = ndarray of shape (nsamples, nfeatures)
CLI: The package installs a console script tda-mapper (defined in pyproject.toml) that mirrors the above usage:
tda-mapper --lens pca --cubes 10 --overlap 0.3 data.npy
UI:
streamlit run app/streamlitapp.py or, if using Docker docker run -p 8501:8501 tda-mapper-app
Testing
pytest -q # runs the 23 unit/benchmark tests in tests/ make test # alias defined in the top‑level Makefile
Real‑World Use
A bioinformatics pipeline can embed TdaMapper after dimensionality reduction:
from sklearn.decomposition import PCA from tdamapper.learn import TdaMapper
Xred = PCA(ncomponents=15).fittransform(geneexpression)
mapper = TdaMapper(lens='pca', ncubes=12, overlap=0.25) graph = mapper.fittransform(Xred)
Export graph for downstream network analysis
graph.tonetworkx().write_gml('mapper.gml')
The resulting GML can be consumed by Cytoscape or other graph tools.
Code Health & Issues
Low – missing lockfile – app/requirements.txt lists unpinned versions; reproducible builds depend on external constraints. Low – test coverage limited to unit tests – benchmarks (benchmarks/benchmark.py) are not exercised by CI; performance regressions may go unnoticed. Low – no static security analysis – CI workflows (.github/workflows/.yml) run unit tests and publishing but lack Dependabot or bandit scans. Medium – optional heavy dependencies – Plotly and PyVis are optional back‑ends; importing them unconditionally could raise ImportError in minimal environments. Low – documentation completeness – docs/ provides API reference and notebooks, and ReadTheDocs builds via docs/Makefile. No glaring gaps.
Overall the repository includes a LICENSE, CONTRIBUTING guide, and CI badges indicating active maintenance.
The Bottom Line
tda-mapper offers a well‑structured, test‑backed implementation of the Mapper algorithm with scikit‑learn compatibility and multiple visual back‑ends. It is suitable for teams that need a fast, extensible TDA component and are comfortable managing unpinned Python dependencies. The primary limitation is the lack of a lockfile and automated security checks; adding those would improve reliability for production deployments.