Metadata-Version: 2.5
Name: viva-tumor-tcell
Version: 0.1.3
Summary: Process-bigraph port of the tumor-tcell tumor-microenvironment ABM (viva-munk physics)
Project-URL: Homepage, https://github.com/vivarium-collective/viva-tumor-tcell
Project-URL: Issues, https://github.com/vivarium-collective/viva-tumor-tcell/issues
Author-email: Eran Agmon <agmon.eran@gmail.com>
License: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Requires-Dist: bigraph-schema>=0.0.60
Requires-Dist: numpy
Requires-Dist: plotly
Requires-Dist: process-bigraph
Requires-Dist: scipy
Requires-Dist: viva-munk
Provides-Extra: dev
Requires-Dist: matplotlib; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# viva-tumor-tcell

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Read-only dashboard](https://img.shields.io/badge/dashboard-live-3b6fb6.svg)](https://vivarium-collective.github.io/viva-tumor-tcell/dashboard/)
[![Cell Systems 2024](https://img.shields.io/badge/paper-Cell%20Systems%202024-e8710a.svg)](https://doi.org/10.1016/j.cels.2024.03.004)
[![process-bigraph](https://img.shields.io/badge/built%20on-process--bigraph-6f42c1.svg)](https://github.com/vivarium-collective/process-bigraph)

A [process-bigraph](https://github.com/vivarium-collective/process-bigraph) port of
[tumor-tcell](https://github.com/vivarium-collective/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](https://github.com/vivarium-collective/viva-munk)'s `pymunk` engine.

<!-- BEGIN:dashboard -->
<!-- generated by `vivarium-workbench gen-readme` — edit the source, not this table -->

> ### 🔬 [Explore the interactive read-only dashboard →](https://vivarium-collective.github.io/viva-tumor-tcell/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).
<!-- END:dashboard -->

## 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](https://doi.org/10.1016/j.cels.2024.03.004)

## What it reproduces

The **[tumor-tcell-showcase investigation](investigations/tumor-tcell-showcase/)**
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.

| Study | Paper analogue | Result |
|---|---|---|
| **tumor-microenvironment** | Fig 3 headline experiment | Full figure suite for the 3 CODEX conditions (no-T / 25% / 75% PD1+) |
| **efficacy-at-scale** | Fig 3E | 25% PD1+ suppresses growth more than 75% PD1+ in **3/3 seeds** (285±15 vs 335±11 vs 315±24 no-T) |
| **phenotype-conversion** | Fig 3G | Active T cells secrete a measurable IFNg field in **6/6** seeds (0/6 without) |
| **tcell-exhaustion** | Fig 3H | Exhausted (PD1+) fraction tracks the starting fraction: **63±22%** (75% start) vs **16±11%** (25% start), 6/6 |
| **killing-assay-cytotoxicity** | Fig 2C/2G | cytotoxicity **~11±8%** vs matched no-T control (positive in 5/6 seeds) |

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](https://github.com/vivarium-collective/viva-munk)
checkout. [`uv`](https://github.com/astral-sh/uv) is recommended.

```bash
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

```python
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/`):

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

<!-- BEGIN:composites -->
<!-- generated by `vivarium-workbench gen-readme` — edit the source, not this table -->

| Composite | What it is |
|---|---|
| `killing_assay` | Well-mixed in-vitro cytotoxicity assay: tumor cells at a chosen PDL1+ fraction, with or without T cells (matched no-T control). |
| `lymph_node` | Tumor microenvironment plus dendritic cells and a diffusing tumor_debris field — DCs take up debris and activate. |
| `tumor_microenvironment` | CODEX layout: a central tumor mass ringed by T cells over a diffusing IFNg field. pd1_positive_frac + n_tcells select the no-T / 25% PD1+ / 75% PD1+ headline conditions. |
| `tumor_tcell_basic` | Small well-mixed chamber of tumor + T cells sharing a diffusing IFNg field; collisions via viva-munk (M1 core-seam demo). |
<!-- END:composites -->

<!-- BEGIN:investigations -->
<!-- generated by `vivarium-workbench gen-readme` — edit the source, not this table -->

| Investigation | Research question |
|---|---|
| [Tumor–T-cell Microenvironment (Vivarium 1.0 → 2.0 migration) _(running)_](https://vivarium-collective.github.io/viva-tumor-tcell/investigations/tumor-tcell-showcase.html) | Does migrating the tumor-tcell agent-based model from Vivarium 1.0 to process-bigraph (Vivarium 2.0) reproduce the paper's mechanism, and which parts of that mechanism hold robustly at a tractable sc… |
<!-- END:investigations -->

## 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](PORT_PLAN.md) for the full architecture, decisions, and the pbg gotchas hit.

## Testing

```bash
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](https://doi.org/10.1016/j.cels.2024.03.004)); see
[`references/papers.bib`](references/papers.bib).

## License

MIT — see [LICENSE](LICENSE).
