viva-tumor-tcell

A process-bigraph port of tumor-tcell — the multiscale agent-based model of the tumor microenvironment from Hickey, Agmon et al., Cell Systems (2024) — as a viva- workspace. The tumor, T-cell, and dendritic-cell biology, the diffusing IFNg / tumor-debris fields, and the cell–cell neighbor exchange are ported faithfully from the original vivarium-1.0 processes; cell–cell collisions and neighbor detection are delegated to viva-munk's pymunk engine.

🔬 Explore the interactive read-only dashboard →

Every composite, study, and result — browsable in your browser, no install required. Published from main by the publish-dashboard workflow (allow a few minutes after the first push).

The science

The paper's central, counter-intuitive finding is that therapeutic T-cell efficacy is governed by the rate of IFNg-driven tumor phenotype conversion — proliferative PDL1n / MHC-I-low tumor cells converting to an arrested, inflammatory PDL1p / MHC-I-high state (G0, non-dividing) — and not by the raw number of T-cell kills. T cells that start more active (25% PD1+, from ex-vivo memory-skewing) drive that conversion earlier and more strongly than exhausted ones (75% PD1+): in the paper's model the tumor is held to ~1,000 cells vs ~3,000 (75% PD1+) vs ~5,000 (no T) at 60 h, even though the two T-cell conditions produce a nearly identical kill count (~1,300 vs ~1,200 deaths). Repeated TCR stimulation exhausts the T cells (PD1- → PD1+), lowering their cytokine output, and spatial reprogramming can preserve the active phenotype for continual conversion.

Hickey, Agmon, Horowitz, Tan, Lamore, Sunwoo, Covert, Nolan. Integrating multiplexed imaging and multiscale modeling identifies tumor phenotype conversion as a critical component of therapeutic T cell efficacy. Cell Systems 15, 322–338 (2024). doi:10.1016/j.cels.2024.03.004

What it reproduces

The tumor-tcell-showcase investigation reconstructs the paper's mechanism and reports every study across replicate seeds (mean ± std). Each study emits the original's analysis figures — population-by-state, cumulative divisions (via phylogeny), deaths-by-type, an 8-panel spatial snapshot montage, an animation + GIF, and cytotoxicity — using the paper's cell-state colors (PDL1n=indianred, PDL1p=skyblue, PD1n=darkorange, PD1p=limegreen) over the YlOrBr IFNg field.

Effects are directional at tractable scale; the population-level efficacy claim resolves when scaled up (see efficacy-at-scale), and the paper's full 1,200-cell / 3-day run is a follow-on (scripts/scale_efficacy.py).

Installation

Requires the sibling viva-munk checkout. uv is recommended.

uv venv .venv && source .venv/bin/activate
uv pip install -e .          # + the sibling viva-munk / viva-superpowers checkouts
pytest                       # 17 tests

Processes register automatically via bigraph_schema.package.discover once installed; viva_tumor_tcell.core.build_core() also registers viva-munk's pymunk_agent types, the set_float type, and this workspace's own processes.

Quick start

from viva_tumor_tcell.core import build_core
from viva_tumor_tcell.composites.microenvironment import tumor_microenvironment_document
from viva_tumor_tcell.run import analysis_run
from process_bigraph import Composite

core = build_core()
doc = tumor_microenvironment_document(n_tumors=60, n_tcells=12, pd1_positive_frac=0.25)
sim = Composite({'state': doc}, core=core)
a = analysis_run(sim, 300)          # per-state populations, deaths-by-type, divisions, snapshots
print(a['populations'][-1])

Run a showcase study (prints its verdict, writes figures to viz/ and reports/figures/):

python studies/tumor-microenvironment/sims/run.py

Architecture

tumor-tcell's Neighbors process did two jobs — pymunk collisions and the biological neighbor exchange. viva-munk's PymunkProcess covers only the collisions, so those are split: TumorTcellPhysics wraps a real viva_munk PymunkProcess as its collision engine (walls, jitter, substeps, circle–circle collisions) and also performs the ported ligand / cytotoxic-packet exchange (T-cell picks nearest tumor; tumor collects all T-cells).

Processes (viva_tumor_tcell/processes/)

• TumorCellProcess — PDL1n ↔ PDL1p; IFNg internalization drives the switch; death by apoptosis or accumulated cytotoxic packets (releases tumor_debris).
• TCellProcess — PD1n ↔ PD1p; TCR timer / refractory cycling; IFNg + cytotoxic-packet secretion in contact; persistent-random-walk migration.
• DendriticCellProcess — takes up tumor_debris, activates, presents MHCI/PDL1.
• DiffusionField — tumor-tcell's Fields + LocalField consolidated: deposit exchange → diffuse → decay → sample local, with the original diffusion/decay constants.
• TumorTcellPhysics — viva-munk collisions + neighbor exchange.

The tumor_tcell_agent type (types.py)

Each cell is a flat agent pinned to an explicit per-field schema: float accumulators (timers, counts, internalized IFNg) and viva-munk's set_float for membrane ligands (present/accept) and migration speed; map[float]/map[set_float] for exchange/local. Per-cell behavior processes are embedded and realized after _add/_remove division.

Visualizations (viz.py)

Interactive Plotly (population/division/death/cytotoxicity, animated spatial view) plus a matplotlib GIF, all in the paper's TAG_COLORS over the YlOrBr field.

See PORT_PLAN.md for the full architecture, decisions, and the pbg gotchas hit.

Testing

pytest -q          # 17 tests: process mechanics, neighbor exchange, IFNg switch, killing,
                   # field, dendritic activation, all-generator build/step, integration

Dependencies

process-bigraph, bigraph-schema, viva-munk (physics + pymunk_agent), numpy, scipy, plotly, matplotlib. The workbench (studies + read-only dashboard) additionally uses vivarium-workbench and viva-superpowers.

Citation

If you use this workspace, please cite the original paper (doi:10.1016/j.cels.2024.03.004); see references/papers.bib.

License

MIT — see LICENSE.