irving-cell-binding-four-page-build-spec-2026-07-27

Irving cell-binding report: visual storyboard for four new pages

Goal

Build four client-facing report pages:

1. Production / Cell Recovery & Singlet Integrity
2. Production / Membrane Integrity
3. Assay Refinement / Binding-Linked Aggregation
4. Assay Refinement / Signal-Density Coupling & Control Anchor

These are visual arguments, not methods pages or dashboards. Each page should lead the reader through:

question → experiment/data → observation → decision

The default view must tell the whole story without clicking. Interactivity should expose detail, not supply missing logic.

Companion context:

• /Users/saahas/saah.as/garden/private/notes/irving-cell-binding-final-report-context-2026-07-27.md
• https://s4.taila7a7a.ts.net/shared/bhavaanijayaram/Cell%20binding%20production%20runs%20CSV%20tabular/index.html
• https://s4.taila7a7a.ts.net/shared/saahas/cell-binding-qc-rescue/index.html

Page design rules

• At least 75% of the page should be plots, diagrams, or data-bearing annotations.
• Use one conclusion-style headline, one one-sentence setup, and at most three short callouts per page.
• No explanatory paragraph longer than two lines.
• Give every visual a numbered title that states what was learned, not what chart type it is.
• Show raw points and physical-plate replicates; never hide disagreement behind a pooled mean.
• Use the same log-dose x-axis wherever dose is shown.
• Use direct labels instead of legends when practical.
• Use no dual y-axes.
• Use no decorative illustration. Every mark must represent data, assay structure, or an inference.
• Keep internal plate/run IDs in tooltips or a provenance drawer, not the client-facing page.
• Recompute every number after the final rerun plates arrive; do not hard-code current counts.

Use metric colors consistently:

Metric	Color
PE binding signal	Purple
Cell recovery	Blue
Singlet retention	Amber
Membrane integrity	Teal
Isotype/blank controls	Gray

Status colors—reportable, uncertain, excluded—must remain distinct from metric colors.

---

Page 1 — Production / Cell Recovery & Singlet Integrity

Client question

Was each binding curve measured on a stable cell population?

Headline

Antibody dose changed the recoverable singlet population for a subset of candidates.

Generate the actual subset count from final data.

Page composition

┌─────────────────────────────────────────────────────────────────┐
│ Headline + one-sentence setup                                   │
├────────────────────┬────────────────────────────────────────────┤
│ 1. Population      │ 2. Four exemplar dose-response stories    │
│    accounting      │    PE | cell recovery | singlet retention │
├────────────────────┴────────────────────────────────────────────┤
│ 3. All-candidate recovery landscape                            │
├─────────────────────────────────────────────────────────────────┤
│ Conclusion strip: counts + implication for production calls    │
└─────────────────────────────────────────────────────────────────┘

1. Show how the analyzed population is accounted for

Build a compact data-bearing cascade:

acquired events/uL
    ↓ FSC/SSC cell gate
cell-gated events/uL
    × singlet fraction
recoverable singlets/uL

For the currently selected candidate/dose, print the count at each stage and the percent lost between stages. This establishes the invariant:

PE median describes the cells that remain after this cascade; it does not measure how much of the dosed population remained.

Do not include membrane integrity here; Page 2 adds that fourth stage only where a valid dye exists.

2. Tell four complete dose-response stories

Choose four exemplars algorithmically from final data:

1. strongest reportable binder with stable recovery;
2. strongest binder with dose-linked cell-density loss;
3. clearest dose-linked singlet exclusion;
4. negative/weak candidate with stable recovery.

For each exemplar, show one row of three aligned plots:

Plot	y-axis	Required marks
Binding	normalized PE response	raw wells, per-plate lines, 4PL only if fit is valid
Cell recovery	cell-gated events/uL normalized to same-plate blank	raw wells, blank reference
Singlet retention	singlet fraction	raw wells, per-plate lines

Use the same dose ticks in every panel. Hollow points remain visible when excluded; the tooltip gives the exclusion reason.

End each row with a five-word data label such as:

• Stable population; strong binding
• Cell depletion increases with dose
• Singlet exclusion increases with dose
• Stable population; no binding

Do not assign a biological mechanism on this production page.

3. Show every candidate in one decision landscape

Build a scatterplot:

• x-axis: minimum normalized cell recovery;
• y-axis: maximum normalized binding response;
• one point per candidate;
• point shape:
  • stable;
  • cell-density loss;
  • singlet exclusion;
  • combined loss;
  • not assessable;
• point outline: replicate agreement;
• label the most consequential candidates directly.

Add a dashed 70% recovery line only as exploratory, unless science approves it as a release threshold.

The four regions should be directly titled:

• strong binding / stable population;
• strong binding / compromised population;
• weak binding / stable population;
• weak binding / compromised population.

Clicking a point replaces the exemplar area with that candidate’s three plots. The static export must retain the four algorithmic exemplars.

Conclusion strip

Show only four generated numbers:

[N] stable population
[N] cell-density loss
[N] singlet exclusion or combined loss
[N] not assessable

Then one sentence:

Compromised recovery does not erase the observed fluorescence response, but it limits how confidently that response represents the original dosed population.

Data required

• every production antibody and dose;
• physical replicate identity;
• acquired volume;
• FSC/SSC cell-gate count;
• singlet-gate count;
• PE median;
• same-plate blank, isotype, and Durvalumab controls;
• gating version, plate QC, and exclusion reason.

Do not estimate recovery from an event count capped by an acquisition stop.

---

Page 2 — Production / Membrane Integrity

Client question

Is dose-linked cell loss accompanied by membrane compromise?

Headline

Membrane integrity and cell recovery separate two different forms of population compromise.

Page composition

┌─────────────────────────────────────────────────────────────────┐
│ Headline + compact assay-coverage ribbon                        │
├─────────────────────────────────────────────────────────────────┤
│ 1. Recovery × membrane-integrity map for every eligible Ab     │
├───────────────────────────────┬─────────────────────────────────┤
│ 2. All-Ab dose-pattern matrix │ 3. Selected candidate curves   │
├───────────────────────────────┴─────────────────────────────────┤
│ Conclusion strip                                                │
└─────────────────────────────────────────────────────────────────┘

Coverage ribbon

Before making a biological claim, show which runs support it:

Status	Meaning
Teal	Valid membrane-impermeant/fixable viability dye with known parent gate
Gray	No eligible membrane-integrity readout
Amber hatch	Debris/nuclear-content proxy only

Render one narrow tile per physical plate, grouped by run. Tooltip: dye, fixation state, gating version, candidates covered.

PI on unfixed cells or a protocol-valid fixable live/dead dye is eligible. Fixed Hoechst/Pacific Blue is not viability and must never be labeled as such.

1. Separate recovery loss from membrane compromise

Build the hero scatterplot:

• x-axis: minimum normalized cell recovery;
• y-axis: minimum membrane-intact fraction;
• one point per eligible candidate;
• point fill: maximum binding response;
• point outline: replicate agreement;
• shape: dye/gating-compatible assay subset.

Directly title the four regions:

Region	Label
high recovery, high integrity	Stable population
low recovery, high integrity	Recovery loss without proportional membrane compromise
low recovery, low integrity	Combined recovery and membrane compromise
high recovery, low integrity	Membrane effect or stain/gate concern

Do not label any quadrant “cell death.”

2. Make all antibodies and runs visible

Build two aligned candidate-by-dose matrices:

1. membrane-intact fraction;
2. membrane-intact singlets/uL.

Rows are candidates, grouped by physical run. Columns are ascending dose. Use a perceptually uniform sequential scale with the numeric value printed in each cell when space permits.

Rules:

• show missing/invalid cells as hatched, never as zero;
• retain separate row bands for physical replicates;
• sort candidates by the supported dose slope, largest decline first;
• place Durvalumab and isotype at the top of each run group;
• allow filters, but the default view includes every eligible antibody/run;
• use this matrix only for overview—the adjacent curve supplies the raw points.

This is the page that answers “viability readouts for all antibodies/runs” at a glance.

3. Show the raw dose story for the selected candidate

Selecting a matrix row or scatter point opens four aligned plots:

1. normalized PE response;
2. normalized cell recovery;
3. membrane-intact fraction;
4. membrane-intact singlets/uL.

Show physical replicates separately, with matched isotype and Durvalumab controls available as directly labeled overlays. Print dye, fixation state, and gate parent above the plots.

The generated annotation must use this form:

Membrane integrity [declines / remains stable / is inconclusive] with dose, while recoverable singlets [decline / remain stable / are inconclusive].

Conclusion strip

Show:

[N] eligible antibodies/runs
[N] dose-linked membrane compromise
[N] recovery loss with preserved membrane integrity
[N] inconclusive

Then one sentence:

These patterns distinguish membrane compromise from clumping, transfer loss, and singlet exclusion; they do not by themselves identify the upstream mechanism.

Data required

• all Page 1 data;
• dye identity and positive/negative direction;
• fixation and stain timing;
• membrane-integrity gate count and exact parent gate;
• debris/nuclear-content proxy identified separately;
• gating compatibility across compared wells.

Fractions and absolute membrane-intact singlets/uL must both be shown. A stable fraction can conceal large absolute population loss.

---

Page 3 — Assay Refinement / Binding-Linked Aggregation

Client question

What mechanism best explains the target- and dose-linked population loss?

Headline

Three experiments converge on transient, binding-linked aggregation as the leading mechanism.

Use “consistent with” or “leading mechanism,” not “proved,” until clumps are measured directly.

Page composition

┌─────────────────────────────────────────────────────────────────┐
│ Headline                                                        │
├───────────────────┬───────────────────┬─────────────────────────┤
│ 1. Orientation    │ 2. Target control │ 3. Dose / gate cascade │
│    experiment     │    experiment     │    experiment           │
├───────────────────┴───────────────────┴─────────────────────────┤
│ 4. Evidence → mechanism diagram → discriminating next tests    │
└─────────────────────────────────────────────────────────────────┘

Each experiment card has exactly four elements:

Question | comparison | observed data | inference

1. Orientation experiment weakens fixed geometry

Show the same plate as two side-by-side plate maps:

• initial acquisition;
• reread after 180° rotation.

Add physical orientation markers and the acquisition-direction arrow. Print the spatial slope/CV on each map.

Under the maps:

A fixed plate/optical effect should rotate with physical coordinates. The pattern diminished on reread, so fixed geometry is insufficient.

This experiment supports a transient sample-state effect; it does not identify aggregation alone.

2. Target control weakens global handling loss

Use same-plate paired dots for:

• blank;
• same-concentration isotype;
• Durvalumab;
• representative target-binding candidates.

y-axis: recoverable singlets/uL. Connect conditions within each physical plate. Show the paired effect and interval, not an unpaired box plot.

Alongside it, show one compact target-engagement dose plot:

• PE response rises with dose;
• recovery falls with dose;
• isotype remains comparatively stable.

Annotation:

Loss tracks target engagement more closely than shared plate handling.

If a control plate contradicts this, show it; do not average it away.

3. Gate cascade localizes where cells disappear

Build an attrition waterfall for:

• blank;
• isotype;
• low, medium, and high Durvalumab;
• one strong, one weak, and one negative candidate.

acquired events/uL
    → cell-gated events/uL
    → singlets/uL
    → membrane-intact singlets/uL, where valid

Facet by experiment when gates are not directly compatible. Use absolute units and print percent loss at each transition.

This visual must answer:

• are events absent before the cell gate?
• are multiplets removed at the singlet gate?
• is membrane compromise an additional loss?

4. Let the evidence resolve into one mechanism

After the three experiment cards, show a simple assay schematic:

PD-L1+ cell + bivalent primary + multivalent secondary
                         ↓
                 cell-cell bridging
                  ↙             ↘
       clumps lost in wash   multiplets excluded
                  \             /
            PE median on survivors

Place three evidence checks next to the corresponding arrows:

• target dependence;
• dose dependence;
• physical loss plus singlet exclusion.

Keep the earlier May failure visually separate in a two-point timeline:

May: fresh pellet disturbed by robot motion → corrected
July: target/dose-linked loss remains → current mechanism

Do not present these as one persistent root cause.

Discriminating next experiments

End the page with three visual experiment cards, ranked by information gain:

A. Remove secondary-mediated bridging

Current two-step stain  vs  directly labeled primary

Measure PE response, cell recovery, singlet fraction, and membrane integrity across the same primary dose ladder. If recovery is restored without losing specific binding, secondary-mediated bridging is strongly supported.

B. Change secondary valency

Current multivalent secondary  vs  monovalent anti-human Fab

Keep antibody equivalents and wash conditions matched. Restoration of recovery/singlets with the Fab supports crosslinking rather than primary toxicity.

C. Test the equivalence-zone prediction

Secondary limiting → near equivalence → true excess

Aggregation should peak near lattice-forming equivalence and weaken in true reagent excess. Show recovery and singlet fraction against the primary:secondary molar ratio.

Add membrane-integrity measurements at four time points—before stain, after primary, after secondary, after wash—to determine whether membrane compromise precedes or follows aggregation.

Conclusion strip

The existing experiments weaken fixed geometry, global handling loss, and gate-only artifact. Binding-linked aggregation is the leading explanation; changing secondary format is the most direct falsification test.

---

Page 4 — Assay Refinement / Signal-Density Coupling & Control Anchor

Client question

Does cell depletion inflate PE signal and destabilize the 10 nM Durvalumab normalization anchor?

Headline

Lower cell density predicts higher PE per surviving cell, while the saturating control is itself depleted.

Page composition

┌─────────────────────────────────────────────────────────────────┐
│ Headline                                                        │
├───────────────────────────────┬─────────────────────────────────┤
│ 1. Mirrored-pair experiment   │ 2. Robustness across analyses  │
├───────────────────────────────┴─────────────────────────────────┤
│ 3. Anchor tradeoff: saturation vs recovery                     │
├───────────────────────────────┬─────────────────────────────────┤
│ 4. What moves: EC50 vs Emax   │ 5. Replacement-control test    │
└───────────────────────────────┴─────────────────────────────────┘

1. Use the mirrored-pair experiment to isolate density

The key experiment is the mirrored Durvalumab reference design:

• same antibody;
• same nominal concentration;
• same physical plate and run;
• mirrored well positions.

For every matched pair plot:

x = Δlog10(cell density)
y = Δlog10(PE median)

Show all raw pairs, zero lines, fitted slope, and 95% interval. Add plate facets or a plate selector.

Current pre-rerun orientation values to reproduce, then recompute:

144 matched pairs across 18 Round 2 plates
slope ≈ -0.454 ± 0.086 SE
emptier well is brighter in 103/144 pairs
15/18 plates have a negative within-plate slope

The one-sentence inference:

Within matched technical pairs, lower cell density is associated with higher PE median among the surviving cells.

Do not generalize the exact Durvalumab slope to every antibody as a proven correction.

2. Show why this pairing is credible

Build a forest plot of slope and interval for:

• unadjusted matched pairs;
• plate means removed;
• row-position means removed;
• plate and row means removed;
• through-origin fit;
• across-plate pairing, visually separated and labeled invalid.

The valid models should read as a coherent robustness check. The invalid across-plate result is included only to show the confounding from whole-plate density/brightness offsets.

3. Make the control-anchor conflict visible

Use two vertically aligned Durvalumab dose plots:

1. PE signal as percent of fitted plateau;
2. normalized cell recovery.

Highlight three dose regions:

• preserved recovery but sub-saturating signal;
• transition;
• near-saturated signal but depleted recovery.

The visual conclusion should be immediate:

No currently tested Durvalumab dose is both clearly saturated and non-depleting.

Show physical plates separately and include uncertainty around the fitted plateau.

Add a small worked inset using the clean versus corrupted reference replicate:

• raw reference points and 4PL fits;
• recovery below each point;
• label them saturating reference replicate and non-saturating reference replicate;
• keep internal plate IDs in provenance only.

If the two-component diagnostic is retained, label it mechanism/QC diagnostic, not client potency:

signal = Bmax × C / (Kd + C) + a × C

4. Show what the anchor uncertainty changes

Build a two-part consequence visual.

EC50 dumbbells

For each candidate, compare EC50 under the tested normalization anchors.

• single-plate 4PL EC50 should remain unchanged under affine y-rescaling;
• pooled-replicate EC50 may move when plates are reweighted differently;
• show these as separate cohorts.

This is the structural reason: rescaling the y-axis changes amplitude, not the x-coordinate of the half-max point within one curve.

Emax intervals

Show raw and density-sensitivity Emax with uncertainty intervals. Draw the 60% and 85% category boundaries. Do not assign a categorical efficacy label when the interval crosses a boundary.

Current pre-rerun orientation values to recompute:

anchor uncertainty ≈ ±27% at 95% confidence
56/72 candidates cross an efficacy-category boundary

Label all density-adjusted values:

Exploratory sensitivity analysis—not the production source of truth.

5. End with the replacement-control experiment

Compare the current two-step Durvalumab reference with a directly labeled, non-depleting positive control on at least two physical plates.

Use the same dose ladder and measure:

• fitted saturation plateau;
• cell recovery;
• singlet fraction;
• membrane integrity;
• EC50 of known controls;
• between-plate agreement.

The replacement succeeds only if it:

1. reaches a clear plateau;
2. retains a science-approved minimum recovery;
3. preserves known-control EC50;
4. reproduces across at least two physical plates.

Do not invent the minimum-recovery threshold. Obtain scientific approval before the experiment.

Conclusion strip

The current anchor is useful for plate-level scaling but not a stable efficacy denominator. Preserve raw production results, show density sensitivity separately, and qualify a non-depleting positive control.

---

Shared implementation contract

This section is for Claude; it should not appear as prose in the report.

Build one canonical per-well table with:

campaign, round, run, physical plate, well, candidate, control class,
dose, composition lineage, acquired volume, acquisition stop,
cell-gate count, singlet count, membrane-intact count and parent gate,
PE median, dye, fixation state, gating version, exclusion reason, plate QC

Derive:

cell density/uL            = cell-gate count / acquired volume
singlet fraction           = singlet count / cell-gate count
singlet density/uL         = singlet count / acquired volume
membrane-intact fraction   = intact count / declared parent count
intact singlets/uL         = singlet density/uL × intact fraction
normalized recovery        = singlet density/uL / same-plate blank singlet density/uL
top-to-bottom recovery     = recovery at highest dose / recovery at lowest dose

Guardrails:

• never pool Round 1 and Round 2 dose ladders;
• never convert capped event counts into recovery;
• never treat fixed Hoechst/Pacific Blue as viability;
• never silently average incompatible gates or physical replicates;
• never label inferred missing exposure as hook/prozone;
• keep density correction exploratory;
• preserve the distinction between raw result, sensitivity analysis, replicate rescue, and final approved call.

Definition of done

• The default static rendering tells each page’s story without interaction.
• Every headline is supported by the plots immediately beneath it.
• Every production antibody/run is visible or has a visible missingness reason.
• Every mechanistic claim is paired with an experiment and an observation.
• Raw wells and physical replicates are inspectable.
• Final rerun plates flow through automatically.
• All page counts reconcile with strict QC and replicate-rescue pages.
• No page exceeds one sentence of setup plus three short explanatory callouts.

Shape of the diff

Verify current owners before editing because another agent is changing both analysis repositories. Reuse existing calculations where they already have a canonical owner.

New files

• /Users/saahas/binding-fcs-pipeline/cell_integrity.py — canonical per-well recovery, singlet, membrane-integrity, and sensitivity calculations.
• /Users/saahas/binding-fcs-pipeline/test_cell_integrity.py — behavior tests for censoring, normalization, eligibility, exclusions, and replicate separation.
• /Users/saahas/binding-fcs-pipeline/assaydev_data/cell_integrity.json — generated data shared by production and assay-refinement pages.

Edited files

• /Users/saahas/binding-fcs-pipeline/metrics_tidy.py — expose acquired volume and nested gate counts.
• /Users/saahas/binding-fcs-pipeline/report.py — generate production-page payloads and summaries.
• /Users/saahas/binding-fcs-pipeline/report_shell.html — render Pages 1–2 and their interactions.
• /Users/saahas/binding-fcs-pipeline/assaydev_report.py — generate aggregation, matched-pair, anchor, and sensitivity payloads.
• /Users/saahas/binding-fcs-pipeline/assaydev_report_shell.html — render Pages 3–4.
• /Users/saahas/binding-fcs-pipeline/report_staleness.py — track integrity artifacts and final rerun inputs.

Do not edit generated HTML directly.