trovo-analysis

Analysis code for microwell co-culture imaging experiments — CAR-T and TIL effector cells imaged against tumor targets in arrays of individual microwells, with per-well fluorescence timecourses read out over hours to days.

Every project here consumes the same basic data shape: a wide CSV per plate, one row per microwell, with paired channel/feature/timepoint columns such as T Area 13 hours (0), C Confluency 1 day 23 hours (1), or the newer channel-named form A647 Area 2 days 23 hours / white Confluency 6 days 23 hours.

This repository holds source only — the canonical script, notebook, and package for each project. Raw plates, rendered figures, HTML reports, and fitted output directories live outside version control (see Data).

---

Projects

Project	What it is	Introduction
raw2Z/	Raw plate CSV → tumor-% and tumor Z-score curves against Tumor0-matched controls, plus population embedding/clustering	INTRODUCTION.md
zscore_viewer/	Installable package: the same Z-score computation plus an interactive Dash well browser	INTRODUCTION.md
notebooks/kill-rate-em/	EM CAR⁺/CAR⁻ mixture model for per-well killing rate k_eff	INTRODUCTION.md
notebooks/carrgo/	CARRGO-style predator–prey ODE fits with measured-T orthogonalisation	INTRODUCTION.md
notebooks/single-t/	Single-effector-cell wells: per-cell kill rates, inter-kill intervals, QC	INTRODUCTION.md
notebooks/merged-pipeline/	The long-running merged "T-series" report pipeline (E:T bins + rate estimates)	INTRODUCTION.md
notebooks/microwell-pipeline/	Structured ALL-wells vs single-T comparison pipeline	INTRODUCTION.md
notebooks/phenotype-analysis/	Threshold-based well phenotyping (killer / proliferator / persistent) and E:T binning	INTRODUCTION.md
notebooks/vaccine-potency/	Tetramer⁺ (GFP-gated) vaccine potency variant of the phenotype pipeline	INTRODUCTION.md
notebooks/dashboards/	Interactive in-notebook Plotly kinetics dashboards (incl. TIL dashboard)	INTRODUCTION.md
notebooks/figures/	Publication figure panels: killing triptych, Sina/violin plots, per-T reports	INTRODUCTION.md
notebooks/tools/	Header-format conversion between v2.0 channel names and v1.0 T/C names	INTRODUCTION.md
notebooks/archive/	First-generation notebooks kept for provenance	INTRODUCTION.md
ifn_quantification/	Per-microwell IFN-γ (FITC) release quantification and responder-rate statistics	INTRODUCTION.md
trovo_keff_cpp/	C++17 reimplementation of the k_eff vs r_T fitter, for batch speed	INTRODUCTION.md
lib/	Shared column parsing + canonical phenotype definitions	INTRODUCTION.md

---

How the projects relate

raw plate CSVs
      │
      ├─ notebooks/tools/          normalise headers (v2.0 channels → v1.0 T/C)
      │
      ├─ lib/                      parse timecourse columns, define phenotypes
      │        │
      │        ├─ notebooks/phenotype-analysis/   threshold phenotyping, E:T bins
      │        ├─ notebooks/vaccine-potency/      same, gated on tetramer⁺
      │        └─ notebooks/merged-pipeline/      consolidated HTML reports
      │
      ├─ raw2Z/  +  zscore_viewer/ Tumor0-matched Z-scores, embedding, well browser
      │
      ├─ notebooks/kill-rate-em/   mechanistic k_eff (EM CAR± mixture)
      │        └─ trovo_keff_cpp/  same fit, C++ for batch runs
      │
      ├─ notebooks/carrgo/         mechanistic k_eff (predator–prey ODE)
      │
      ├─ notebooks/single-t/       single-effector wells → per-cell rates, IKI
      │
      └─ notebooks/dashboards/     +  notebooks/figures/   presentation layer

Two independent routes to a per-well killing rate — the EM mixture model and the CARRGO ODE — exist deliberately: agreement between them is the main sanity check on any reported rate.

---

Data

Not in this repository. Notebooks read from paths configured at the top of the first cell, typically:

IN_DIR   = Path(globals().get('DATA_DIR', './data/raw_1_10'))
_baseout = Path(globals().get('OUT_DIR',  './outputs'))

Set DATA_DIR and OUT_DIR before running, or edit the defaults. Expected local layout (all git-ignored):

data/            raw plate CSVs, grouped by round/day/E:T ratio
input_select/    curated per-dataset CSVs + _capture_killer / _capture_non-killer subsets
outputs*/        fitted parameters, PNG/PDF figures, HTML reports

Notebook outputs are stripped before commit and no experimental results are tracked here, so the repository documents the methods rather than the findings of any particular study. Sample filenames in the examples are generic ({plate}_{well}_{sample}_{E:T ratio}).

Environment

conda env create -f environment.yml
conda activate microwell
python -m ipykernel install --user --name microwell --display-name "microwell (conda)"

zscore_viewer declares its own dependencies in pyproject.toml.

License

MIT — see LICENSE.

---

A note on file naming

These notebooks were written as research instruments, and their names record the model variant rather than a version number: _inter = effector–target interaction term, _rc = tumor growth-rate term, _migration = migration/contact term, _highRsquare / _goodCAR = fit-quality and CAR-call gating, realCARpos = measured rather than inferred CAR status, _wellcharts / _pretty = figure rendering, Ez = z-normalised effector metric, IKI = inter-kill interval.

Where several near-duplicate variants existed, only the newest complete one per family was committed; each project's introduction page names the file that supersedes the rest and what the dropped variants were.