xeSim

Learning biology through physics-based generative models of Xenium measurements.

xeSim fits a hybrid physics-based model combined with a neural net renderer for Xenium bundles. The model parameters and scene configuration are optimized to best explain the experimentally-observed data: re-rendering the bundle should produce something that looks very similar to the original measurement, but every pixel and molecule in that data is traceable back to its virtual cell source. By constraining the staining and molecular data by the physical model, such simulations aim to provide realistic-looking data where the ground truth is actually known.

Install

# 1. xeSim (this repo). All runtime dependencies are declared — pip
#    resolves them automatically.
git clone <this-repo-url> xeSim
cd xeSim
pip install -e .

# 2. cellAdmix-core (sister package — transcript NMF priors).
#    Built from C++ via scikit-build-core; needs a working CMake toolchain.
#    See cellAdmix-core/docs/install.md for system-dependency details.
git clone https://github.com/kharchenkolab/cellAdmix-core
python -m pip install -e cellAdmix-core/python --no-build-isolation

Skip cellAdmix-core only if you'll always pass --no-transcripts to fit-model (transcript-based features — per-gene compartments, per-cell-type negbin counts, factor-derived gene assignment — will then be unavailable).

A CUDA GPU is required for fit-model. Inference (explain) works on CPU but is much slower.

Quick start

# Fit (~30-60 min on an A100). cellAdmix (sister package, transcript NMF)
# is run automatically on the bundle. Pass --celladmix-run PATH to reuse
# an existing fit, or --no-transcripts to skip.
xesim fit-model PATH/TO/BUNDLE --annotations PATH/TO/cell_types.csv \
    --out my_model/

# Re-render the real bundle through the model. 2D is the default.
xesim explain PATH/TO/BUNDLE --model my_model/ --out explained/

# Opt in to the 3D z-stack (multi-z DAPI) output. NOTE: 2.5D is several
# times slower per tile than 2D (it renders a z-stack and re-synthesizes
# off-focus structure), so start with 2D and use 2.5D only when you need
# the volumetric morphology.
xesim explain PATH/TO/BUNDLE --model my_model/ --out explained_25d/ \
    --scene-mode 2.5d --whole-bundle

Outputs are written as standard Xenium bundles (image stack + cells.parquet + transcripts.parquet + ground_truth/).

Python API

from xesim import XesimModel
model = XesimModel.fit("path/to/bundle", "path/to/cell_types.csv",
                          out_dir="my_model/")
# or load: model = XesimModel.load("my_model/")
items = model.explain("path/to/bundle")

Inspection helpers

xesim inspect-bundle PATH/TO/BUNDLE
xesim inspect-model my_model/

Documentation

• docs/quickstart.md — installation + first run.
• docs/pancreas_vignette.md — end-to-end walkthrough on the public Xenium pancreas bundle: download, fit, render a tile, render the whole bundle.
• docs/model.md — what is modeled, pipeline schematic, 2D / 2.5D outputs, real-vs-rendered examples.
• docs/prior_estimation.md — 3D nucleus shape priors fit from 2D polygons via an ellipsoid observation model (consumed by the 2.5D scene mode).

Status

Pre-release. Reference fits exist for the Xenium pancreas membrane (377 genes) and Xenium breast 5K (8,456 targets) bundles. Cross-bundle fidelity tuning is ongoing.