NICHEVERSE#

A world model for tissues

Every cell and niche mapped to an interpretable codebook.

Explore the atlas Get started
381
samples
102
datasets
39M
cells mapped
20
tissues
6
platforms
A clear cell renal cell carcinoma primary tumor core read into cell-state lineages
A whole mouse pup with every cell painted by its learned cell-state code
Interpretable by construction

A discrete code for every cell and niche.

Each cell is quantized to one of 256 learned cell states and each neighborhood to one of 32 spatial niches, coupled by cross-attention so identity is always read in tissue context. The same discrete vocabulary transfers, unchanged, from one cohort and platform to the next.

256 cell-state codes 32 niche codes cross-attention coupled
Recovered, not supervised

An interpretable vocabulary of cell states.

Correlating the learned code embeddings blocks them into coherent lineages with no labels supplied, epithelium, stroma, endothelium, and the immune compartment separate on their own. Each code carries a stable expression signature you can read, name, and compare across tissues.

Hierarchically clustered correlation of the 256 cell-state codes, colored by dominant cell type

Explore the atlases mapped in the nicheverse

Read across 381 independent samples from 102 datasets and every accessible platform, Xenium, CosMx, MERFISH, seqFISH, RIBOmap, EEL-FISH. Every cell is painted by the lineage of the cell-state code the model assigns it.

Browse all samples

NICHEVERSE

Neighborhood-Inferred Cell type HiErarchical annotation + VEctor-quantized Representations of Spatial Ecotypes

The released NICHEVERSE checkpoint, frozen and never retrained, learns paired discrete codebooks of recurrent cell states and multicellular spatial niches from imaging-based spatial transcriptomics, and reads any cohort reproducibly.

Hierarchical codebooks

Paired cell-state and spatial-niche codebooks coupled by cross-attention, so cell identity is read in tissue context.

Swappable components

Encoder registry: mlp_deep (default), mlp, mlp_plr, residual_mlp, transformer, cnn, fast_cnn, deep_cnn, gnn, diffusion, dit, set_transformer, perceiver_io, soft_moe, ft_transformer. Quantizer registry: vq (default), rvq, grvq, pq, qinco, rot, soft, bsq, lfq, fsq, residual_fsq.

Spatial-aware

Per-sample graphs (knn, knn_radius, radius, delaunay, alpha_complex, gabriel, rng), inverse-distance aggregation, and opt-in spatial-coherence losses.

Reproducible

Byte-exact reproduction of the published renal cell carcinoma and brain-metastasis model, guarded by a regression test.

PyTorch-native

A Trainer, checkpoints, mixed precision, warmup-cosine scheduling, and MAE pretraining.

Install

pip install nicheverse       # or: conda install -c conda-forge nicheverse

Quickstart

import nicheverse as nv

adata = nv.read_xenium_cohort(["./run_A", "./run_B"])
mc = nv.ModelConfig(input_dim=adata.n_vars, gene_names=tuple(adata.var_names))
model, adata = nv.Trainer(nv.TrainConfig(num_epochs=300)).fit(adata, "./ckpt", model_config=mc)

annotated = nv.predict_codes(
    nv.read_xenium_cohort(["./run_C"]), "./ckpt/hierarchical_vqvae_checkpoint.pt"
)