About TMAP
A modernized reimplementation of Probst & Reymond's TMAP (J. Cheminf. 2020) with an sklearn-style API, multiple distance metrics, graph analysis, and interactive visualization.
Background
Dimensionality reduction techniques like t-SNE and UMAP produce scatter plots where similar items cluster together. But clusters are blobs - you can see groups, but you can't trace the relationship between any two specific points. TMAP solves this by producing a tree layout where there is exactly one path between any two data points.
This tree structure enables analyses that are impossible with scatter plots: tracing structure-activity relationships in drug discovery, walking decision boundaries in ML classifiers, following evolutionary paths in protein fold space, and computing pseudotime trajectories in single-cell biology.
TMAP vs UMAP
Both are dimensionality reduction tools, but they serve different analytical needs:
| Feature | TMAP | UMAP |
|---|---|---|
| Output structure | Tree (minimum spanning tree) | Scatter plot (point cloud) |
| Paths between points | Exactly one path - always exists | No guaranteed paths |
| Deterministic | Yes (with seed) | Stochastic by default |
| Cluster boundaries | Explicit tree edges at boundaries | Implicit gaps between blobs |
| Best for | Exploration, SAR, path analysis | Cluster overview, embedding quality |
| Supported metrics | Jaccard, cosine, euclidean, precomputed | Many (via pynndescent) |
Architecture
TMAP's pipeline has four independent, swappable stages:
1. Index
Nearest-neighbor search via MinHash + LSHForest (Jaccard) or USearch (cosine/euclidean). Accepts precomputed k-NN graphs for custom pipelines.
2. Graph
k-NN graph construction with optional sparsification. MST extraction produces the tree structure.
3. Layout
Force-directed layout via OGDF (C++ backend via pybind11). Produces 2D coordinates from the tree or graph structure.
4. Visualization
Interactive HTML output via regl-scatterplot (WebGL). Jupyter integration via jupyter-scatter. Matplotlib for static figures.
Roadmap
TMAP is actively developed. Here's what's done and what's coming:
Completed
- sklearn-style estimator API (fit, fit_transform, transform)
- Dense metric support (cosine, euclidean) via USearch
- Precomputed k-NN graphs and distance matrices
- Graph exploration API (tree paths, subtrees, pseudotime)
- Graph analysis (boundary_edges, confusion_matrix, subtree_purity, edge_delta, path_properties)
- Domain utilities: chemistry (fingerprints, properties, scaffolds), proteins (FASTA, UniProt, AlphaFold), single-cell (AnnData)
- Incremental learning: add_points() and transform()
- Interactive HTML with lasso selection, filtering, search, pinned cards
- jupyter-scatter notebook integration
- Model persistence (save/load)
In Progress
- Matplotlib static plot backend
- Pure-Python layout fallback (no OGDF dependency)
Planned
- Edge weight-based visual styling
- Published speed benchmarks vs UMAP and t-SNE
Contributing
TMAP is open source under the MIT license. Contributions are welcome - from bug reports to feature implementations.