spatialbrowser

Interactive two-panel browser to annotate spatial transcriptomics (.h5ad) data — Dash + Datashader.

Overview

• Two independent panels — One panel can showcase genes, with labels or spatial coordinates in another. Can also be used for comparing annotations side by side. Each shows UMAP + spatial, with samples tiled into a grid so sections don't overlap.
• Any obs column or gene is selectable, and categorical vs continuous is auto-detected (coolwarm for continuous; a red-on-grey scheme for QC/doublet flags).
• Isolate one category per panel to see just those cells.
• DEG tables for multiple levels of annotations precompute markers for any grouping columns (main compartment, broad annotations, granular annotations, or whatever you use), then switch grouping and cluster in the app to see ranked markers (logFC, p-adj, pct in/out).

Install

pip install git+https://github.com/<you-or-lab>/spatialbrowser.git
# or, from a clone:
pip install -e .

Usage

1. Precompute DEGs (once; ranking genes on the browser is too slow for an interactive app, so we cache them). 'Groupings' refers to the .obs carrying leiden or annotations (in this case, Broad, Middle, Granular):

spatialbrowser-degs --in tissue.h5ad \
    --groupings Broad Middle Granular --outdir results

This writes results/deg_Broad.csv, deg_Middle.csv, deg_Granular.csv — one per grouping you name. Use any obs columns you like.

2. Launch the browser:

spatialbrowser --in tissue.h5ad --deg-dir results --port 8050

Then open http://127.0.0.1:8050 .

Options

• --host — 127.0.0.1 (default, local only, safe) or 0.0.0.0 (reachable from other machines; use only behind a firewall / SSH tunnel).
• --umap-key / --spatial-key / --sample-key — obsm/obs keys if yours differ from X_umap / X_spatial / sample_id.
• --title — heading shown in the app.

Running on an HPC

Launch on the compute/login node with --host 0.0.0.0, then SSH-tunnel the port to your laptop:

ssh -L 8050:<node>:8050 you@hpc      # then open http://127.0.0.1:8050 locally

Notes

• The DEG CSVs use columns: cluster, rank, gene, logFC, pval_adj, score, pct_in, pct_out. compute_degs writes exactly this; if you supply your own CSVs, match that schema and name them deg_<grouping>.csv.
• Works with your own annotations or reference predictions — it just reads whatever obs columns are present.