Diorama

Interactive 2D/3D embedding visualization for JSON documents.

Diorama takes high-dimensional embeddings and a list of JSON documents, runs dimensionality reduction, and produces interactive Plotly scatter plots. Color points by any field in your documents, filter with MongoDB query syntax, and switch between perspectives via dropdown.

Install

pip install diorama[umap]        # core + UMAP (recommended)
pip install diorama[all]         # core + UMAP + T-SNE + Dash app

Quick start

import numpy as np
import diorama

# Load your data
documents = [{"city": "Sydney", "score": 4.2, "category": "A"}, ...]
embeddings = np.load("embeddings.npy")  # (N, D) array

# Reduce and visualize in one call
fig = diorama.show(embeddings, documents, color_by="category")

Reduce once, explore fast

UMAP is the expensive step. Run it once and reuse the result:

reduced = diorama.reduce(embeddings, n_components=2, show_progress=True)

# Fast iterations — only filtering + plotting
diorama.show(reduced, documents, color_by="city")
diorama.show(reduced, documents, color_by="score")
diorama.show(reduced, documents, filter={"score": {"$gt": 3.0}})

Positions are stable across calls — the same document always appears at the same coordinates.

Large datasets

For 100K+ points, fit UMAP on a subset and transform the rest:

reduced = diorama.reduce(
    embeddings, n_components=2,
    subsample=10_000, show_progress=True,
)

Coloring

Pass a single field, a list of fields (creates a dropdown), or None to auto-discover:

# single field
diorama.show(reduced, documents, color_by="category")

# dropdown
diorama.show(reduced, documents, color_by=["category", "city", "score"])

# auto-discover top 15
diorama.show(reduced, documents)

Numeric fields with many unique values are colored continuously. Low-cardinality numerics, strings, and booleans are categorical. Override with:

diorama.show(
    reduced, documents,
    color_by="score",
    color_type_overrides={"score": "categorical"},
)

Filtering

Filter documents using MongoDB query syntax:

diorama.show(reduced, documents,
             filter={"score": {"$gte": 4.0}, "city": "Sydney"})

diorama.show(reduced, documents,
             filter={"$or": [{"city": "Sydney"}, {"city": "Melbourne"}]})

diorama.show(reduced, documents,
             filter={"name": {"$regex": "^A"}})

Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or, $not, $nor.

3D

reduced_3d = diorama.reduce(embeddings, n_components=3)
diorama.show(reduced_3d, documents, color_by="category")

Dash app

Launch an interactive web UI with a field dropdown, filter text input, and 2D/3D toggle:

diorama.app(embeddings, documents, subsample=10_000)
# Opens at http://127.0.0.1:8050

Requires the dash extra: pip install diorama[dash].

Options

diorama.show(
    embeddings,
    documents,
    color_by="field.path",          # dot notation for nested fields
    filter={"age": {"$gt": 20}},    # MongoDB-style filter
    n_components=2,                  # 2 or 3
    method="umap",                   # "umap" or "tsne"
    subsample=10_000,                # fit on subset, transform all
    color_scheme="dark",             # "light" or "dark"
    height=800,                      # figure height in pixels
    show_progress=True,              # tqdm progress bar
    output_path="plot.html",         # save to file
)