Non-executable

Tumor/T cell Microenvironment ABM

John Hickey + 1 other

v0.0.1MITOct 2026

Citation: Integrating Multiplexed Imaging and Multiscale Modeling Identifies Tumor Phenotype Transformation as a Critical Component of Therapeutic T Cell Efficacy

The model represents tumor cells, T cells, and related processes in a spatial microenvironment, including intracellular and intercellular interactions, soluble factors, cell movement, molecular fields, proliferation, phenotype changes, and cytotoxic killing. It is implemented on the Vivarium framework and can be initialized with multiplexed imaging datasets.

molecular cellular tissue

How this model is classified mathematically and dynamically.

Model class: agent-based model multi-scale model
Formalism: stochastic
Determinism: Stochastic
Time dynamics: Discrete
Spatial: 2D
Multiscale: Yes

Organisms, entities and processes this model represents.

Organisms: Not recorded
Infectious agents: Not recorded
Health conditions: Not recorded
Biological processes: chemotaxis immune response cell proliferation apoptosis
Molecular entities: Not recorded
Proteins / genes: IFNg PD1, PDL1, TCR, MHCI

The data this model consumes and produces when executed.

Parameters

Name	Default	Unit	Meaning
n_tumors	30	Not recorded	tumor cell count
n_tcells	30	Not recorded	T cell count
n_dendritic	0	Not recorded	dendritic cell count
time_step	60	second	Vivarium process time step in seconds.
total_time	60000	second	Total simulation duration in seconds.
bounds	`[200,200]`	micrometer	Two-dimensional environment bounds in micrometers.
n_bins	`[20,20]`	Not recorded	Number of spatial bins in x and y.
tumors_state_PDL1n	0.5	dimensionless probability	Initial probability that tumor cells are PDL1-negative.
tcells_total_PD1n	9	Not recorded	Number of initially PD1-negative T cells when explicit count initialization is used.
emit_step	600	second	Interval between emitted simulation states in seconds.

Initial conditions

Name	Value	Unit
initial_tumor_and_tcell_state	Generated by get_tumors() and get_tcells(), with optional explicit tumors/tcells dictionaries.	Not recorded

Data inputs

Name	Format	Required	Purpose
2HCTcell_exp_1of4.csv	CSV	Optional	Multiplexed imaging / experimental initialization or analysis data.
Cntrl_exp_1of4.csv	CSV	Optional	Control experimental data.
Tcell_exp_1of4.csv	CSV	Optional	T-cell experimental data.

Outputs

Name	Quantity	Unit	Format
simulation timeseries	simulation data	second	Not recorded
process and composite plots	simulation data	Not recorded	PNG

Experiment protocol

A typical run advances a spatial two-dimensional Vivarium composite at fixed 60-second steps, emits every 600 seconds, and can run for 60000 seconds; the repository also defines a large three-day experiment.

Timestep: 60 second
Duration: 60000 second
Observables: agent trajectoriescell_stateIFNgcytotoxic_packetscell deathtumor debris

Runtime environment, dependencies, and compute requirements.

Language: Python 3.8.5
Environment: pip

Vivarium provides fixed-step Engine execution. The primary experiment uses timeseries emission by default; database emission requires MongoDB. The repository also contains Jupyter notebooks for tutorial, diagram, killing, analysis, and local experiment workflows.

Compute requirements

GPU: Not required
Parallelism: multi-process

Dependencies

runtime: vivarium-core ==1.6.0
vivarium-multibody ==0.0.12
tqdm
opencv-python
pymunk
pandas
seaborn
numpy
scipy
system: MongoDB

Entry points

python tumor_tcell/experiments/main.py
Run experiment workflows for tumor/T-cell interactions
-w
Workflow identifier
python tumor_tcell/processes/t_cell.py
Run T-cell process single, batch, or timeline demonstrations
--single
--batch
--timeline
python tumor_tcell/processes/tumor.py
Run tumor-cell process single, batch, or timeline demonstrations
--single
--batch
--timeline
python tumor_tcell/processes/dendritic_cell.py
Run dendritic-cell process demonstration
python tumor_tcell/processes/fields.py
Run molecular-field decay and diffusion demonstrations
python tumor_tcell/processes/local_field.py
Run the local-field process demonstration
python tumor_tcell/processes/lymph_node.py
Run the lymph-node process demonstration
python tumor_tcell/processes/neighbors.py
Run the neighbors process demonstration
python tumor_tcell/composites/t_cell_agent.py
Run the integrated T-cell agent composite
python tumor_tcell/composites/tumor_agent.py
Run the integrated tumor agent composite
python tumor_tcell/composites/dendritic_agent.py
Run the integrated dendritic agent composite
python tumor_tcell/composites/tumor_microenvironment.py
Run the 2D tumor microenvironment composite
python tumor_tcell/experiments/killing_experiments.py
Run in-vitro killing experiments
python tumor_tcell/experiments/analyze.py
Access and analyze data from the database emitter
python tumor_tcell/library/get_db.py
Retrieve experiment data from MongoDB
python tumor_tcell/library/population_plots.py
Run population plotting utilities
python tumor_tcell/library/pymunk_minimal.py
Run the minimal Pymunk multibody example
python tumor_tcell/library/pymunk_multibody.py
Run the Pymunk multibody example

Tests

pytestpytest

Artifacts stored with this model.

Download all (zip)

16 B
171 B
8.7 KB
1.2 KB
5 B
975 B

Identifiers and integrity.

Metadata review: Approved · 1da614bf-946a-4400-a0be-4fd0f1d00f74 · Oct 2026

Contacts: John Hickey · john.hickey@duke.edu
Eran Agmon · agmon@uchc.edu
External IDs: url:https://github.com/vivarium-collective/tumor-tcell

Model characterization

Biology

Inputs & outputs