tda mapper python - Moses Yebei

The Problem

High-dimensional datasets hide structure that standard clustering misses. The Mapper algorithm builds a graph that captures topological shape—clusters, loops, and transitions—but implementations are often slow and don't integrate with existing ML tooling. tda-mapper-python addresses this with an optimized, scikit-learn-compatible library.

What This Does

The library implements the full Mapper pipeline: lens functions (lens_pca, lens_umap in src/tdamapper/app.py), covers (BallCover, CubicalCover in src/tdamapper/cover.py), clustering (TrivialClustering in src/tdamapper/learn.py), and graph construction (mapper_graph in src/tdamapper/core.py). It includes three visualization backends—Plotly, Matplotlib, PyVis—under src/tdamapper/plot_backends/.

A Streamlit web app (app/streamlit_app.py) provides interactive parameter exploration. The package also ships benchmark scripts (benchmarks/benchmark.py) and 23 test files covering units, benchmarks, and integration with scikit-learn.

How It Is Wired

Execution starts at main in src/tdamapper/app.py:1032, which reaches 135 functions. The CLI path calls run in src/tdamapper/_run_app.py, which reaches 136 functions. The core pipeline flows: run_mapper (reaches 68 functions) → fit_transform (called from 27 places) → MapperAlgorithm (called from 20 places) → mapper_connected_components (9 callers).

The most-connected hub is src/tdamapper/cover.py—31 functions, 7 classes, called from 9 files. src/tdamapper/utils/vptree_flat/common.py follows with 16 functions called from 15 files; it implements the vantage-point tree spatial index that powers efficient neighbor searches. src/tdamapper/core.py owns graph assembly and clustering orchestration.

The code touches the outside world minimally: one function runs an external command, two read/write files. The module graph shows no circular dependencies—13 import edges across 60 internal modules—so changing one component won't cascade through cycles.

How To Use It

git clone https://github.com/moses-y/tda-mapper-python
cd tda-mapper-python
pip install -e .          # from pyproject.toml
python -m tdamapper.app   # CLI entry point
streamlit run app/streamlit_app.py  # web UI

Configuration happens through the CLI or Streamlit UI—no required environment variables. The Makefile provides convenience targets for testing and benchmarking. Docker users can build from app/Dockerfile.

Real-World Use

from tdamapper import MapperAlgorithm
from tdamapper.cover import BallCover
from tdamapper.learn import TrivialClustering

mapper = MapperAlgorithm(
    lens='pca',          # or 'umap', or custom
    cover=BallCover(radius=0.3),
    clustering=TrivialClustering()
)
graph = mapper.fit_transform(X)  # returns networkx graph

This fits into pipelines where you need to visualize cluster topology before choosing a segmentation strategy—e.g., customer segmentation from high-dimensional behavioral data.

Code Health & Issues

Static analysis found 11 issues (2 high, 9 medium):

High - Duplicated code blocks: 174 repeated 6-line blocks across 27 files, notably in docs/source/notebooks/ and tests/example.py. Extract shared helpers.
High - Deep nesting (depth 8) in benchmarks/benchmark.py, src/tdamapper/_common.py, src/tdamapper/plot_backends/plot_plotly.py. Use early returns.
Medium - File opened without context manager in tests/test_unit_app.py.
Medium - Oversized files: app/streamlit_app.py, src/tdamapper/app.py (834 lines), plot_plotly.py.
Medium - High branching density in docs/source/notebooks/cover.py (24 branches over 79 lines).

SDLC gaps: no lockfile (non-reproducible builds), GitHub Actions pinned to mutable tags (use SHA pins), no Dependabot, Docker base image unpinned, no non-root user in container, no dependency vulnerability scan in CI.

The Bottom Line

A solid, well-tested Mapper implementation with clean module boundaries and no circular dependencies. The main risks are maintainability (duplication, large files) and supply-chain hygiene (unpinned dependencies, mutable CI tags). Use it if you need topological data analysis in a scikit-learn workflow; fix the lockfile and CI pins before production.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

107 files

Python60
Markdown6
YAML5
reStructuredText5
JSON1
TOML1

FlaskDocker

Module dependencies

The 10 most depended-upon modules of 60, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_tests_test_utils["test_utils"] n1_tests_setup_logging["setup_logging"] n2_tests_ball_tree["ball_tree"] n3_tests_example["example"] n4_tests_test_bench_cover["test_bench_cover"] n5_tests_test_bench_vptree["test_bench_vptree"] n6_tests_test_unit_vptree["test_unit_vptree"] n7_tests_test_bench_metrics["test_bench_metrics"] n8_tests_test_unit_cover["test_unit_cover"] n9_tests_test_unit_heap["test_unit_heap"] n4_tests_test_bench_cover --> n2_tests_ball_tree n4_tests_test_bench_cover --> n1_tests_setup_logging n7_tests_test_bench_metrics --> n1_tests_setup_logging n5_tests_test_bench_vptree --> n2_tests_ball_tree n5_tests_test_bench_vptree --> n1_tests_setup_logging n8_tests_test_unit_cover --> n0_tests_test_utils n9_tests_test_unit_heap --> n0_tests_test_utils n6_tests_test_unit_vptree --> n2_tests_ball_tree n6_tests_test_unit_vptree --> n0_tests_test_utils

Findings

LowDependencies declared without a lockfile - non-reproducible builds app/requirements.txt

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium6

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

pypa/gh-action-pypi-publish@release/v1, codecov/codecov-action@v4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/test-bench.yml

2 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

4 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

app/Dockerfile

python:3.11-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/publish-pypi.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

app/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/publish-pypi.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.