tmap

Getting Started

Install TMAP and create your first interactive tree visualization in under 5 minutes.

Installation

TMAP requires Python 3.11 or later. Install it from PyPI:

terminalbash
# Create a virtual environment (recommended)
python -m venv tmap-env
source tmap-env/bin/activate  # or tmap-env\Scripts\activate on Windows

# Install TMAP
pip install tmap2

For dense metric support (cosine, euclidean), also install FAISS: pip install tmap2[faiss]

Quick Start

TMAP uses a familiar sklearn-style API. Fit your data, then explore the tree structure:

quickstart.pypython
from tmap import TMAP
import numpy as np

# Generate some sample data (binary fingerprints)
np.random.seed(42)
data = np.random.randint(0, 2, size=(500, 256)).astype(np.uint8)

# Create a TMAP - sklearn-style API
model = TMAP(n_neighbors=15, metric="jaccard", seed=42)
model.fit(data)

# Access the embedding coordinates
print(f"Coordinates shape: {model.embedding_.shape}")
print(f"Tree edges: {len(model.tree_.edges)} edges")

Your First Visualization

Export an interactive HTML visualization you can open in any browser:

visualize.pypython
# Export as interactive HTML
model.to_html("my_first_tmap.html")

# Or with custom colors
import numpy as np
colors = np.random.rand(500)  # some property to color by
model.to_html("colored_tmap.html", color=colors)

This creates a self-contained HTML file with pan, zoom, and hover interactions. No server required.

Notebook Usage

TMAP integrates with Jupyter notebooks via jupyter-scatter for interactive exploration:

notebook.pypython
# In a Jupyter notebook
model.plot()  # interactive jupyter-scatter widget

# Or with custom settings
model.plot(color=colors, point_size=5)

Requires pip install tmap2[notebook]

Try in Google Colab

No installation needed - run TMAP directly in your browser with Google's free compute. The quickstart notebook walks you through building your first visualization from scratch.

Open Quickstart Notebook

The Full Pipeline

For more control, you can use the lower-level pipeline directly. This gives you access to each stage independently:

pipeline.pypython
from tmap import MinHash, LSHForest
from tmap.layout import layout_from_lsh_forest, LayoutConfig

# 1. Encode your data as MinHash signatures
mh = MinHash(num_perm=128, seed=42)
signatures = mh.batch_from_binary_array(your_fingerprints)

# 2. Build the LSH Forest index
lsh = LSHForest(d=128, l=64)
lsh.batch_add(signatures)
lsh.index()

# 3. Compute layout with custom config
cfg = LayoutConfig()
cfg.k = 20      # neighbors per point
cfg.kc = 50     # search quality
cfg.deterministic = True
cfg.seed = 42

x, y, s, t = layout_from_lsh_forest(lsh, cfg)

# x, y are coordinates; s, t are tree edge indices

Next Steps