InSituGame: In Situ Spatial Evolutionary Game Assay

Author & Principal Investigator: Luca Celebrano
Affiliation: Department of Clinical Medicine and Surgery, School of Medicine, Università degli Studi di Napoli Federico II, Naples, Italy
Publication Status: Submitted to Cancer Research Communications (AACR MS# CRC-26-0804, Initial QC Passed & Under Editorial Consideration) · Bioconda Package: conda install -c bioconda insitugame · Permanent Archival DOI: 10.5281/zenodo.23585216 · Community Recognition: Listed in Awesome Single-Cell
Live Interactive Portal: https://lukecele.github.io/spatial-game-assay/

Tip

⭐️ Support Open-Source Theoretical Biology:
If you find this spatial evolutionary game assay or our in situ payoff inference engine helpful in your research, please consider giving this repository a Star on GitHub!

---

Overview

InSituGame is a clinical-computational biology assay designed to infer subclonal evolutionary game payoff matrices ($A$), compute exact Nash equilibria, and design personalized adaptive therapy protocols directly from intact human tumor biopsies using spatial transcriptomics (10x Genomics Visium and CytAssist FFPE).

Unlike traditional mathematical oncology models that rely on arbitrary parameter guesses or non-physiological 2D in vitro Petri dishes, InSituGame:

1. Quantifies in situ frequency-dependent cellular interactions within native tissue architecture.
2. Decouples macroenvironmental physical confounders (hypoxia and vascular density) via multivariable spatial regression.
3. Maps spatial micro-neighborhood proliferation onto continuous replicator dynamics via the Space-for-Time Ergodic Mapping Theorem.
4. Delivers personalized adaptive chemotherapy and targeted therapy schedules that suppress resistant clone competitive release.

flowchart TD
    Biopsy["Intact Human Biopsy<br>(10x Visium / CytAssist)"] --> Deconv["Cellular & Phenotype Deconvolution<br>(Sensitive vs Resistant Clones)"]
    Deconv --> Filter["Microenvironmental Spatial Filter<br>(Hypoxia CA9 & Vascular PECAM1)"]
    Filter --> Matrix["Purified Subclonal Payoff Matrix A<br>(Frequency-Dependent Interactions)"]
    Matrix --> Nash["Exact Nash Equilibria & Replicator Dynamics<br>(Space-for-Time Ergodic Mapping)"]
    Nash --> Therapy["Personalized Adaptive Therapy Protocol<br>(Extends Progression-Free Survival)"]
    
    style Biopsy fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    style Deconv fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    style Filter fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Matrix fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    style Nash fill:#ede7f6,stroke:#512da8,stroke-width:2px
    style Therapy fill:#e0f2f1,stroke:#00796b,stroke-width:2px

Loading

---

Key Scientific Findings & Benchmarking

• Human Breast Invasive Ductal Carcinoma ($N = 4,992$ spots):
  • Empirically discovered Hawk-Dove / Snowdrift (Coexistence) dynamics ($\tilde{A}{SS}=-0.736, \tilde{A}{SR}=+2.866, \tilde{A}{RS}=+2.188, \tilde{A}{RR}=-1.772$).
  • Stable internal coexistence equilibrium at $x^* = 61.3%$ sensitive clones (95% bootstrap CI: [52.6%, 72.5%]).
  • Independent Ground-Truth Concordance: Replicates the in vitro co-culture findings of Kaznatcheev et al. (Nature Ecology & Evolution 2019, 3:450-456) directly in situ.
• Human Lung Squamous Cell Carcinoma ($N = 3,858$ spots):
  • Indeterminate / Regional Composition — incremental game test non-significant ($F = 1.30$, $p = 0.266$); bootstrap CI for $\tilde{\Delta}_R$ spans zero. Spatial proliferation predominantly governed by regional subclonal composition rather than frequency-dependent interactions.
• Human Cutaneous Malignant Melanoma ($N = 3,458$ spots):
  • Suggestive Stag Hunt (Bistability) — point estimate tipping separatrix $x_{sep} = 48.1%$; bootstrap CI for $\tilde{\Delta}_R$ spans zero ($[-0.97, +3.57]$), Bayesian MCMC (50k Gibbs draws) confirms $P(\text{Stag Hunt} \mid \text{Data}) = 99.874%$.
• Technical & Biological Replicate Concordance ($\approx 10,\mu\text{m}$ Serial Cuts):
  • Payoff matrix Pearson correlation: $r = +0.811$ ($p = 0.0079$).
  • Replicated Stag Hunt classification on both independent consecutive slices.
  • Blind Out-Of-Sample (OOS) Generalization: $R^2_{OOS} = 10.20%$ (Fisher exact $p = 4.82 \times 10^{-12}$, DOR $= 2.30$ [95% CI: $2.03 - 2.61$]).

---

📊 Empirical Findings & Visual Proof

1. Spatial Game Decomposition & Tissue Deconvolution

2. Pan-Cancer Spatial Game Atlas (Breast, Lung & Melanoma)

3. Replicator Dynamics & In Silico Adaptive Scheduling

---

🔗 The Spatial Oncology Research Continuum

This project constitutes the foundational game-theoretic cornerstone of a 4-part open-source scientific investigation:

1. Study 1: InSituGame (This Repository) • Evolutionary game assay inferring subclonal payoff matrices in situ • DOI: 10.5281/zenodo.23585216
2. Study 2: Spatial Architecture & Biophysics • 10x Visium HD subcellular architecture & $\lambda \approx 624,\mu\text{m}$ transport barrier • DOI: 10.5281/zenodo.23620878
3. Study 3: Massive Validation ($N = 854$) • Multi-center population clinical survival validation ($p < 10^{-15}$, $HR = 19.45$) • DOI: 10.5281/zenodo.23620887
4. Study 4: InSituVision-AI (< 5 €) • Attention-MIL predicting microvascular decoupling and PFS directly from routine H&E slides • DOI: 10.5281/zenodo.23621924

---

Installation

git clone https://github.com/Lukecele/spatial-game-assay.git
cd spatial-game-assay
pip install -e .

# Run instant quickstart verification
./quickstart.sh

---

5-Line Quickstart

import numpy as np
from insitugame import InSituGameAssay

# 1. Define subclonal gene markers
gene_spec = {
    "T_S": ["EPCAM", "CDH1", "ESR1"],
    "T_R": ["VIM", "CDH2", "AXL"],
    "S_CAF": ["ACTA2", "COL1A1", "FAP"],
    "FITNESS": ["MKI67", "PCNA", "TOP2A"],
    "HYPOXIA": ["HIF1A", "VEGFA", "CA9"],
    "VASCULAR": ["PECAM1", "VWF"]
}

# 2. Initialize and fit assay on spatial biopsy data
assay = InSituGameAssay(gene_spec)
assay.fit(coords=coords, raw_counts=raw_counts, total_umi=total_umi)

# 3. Inspect inferred game matrix and Nash equilibria
print(assay.summary())

Command-line interface

The insitugame command accepts a delimited spot-by-gene table and performs the same fit as the Python API:

insitugame --input expression.tsv --output-prefix sample

The table must contain at least three spots and numeric expression columns. x/y (or row/col) columns are used as coordinates when present; otherwise a deterministic grid is generated. Marker columns can be named T_S, T_R, S_CAF, FITNESS, HYPOXIA, and VASCULAR (aliases Sensitive, Resistant, Stroma, Fitness, Hypoxia, and Vascular are also accepted). The command writes <prefix>_results.json with the fitted payoff matrix, Nash classification, and diagnostics, plus <prefix>_tables.csv containing the 3x3 payoff matrix.

---

Data Access & Reproducibility

To ensure both immediate verification and full provenance:

1. Instant Offline Cache: The repository bundles data/cache/clinical_pan_cancer_cache.npz (713 KB), containing the exact normalized gene expression matrices and spot coordinates for all 20,093 clinical spots. All tests and primary analyses run immediately without network access.
2. End-to-End Raw 10x Datasets (~5 GB): To download and unpack the full raw FASTQ/BAM/MTX archives from official 10x Genomics servers:

   python src/download_data.py        # Human Lung SCC (CytAssist FFPE)
   python src/download_cohort.py      # Human Breast IDC & Cutaneous Melanoma (CytAssist FFPE)
   python src/download_replicates.py  # Consecutive serial sections 1 & 2 (Visium Block A)

---

Citation & Authorship

If you utilize this methodology, assay software, or empirical matrices in your research or clinical trials, please cite the official specification via CITATION.cff:

@software{Celebrano_InSituGame_2026,
  author = {Celebrano, Luca},
  title = {{InSituGame: In Situ Spatial Evolutionary Game Assay for Inferring Tumor Subclonal Payoff Matrices and Guiding Adaptive Therapy}},
  year = {2026},
  url = {https://github.com/Lukecele/spatial-game-assay},
  version = {1.0.5},
  institution = {School of Medicine and Surgery, Università degli Studi di Napoli Federico II}
}

---

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).
Under this copyleft license:

• Academic institutions, public hospitals, clinicians, and researchers are free to run, inspect, and apply this software for patient care and scientific investigation at zero cost.
• Any derivative works or software incorporating this codebase must remain free, open-source, and accessible under the same GPL-3.0 license, preventing closed commercial monopolies.