MilliMap Documentation

MilliMap is an open-source desktop application for interactive spatial omics visualization and analysis. It provides a complete code-free workflow: load spatial transcriptomics data, explore tissues in 3D, run analyses, and export reproducible results.

Installation

Standalone App (Recommended)

Download the latest release for your platform from the GitHub Releases page. No Python installation required.

From Source

# Clone the repository
git clone https://github.com/milliomics/MilliMap.git
cd MilliMap

# Option 1: Conda (recommended)
conda env create -f setup/environment.yml
conda activate millimap

# Option 2: pip
pip install -r requirements.txt

# Launch
python src/millimap/main.py

Loading Data

MilliMap supports multiple ways to load spatial omics data. Use File → Open or drag and drop files directly into the application window.

Quick Start

1. Launch MilliMap. You'll see the welcome screen.
2. Click Load Spatial Data or drag an .h5ad file into the window.
3. For platform-specific outputs (Xenium, MERSCOPE, CosMx), select the experiment folder instead.
4. MilliMap auto-detects the format, loads spatial coordinates, and renders the tissue.

Automatic Detection

MilliMap inspects file extensions, headers, and folder structures to determine the data type. For most workflows you can simply point it at your data and it will do the right thing. Multi-section datasets are detected automatically from metadata fields like source, sample, batch, or fov.

Supported Formats

Workspace Navigator

The workspace navigator is the sidebar on the left side of the MilliMap window. It provides a persistent view of all loaded datasets and their analysis results.

Key Features

• Multi-dataset management — Load multiple datasets and switch between them by clicking the dataset header.
• Result cards — Every completed analysis appears as a card under its dataset. Double-click a card to open the full interactive result.
• Drag and drop — Drag result cards between datasets for comparative analysis, or into the center view for split-pane display.
• Session persistence — Results remain available across dataset switches. Close individual sessions via right-click.

Visualization

MilliMap renders spatial omics data as GPU-accelerated 3D point clouds using PyVista/VTK. Every cell is a point in space, colored by cluster identity, gene expression, or metadata.

View Modes

Display Controls

• Point size — Adjustable globally or per-view in split mode.
• Transparency — Fade non-selected cells to highlight regions of interest.
• Background color — Switch between dark and light backgrounds.
• Auto-scaling — Point size adjusts automatically as you zoom.
• Co-expression mode — Overlay two genes with independent red/green color channels.

Selection & ROI Tools

MilliMap provides multiple selection tools for defining cell populations directly on the tissue or embedding view. Selections can be saved as named Regions of Interest (ROIs) and used in downstream analyses.

Selection Methods

• Rectangle — Click and drag to draw a rectangular region on the spatial or embedding view.
• Lasso — Freeform polygon selection for irregular shapes.
• Cluster-based — Select all cells belonging to one or more clusters.
• 3D Volume — Extrude a 2D selection into a 3D volume, or connect multiple ROIs across tissue sections.

ROI Management

• Save selections as named ROIs that persist throughout the session.
• View ROI composition — cell-type breakdown for each region.
• Use ROIs directly in differential expression (ROI vs. ROI comparisons).
• Export ROIs as AnnData subsets or coordinate CSVs.
• Import/export ROI definitions from CSV files.

Color Schemes

MilliMap includes multiple color palette options for cluster visualization:

• Scanpy — Default categorical colors matching the Scanpy ecosystem.
• Plotly Extended D3 — Large categorical palette for datasets with many clusters.
• Custom Turbo — Continuous heatmap-style coloring.
• Seaborn — Statistical visualization palette.
• MilliOmics — Custom palette optimized for spatial omics.

Analysis Library

The Analysis Library is MilliMap's central hub for running analyses. It provides a visual card-based interface with 30+ analysis methods organized by category. Each card shows the method name, description, and which library it belongs to.

Categories

• Preprocessing — Normalize, log-transform, HVG selection
• Dimensionality Reduction — PCA, UMAP, t-SNE, Diffusion Map, Draw Graph, PAGA
• Clustering — Leiden, Louvain, Cell Cycle Scoring
• Differential Expression — Rank Genes, Pseudobulk DEG, Score Gene Sets, DEG Compare Groups
• Spatial Analysis — SVG, Neighborhood Enrichment, Co-occurrence, Centrality, Interaction Matrix, Ripley's, Ligand-Receptor, Expression by Distance
• Enrichment — GO Enrichment, GSEA
• Gene Visualization — Violin, Dot Plot, Heatmap, Stacked Violin
• Trajectory — Diffusion Pseudotime (DPT)
• Comparative — Sample Correlation, Embedding Density

Scope Selector

Every analysis in the library includes a scope selector that lets you choose which cells to include. You can run analyses on all data, specific sections, selected clusters, or named ROIs. This means you can compare spatial statistics across different tissue regions without writing any code.

Plot Controls

All result popups include a Plot Controls panel for customizing the appearance of figures: title, axis labels, font family, title/axis/tick font sizes, and (for heatmaps) colormap and colorbar label. Enable Live Preview to see changes in real-time, or click Apply to update.

Preprocessing & QC

Quality Control

MilliMap provides an interactive QC panel for filtering cells before analysis.

• Doublet detection — Scrublet-based doublet scoring with configurable expected doublet rate. View the doublet score distribution histogram before filtering.
• QC metrics — Filter by minimum/maximum genes per cell, total counts, and maximum mitochondrial percentage.
• Reset — Restore original unfiltered data at any time.

Normalization

Scanpy Normalize total counts per cell and apply log1p transformation. Available as a one-click operation from the Analysis Library.

Highly Variable Genes

Scanpy Select the most informative genes for downstream analysis (PCA, clustering, DEG). Configurable number of top genes.

Clustering

MilliMap supports graph-based clustering with a full automated pipeline or step-by-step manual control.

Pipeline

The one-click pipeline runs: PCA → (optional Harmony batch correction) → KNN graph → Leiden clustering → UMAP embedding. Configure each step's parameters before running or accept the defaults.

Algorithms

• Leiden Scanpy — Modern graph-based community detection. Resolution parameter controls granularity: lower values yield fewer, larger clusters.
• Louvain Scanpy — Classic modularity-based clustering. Available as an alternative to Leiden.

Advanced

• Sub-clustering — Select a subset of cells (via ROI or cluster selection) and re-cluster independently.
• Resolution search — Preview how different resolution values affect cluster count.
• Cell cycle scoring — Score cells for S and G2M phases to identify cycling populations.

Differential Expression

MilliMap provides a full differential expression suite accessible from the DEG tab or the Analysis Library.

Comparison Modes

• Cluster vs. Cluster — Compare any two clusters with Wilcoxon, t-test, or logistic regression.
• ROI vs. ROI — Compare cells in two saved spatial regions.
• Section vs. Section — Compare cells across tissue sections in multi-section datasets.
• Pseudobulk Scanpy — Aggregate expression by sample or condition for bulk-level DE.
• Marker genes — Find top markers per cluster using rank_genes_groups.

Result Visualization

• Volcano plot — Interactive scatter of log2FC vs. -log10(p-value). Click any gene to highlight its expression on the tissue.
• DEG heatmap — Top differentially expressed genes across clusters.
• Tissue highlighting — Click the "Highlight Top DEG on Tissue" button to color the spatial view by the most significant gene.
• Results browser — Tabular view of all DEG results with sorting and filtering. Click any row to visualize that gene.

Spatial Analysis

Squidpy MilliMap integrates the full Squidpy spatial statistics suite through the Analysis Library. All spatial analyses produce interactive results — click elements in the plots to highlight corresponding cells or regions on the tissue.

Spatially Variable Genes

Identify genes with significant spatial patterning using Moran's I (positive spatial autocorrelation) or Geary's C (spatial heterogeneity). Results appear as a sortable gene table. Click any gene to view its spatial expression pattern.

Neighborhood Enrichment

Permutation test for spatial co-localization preferences between cell types. Results are displayed as an interactive z-score heatmap. Click any cell in the heatmap to highlight that cluster pair on the tissue.

Co-occurrence

Compute pairwise co-occurrence probabilities between cell types at varying spatial distances. Produces line plots for each cluster pair showing co-occurrence ratio vs. distance. Click a curve or legend entry to highlight the corresponding pair.

Centrality Scores

Compute degree, closeness, and betweenness centrality per cluster from the spatial neighbor graph. Results appear as an interactive bar chart. Click any bar to highlight that cluster on the tissue. Use the dropdown to switch between centrality measures.

Interaction Matrix

Build and visualize the count (or normalized) matrix of spatial neighbor interactions between clusters. Displayed as a heatmap. Click a cell to highlight the interacting pair.

Ripley's Statistics

Test for spatial clustering, dispersion, or randomness per cluster using Ripley's K, L, or G functions. CSR (complete spatial randomness) simulation envelopes are shown for reference. Hover to read per-cluster values; click a curve or legend entry to highlight that cluster.

Ligand-Receptor Analysis

CellPhoneDB-style permutation test for significant ligand-receptor interactions between cell types. Results appear as a dot plot (dot size = mean expression, color = p-value). Click a dot to highlight the ligand's spatial expression and the interacting cluster pair. Adjustable p-value threshold via spinbox.

Expression by Distance

Plot mean gene expression as a function of distance from an anchor cell type. A draggable pink threshold line lets you interactively select cells within a distance cutoff and highlight them on the tissue. Click a gene in the legend to focus on it.

Enrichment Analysis

GO Enrichment

GSEApy Gene Ontology enrichment analysis using the Enrichr API. Input gene lists from the last DEG comparison, top markers per cluster, or a custom gene list. Supports multiple gene set libraries.

GSEA

GSEApy Gene Set Enrichment Analysis using ranked gene lists. Supports MSigDB, KEGG, Reactome, and other gene set libraries. Input ranked genes from DEG log2FC, DEG score, or rank_genes_groups.

Trajectory & Pseudotime

Diffusion Pseudotime (DPT)

Scanpy Order cells along developmental or differentiation trajectories. Requires a diffusion map embedding (computed from the Analysis Library). Results include an interactive pseudotime colorbar — drag the threshold to select and highlight cells with pseudotime below the cutoff.

PAGA

Scanpy Partition-based graph abstraction visualizes cluster-state transitions as a graph. Nodes are clusters, edges represent transition strength. Click a node to highlight that cluster on the spatial view.

Diffusion Map

Scanpy Non-linear dimensionality reduction based on Markov chain diffusion. Serves as the basis for DPT computation. Interactive embedding with clickable legend for cluster highlighting.

Gene Visualization

Scanpy MilliMap

Violin Plots

Visualize expression distributions across clusters. Click a cluster violin to highlight those cells on the spatial view and color them by expression. Ctrl+click to multi-select.

Dot Plot

Gene-by-cluster matrix where dot size indicates percentage of expressing cells and color indicates mean expression. Click a gene tick label to highlight its spatial expression.

Heatmap

Mean expression heatmap grouped by cluster for a set of genes. Click gene names to visualize their spatial patterns.

Stacked Violin

One violin per gene per cluster, stacked vertically. Compact view for comparing expression of multiple genes across clusters simultaneously.

Millini AI Assistant

MilliMap Millini is MilliMap's built-in AI assistant that translates natural-language biological questions into reproducible analysis operations. It uses function-calling to directly control MilliMap's analysis tools.

Capabilities

• Run clustering pipelines, differential expression, and gene set scoring through natural language.
• Query dataset metadata ("How many cells are in cluster 3?")
• Find marker genes and explore gene expression patterns.
• Run GO enrichment on recent DEG results.
• Apply QC filters and preprocessing steps.

Example Queries

• "Run PCA and Leiden clustering with resolution 0.8"
• "Show a violin plot for Ttn"
• "Which clusters express Slc17a7?"
• "Compare cluster 2 vs cluster 5 and run GO enrichment on the results"
• "Score cells by the gene set [Gfap, Aqp4, Aldh1l1]"

Setup

Millini supports OpenAI and Google Gemini as LLM backends. Enter your API key in the Millini settings panel. Chat history is maintained throughout the session.

Cell Annotation

MilliMap MilliMap includes a semi-automatic annotation system that scores clusters against known marker gene sets to suggest cell type identities.

How It Works

1. Provide a set of marker genes (with optional weights) for each cell type.
2. MilliMap scores each cluster on multiple metrics: mean expression, variance, percent expressing, and uniqueness.
3. A weighted multi-metric ranking assigns the best-matching cell type label to each cluster.
4. Review and adjust annotations interactively. Labels are saved in the AnnData metadata.

Batch Correction

MilliMap integrates Harmony for batch effect correction when combining data from multiple samples, experiments, or tissue sections.

• Automatic detection of batch metadata fields (source, sample, batch).
• Optional step in the clustering pipeline: PCA → Harmony → KNN → Leiden → UMAP.
• Toggle on or off via a checkbox in the clustering panel.

Multi-Dataset Analysis

MilliMap supports loading and analyzing multiple datasets simultaneously.

• Dataset switching — Click a dataset in the workspace navigator to make it active. All views and tools update to reflect the selected dataset.
• Result sharing — Drag result cards between datasets for side-by-side comparison.
• Sample Correlation — Compare per-gene mean expression between any two datasets, sections, or ROIs. Interactive scatter plot with Pearson and Spearman correlation coefficients.
• Independent sessions — Each dataset maintains its own analysis state, clusters, ROIs, and result history.

Export & Reproducibility

Jupyter Notebook Export

MilliMap MilliMap records every analysis operation during your session. When you're done, export the entire session as a reproducible Jupyter notebook containing executable Scanpy and Squidpy code cells with the exact parameters you used.

• Automatic session recording — no manual steps required.
• Preview and select which analyses to include before export.
• Generated notebooks include library imports, data loading, and markdown section headers.

Figure Export

• Export any result figure as PNG or PDF from the result popup.
• Publication-quality export rebuilds figures at higher DPI.

Data Export

• Export current AnnData (with clusters, QC, and annotations) to .h5ad.
• Export cell metadata (clusters, coordinates, QC metrics) to CSV.
• Export DEG results, analysis tables, and ROI subsets.

Morphology Overlay

MilliMap For platforms that provide morphology images (Xenium OME-TIFF), MilliMap can overlay high-resolution microscopy channels on top of the spatial point cloud.

• Multi-channel support — Toggle individual morphology channels (e.g., DAPI, membrane stains) on and off.
• Per-channel controls — Adjust opacity and LUT (lookup table) normalization for each channel independently.
• Lazy loading — OME-TIFF pyramids are read tile-by-tile; only the visible region is decompressed, keeping memory usage low for large images.