Embeddings and projection

Every Mantis map is the output of a three-stage pipeline: embed your data into high-dimensional vectors, reduce those vectors to exactly two coordinates, and cluster them into a labeled hierarchy. Understanding which stage did what tells you which patterns on the map are real and which are artifacts of the squeeze.

Embedding

An embedding is a list of numbers that stands for a piece of content, positioned so that things which mean similar things sit close together. Mantis builds one per row.

By default it does that from text. You mark one or more columns as semantic during space creation; those columns are concatenated per row and sent to an embedding service. Columns you mark as numeric, categorical or date are carried along as metadata and are available for coloring, filtering and analysis, but they do not move the point.

Embedding services

Two services are wired up:

Service	Default model
vllm-embeddings	Qwen/Qwen3-Embedding-8B, served from the lab cluster
openai-embeddings	text-embedding-3-small

Mantis prefers vLLM when the local service reports itself available and falls back to OpenAI when it does not. This is not usually a decision you make: the service selector only appears when Embedding Strategy is set to llm, and the one-step create path on the home dashboard hard-codes vLLM without asking.

Embedding strategies

The Embedding Strategy control is populated live from the backend registry. Four strategies are registered:

• llm is the default. Concatenate the semantic columns, embed the text.
• forward skips embedding and uses vectors you already have, either a coordinate pair or a vector column. This is how you bring your own layout.
• vae (also registered as probabilistic) trains a variational autoencoder, built for single-cell RNA-seq data.
• graph produces graph embeddings via a graph neural network.

Reduction

An embedding has hundreds or thousands of dimensions; a screen has two. The reduction stage projects the vectors down. The target is always two dimensions. There is no 3D map, and the 2.5D view mode is a rendering choice, not an extra data axis.

Six strategies are registered in the backend, and the create-space form fetches the live list rather than hard-coding it:

Strategy	What it does
UMAP	The default. Balances local neighborhoods against global shape.
PCA	Linear projection onto the top principal components.
PCA+UMAP	PCA down to a moderate dimension first, then UMAP to 2D.
TSNE	Emphasizes local structure; global distances mean little.
PARAMETRIC_UMAP	UMAP with a learned projection function.
GAUSSIAN_UMAP	2D coordinates plus a 3D uncertainty estimate per point.

The Refine tab of the Space Creation panel re-runs reduction on an existing map and exposes three of them with their parameters:

• UMAP: number of neighbors (higher preserves more global structure) and minimum distance (lower packs clusters tighter).
• t-SNE: perplexity, typically 5 to 50, and maximum iterations, at least 250.
• PCA: number of components.

WARNING

Reduction is lossy by construction. Two points can be adjacent on the map and distant in the embedding, or far apart on the map and near neighbors in the embedding. Use the Semantic Ruler, the Heatmap tool and the Localized Error panel to check, as described in Read the map.

Clustering

Clustering runs on the embeddings and produces a tree: each cluster has a parent, a depth, a center, a color and the points beneath it. Three methods are registered:

• KMeans, exposed in the Refine tab as Hierarchical Clustering, with a choice of linkage (ward, complete, average, single, weighted, centroid, median) and distance metric.
• HDBSCAN, density based, which decides the number of clusters itself.
• Leiden, community detection on the neighbor graph.

A Depth Detection strategy decides how deep the tree should go: fixed uses a set depth, sse and trustworthiness derive one from the data.

Cluster labels

Labels are generated, not taken from your data. For each cluster, a sample of its points is sent to a language model along with its parent's label and its children's labels, with instructions to be more specific than the parent and more general than the children. Shallow labels are therefore written to read as broader categories than the ones nested under them.

Labels are an interpretation of a sample. Treat them as a starting hypothesis about a region, then open the Reader, Summarizer or Keywords panel on the points themselves to confirm it.

Re-running the pipeline

Open View > Machine Learning > Space Creation and pick the Refine tab. It re-runs a single phase against an existing map, one at a time: Re-Embed, Dimensionality Reduction Phase, Clustering Phase, Cluster Labelling Phase, Point Re-titling Phase. Re-embedding on a different set of metadata columns and re-reducing is the fastest way to ask "what if the layout were about this instead".

Maps imported from an H5AD source are locked: their coordinates, cluster assignments, labels and colors come from the AnnData file, and you have to create a derived representation map before any of these phases will run.

Limits

• There is no minimum or maximum row count for a CSV space. The generic upload path only requires a header row plus at least one data row.
• Academic scraping refuses to build a space from fewer than 50 rows, and web search requires more than 51.
• The single-cell expression path needs at least three observations to run PCA or UMAP.
• GAUSSIAN_UMAP returns 2D coordinates plus an uncertainty triple; the map still plots the two coordinates.

Read nextRead the mapWhat the resulting points, clusters and boundaries actually mean.