STPuppeteer

STPuppeteer generates synthetic spatial transcriptomics datasets with ground-truth cell annotations, transcript locations, and expression profiles. Let spatial transcriptomics data be the puppets that you can design, update and play around. Given the complexity and noisy nature of real spatial transcriptomics data, STPuppeteer opts for a clean, flexible and interpretable design to generate synthetic dataset. With tangible ground truth in hand, the package can be used to benchmark and stress-test deconvolution, cell segmentation, and transcript-to-cell assignment methods.

---

How it works

The simulator builds a synthetic tissue section in four stages:

SimulationConfig
      │  (ProgramSpec · CellTypeSpec · MorphologySpec)
      ▼
1. Gene Parameters     — build gene loading matrix W from ProgramSpec loadings;
                          derive μ* per gene per cell type via LMC (W · activations);
                          sample overdispersion θ from a power-law model
      │
      ▼
2. Cell Geometry       — place nuclei via Poisson-disk sampling,
                          grow log-normal polygons, tile boundaries with Voronoi;
                          optional PrototypeSpec / PrototypeScene for structured regions
      │
      ▼
3. Count Matrix        — draw transcript counts from NegBinom(μ·scale, θ)
                          per cell per gene
      │
      ▼
4. Transcript Locations — place each transcript inside its cell polygon;
                           a configurable fraction leaks outside (leakage model)

Key design choices:

• Program-based (LMC) gene model — gene expression is a linear mixture of latent programs; each ProgramSpec defines a sparse loading vector over genes
• Cell-type programs and variability specified per CellTypeSpec via program_activations and program_variability
• Per-cell size scaling so larger cells receive more transcripts proportionally
• Per-cell-type and per-gene leakage probabilities for realistic cross-boundary contamination
• Optional prototype insertion (PrototypeSpec / PrototypeScene) for structured tissue architectures
• Shapely 2.x vector geometry throughout — no rasterisation

---

Installation

First, clone the repo

git clone git@github.com:Jieran-S/STpuppeteer.git

Then create a working environment from the recipe file in the repo

cd STpuppeteer
conda env create -f environment.yml
conda activate STpuppeteer

To write output in SpatialData-compatible format, install spatialdata additionally:

pip install spatialdata

---

Quickstart

from STpuppeteer.simulation import SpotlessSimulator, default_program_config

# Build a default config: 3 cell types, gene programs, housekeeping genes
config = default_program_config(
    n_cells=300,
    n_celltype=3,
    n_genes_per_program=20,
    n_hk_genes=30,
    seed=42,
)
# Equivalent: SimulationConfig.from_defaults(...)

sim = SpotlessSimulator(config)
sim.run_full_simulation()

print(sim.cell_gdf.shape)      # (n_cells, ...)  — geometry + metadata
print(sim.count_array.shape)   # (n_cells, n_genes)
print(sim.trs_df.shape)        # (n_transcripts, ...)

sim.save_simple("output/")          # CSV, Parquet, NPY
sim.save_spatialdata("output.zarr") # SpatialData/Zarr

Step-by-step equivalent:

sim2 = SpotlessSimulator(config)
sim2.generate_gene_parameters()       # → sim2.gpar_df
sim2.initialize_cells()               # → sim2.cell_gdf
sim2.simulate_counts()                # → sim2.count_array
sim2.simulate_transcript_locations()  # → sim2.trs_df

---

Tutorials

Tutorial	Description
Quick Start	Run a complete simulation in under a minute; covers all four pipeline steps and the step-by-step API
Step 1 — Gene Expression Parameters	Program-based (LMC) gene model, ProgramSpec / CellTypeSpec / GeneSpec, loading matrices, and overdispersion
Step 2 — Cell Generation	Nucleus placement, MorphologySpec, Voronoi expansion, and prototype insertion
Step 3 — Simulate Counts	Negative-Binomial count model, count matrix overview, and effect of key parameters
Step 4 — Simulate Transcripts	Spatial transcript placement, leakage model, and parameter scan
Configuration Reference	Field-by-field reference for SimulationConfig: spatial, morphology, program, dispersion, leakage, and depth parameters