Reference · The manual
All the features, in one place.
TMAP is a small library with a lot of capabilities. This page is the complete catalog, grouped by what you'd use each feature for. Click [preview ▸] on any row to see it in action.
§ 01 · In the browser
Interactive viewer.
Every TMAP compiles to a self-contained HTML file (or a local server for the really big ones). Here's everything in the viewer.
Filter panelsmulti-column
Numeric ranges, categorical checkboxes, computed expressions. Filters compose - use several at once to carve out any subset. Dimmed points stay on screen so you can see the topology.
Text search⌘ K
Full-text search across any metadata column - IDs, names, SMILES, InChI. The map zooms and highlights matches, with indexed lookups in under a millisecond on 10M+ nodes.
Lasso selectionfreehand
Draw a polygon around any region. Get live summary statistics on the selection; export to CSV with one click, or send to a downstream notebook.
3D structure viewerMol*
Click a node in a protein-fold map to open its PDB structure in a draggable 3D viewer. Structures are lazy-loaded from AlphaFold DB when needed.
Molecule tooltipsSMILES → 2D
Hover any molecule node to see its 2D structure rendered on the fly from SMILES. No precomputation required.
Image thumbnailsany dataset
For image-based datasets, tooltips show the actual image. Works with any URL-reachable thumbnail column.
Protein structure cardsAlphaFold DB
For protein maps, the hover card includes a live Mol* 3D preview pulled directly from AlphaFold - no local PDB files needed.
model.serve()local HTTP
For maps too big to embed in a single HTML file, spin up a local server. The viewer streams tiles on demand - same UI, no 100MB downloads.
# stream a 100M-node map instead of a 2GB HTML file
model.serve(port=8080)§ 02 · Python API
A single class, sklearn-style.
The 2.0 API collapses the old multi-step pipeline into one model object. If you've ever used scikit-learn, you already know how to use TMAP.
.fit(X)any vector data
Pass a 2D array, get a fitted model. Works on fingerprints, protein embeddings, sentence vectors, image features, single-cell counts - anything you can represent as rows of numbers.
from tmap import TMAP
model = TMAP(metric="cosine", seed=42).fit(X)Metric choicepluggable
jaccard, euclidean, cosine, or pass your own callable. No more hard-coded binary fingerprint assumption.
TMAP(metric="jaccard") # binary fingerprints
TMAP(metric="cosine") # embeddings
TMAP(metric=my_callable) # customReproducible seedseed=42
Identical inputs produce identical maps. Run it twice, ship a figure once.
.add_points(X_new)mutating
Grow an existing map by adding new points. The tree structure updates incrementally - no full rebuild.
model.add_points(X_new).transform(X_new)non-mutating
Project new points onto an existing map without modifying it. Returns 2D coordinates only. Use this for out-of-sample queries.
coords = model.transform(X_new) # (n, 2) array.save() / .load()pickle
Persist a fitted model to disk and reload it later. Everything - tree, index, metadata - round-trips cleanly.
model.save("map.pkl")
model = TMAP.load("map.pkl")Precomputed KNNpower user
Bring your own k-nearest-neighbors graph if you need exotic distance metrics or billion-scale inputs. TMAP will build the tree from the graph you give it.
model = TMAP().fit_from_knn(knn_graph)§ 03 · Exploration queries
The tree is a graph you can query.
Because TMAP produces an actual spanning tree - not a lossy 2D projection - you can run exact graph queries on it.
model.path(a, b)shortest path
Return the exact sequence of nodes connecting any two points along the tree. Walk from one molecule to another and see every intermediate structure.
model.distance(a, b)tree metric
Tree distance between any two points - a principled similarity measure that respects the original high-dimensional topology.
d = model.distance("a", "b")model.distances_from(a)pseudotime
Tree distance from a single source to every other point. Useful for pseudotime analysis in single-cell data, or for 'distance from this reference compound' in chemistry.
Tree analysisstructural
Boundary edges between labeled classes, subtree purity, per-node diversity, per-edge property changes. Lets you ask structural questions that scatter plots can't answer.
tree = model.tree_
# boundary edges: tree edges whose endpoints fall in different classes
crossings = [(u, v) for u, v in tree.edges if y[u] != y[v]]
sizes = tree.subtree_sizes() # subtree size rooted at every node§ 04 · Plotting & export
Notebook, paper, or dataframe.
Three output formats, one model. Pick whichever fits the stage you're at.
Notebook integrationjupyter-scatter
Call model.show() inside a Jupyter cell for a live, pannable, lasso-able scatter right in the notebook. No HTML export, no extra files.
model.show() # interactive scatter in the cellplot_static()matplotlib
Publication-quality static figures via matplotlib. Configurable node size, edge alpha, coloring, annotations - whatever your paper needs.
DataFrame exportpandas
Dump the raw map - coordinates, tree edges, properties - to a pandas DataFrame for custom analysis.
df = model.to_dataframe()
# columns: x, y, parent, properties...§ 05 · Domain utilities
Batteries included.
TMAP ships with helpers for three common domains, so you rarely need to write boilerplate. Skip this section if you're working with generic vectors.
Chemistrytmap.chem
SMILES → fingerprints, Murcko scaffolds, molecular & reaction properties. Everything you need to go from a CSV of SMILES to a TMAP in a few lines.
from tmap.chem import mol_to_mhfp
X = [mol_to_mhfp(smi) for smi in smiles]Proteinstmap.bio
UniProt / AlphaFold / PDB fetchers, sequence properties, MMseqs2 and Foldseek alignment parsing. Built for fold-space and sequence-space maps.
from tmap.bio import fetch_alphafold, esm_embed
X = esm_embed(sequences)Single-celltmap.sc
AnnData integration, cell metadata, marker scoring. Works side-by-side with scanpy workflows - TMAP as a replacement for UMAP on single-cell counts.
from tmap.sc import from_anndata
model = from_anndata(adata, metric="cosine")§ 06 · Installation
One command.
No more C++ build dance. OGDF ships as a prebuilt extension inside the Python package.
pippypi
One command. Manylinux, macOS, and Windows wheels all published - if pip resolves it, it'll run.
pip install tmap2