/by-experiment-results

id: "skill_4e182a2c2fad4dcd97f1f24db39eb949"
name: "by-experiment-results"
display-name: "BY Experiment Results"
short-description: "Closes the wet-lab feedback loop — ingests lab readouts (Adaptyv batch CSVs, internal ELISA/BLI/Octet, expression QC), joins them to in-silico features per design_id, diagnoses which predictions matched reality, and pipes calibration findings into the optimizer and knowledge graph. Use when a lab readout file arrives, when validating round-N predictions against round-N-1 lab data, or when computing calibration metrics across an internal screening batch."
category: "diagnosis"
keywords: "lab readout, experimental validation, calibration, in-silico vs in-vitro, wet-lab feedback, ELISA, BLI, Octet, Adaptyv, ground truth, precision at K, Mann-Whitney, validated finding, falsified finding"
version: "1.0"
last-updated: "2026-05-20"
mcp_tools: ["mcp__by-adaptyv__adaptyv_get_results", "mcp__by-knowledge__knowledge_store_campaign", "mcp__by-knowledge__knowledge_store_failure"]

BY Experiment Results Skill

A design campaign only learns when lab outcomes are joined back to the in-silico predictions that produced them. This skill is the wet-lab feedback loop closer: it ingests lab readouts (Adaptyv batch CSVs, internal ELISA plate-reader output, BLI/Octet kinetics, expression QC), joins them to the per-design feature table the screener emitted, and runs a calibration analysis that asks one question for every in-silico feature:

> **Did this feature actually predict whether the design worked in the lab?**

The answer for each feature is one of: **validated** (in-silico PASS correlated with lab PASS), **contradicted** (predictor pointed the opposite direction), or **inconclusive** (no signal). The diagnosis goes into the knowledge graph with that confidence label so future campaigns start from real-world-calibrated priors, not silicon-only priors.

This skill sits between **by-screening** (which produces in-silico PASS/FAIL) and **by-campaign-optimizer** (which trains the next round). It is the only skill in BY that consumes **ground-truth lab data**.

---

When to Use This Skill

✅ **Use this skill when:**

• A lab readout file (CSV or Excel) has arrived from Adaptyv Bio for a previously submitted batch
• An internal ELISA, BLI, or Octet run has produced a tidy results table for designs the BY pipeline scored
• You need to validate round-N in-silico predictions against round-N-1 lab outcomes
• A user asks "did our predictions hold up?", "calibrate the screener", or "did ipSAE correlate with Kd?"
• A round of designs has come back from the lab and you need to update the campaign-optimizer training data with ground truth
• You want to write a **calibration report** showing precision at top-K and lift over random
• You want to publish findings to the knowledge graph as **validated** or **contradicted** with confidence levels

❌ **Don't use this skill for:**

• A campaign that has not yet been submitted to lab — there is no ground truth to compare. Use **by-screening** + **by-failure-diagnosis** first.
• Pre-submission ranking of designs — that is **by-screening** and **by-design-workflow**.
• Computing raw in-silico scores from PDB / NPZ — use **by-scoring**.
• Diagnosing why a campaign produced low in-silico pass rate — use **by-failure-diagnosis** (no lab data needed).
• Lab submission itself — use the gated `/by:approve-lab` flow and **by-adaptyv** MCP tools.
• Curating raw structural files (CIF / PDB) — those stay in the campaign directory.

---

Quick Start

The shortest path from a lab CSV to a calibration report and knowledge-graph update is three CLI calls:

# 1) Normalize the lab readout to canonical schema
python3 scripts/ingest_lab_results.py \
    --input  experiments/batch_001_adaptyv.csv \
    --output campaigns/<target>/<campaign_id>/lab_results.normalized.json \
    --assay  affinity_bli \
    --aggregate median

# 2) Join with in-silico features and run calibration
python3 scripts/diagnose_silico_vs_lab.py \
    --lab          campaigns/<target>/<campaign_id>/lab_results.normalized.json \
    --silico       campaigns/<target>/<campaign_id>/screening_results.json \
    --output-json  campaigns/<target>/<campaign_id>/calibration.json \
    --output-md    campaigns/<target>/<campaign_id>/calibration_report.md

# 3) Push validated / contradicted findings to the knowledge graph
python3 scripts/update_knowledge_from_lab.py \
    --calibration campaigns/<target>/<campaign_id>/calibration.json \
    --campaign-id <campaign_id> \
    --target      <target>

✅ **VERIFICATION:** `calibration.json` contains a `features[]` array where each feature has a `verdict` of `validated`, `contradicted`, or `inconclusive`, and `calibration_report.md` opens with a one-line headline like "12 / 18 lab-tested designs bound (67%); ipSAE_min was the strongest validated predictor (p=0.004, AUC=0.81)."

---

Installation

| Software | Version | License | Commercial Use | Installation | |----------|---------|---------|----------------|--------------| | Python | >= 3.10 | PSF | ✅ Permitted | system | | pandas | >= 2.0 | BSD-3 | ✅ Permitted | `pip install pandas` | | numpy | >= 1.24 | BSD-3 | ✅ Permitted | `pip install numpy` | | scipy | >= 1.11 | BSD-3 | ✅ Permitted | `pip install scipy` | | openpyxl | >= 3.1 | MIT | ✅ Permitted | `pip install openpyxl` (only for `.xlsx` ingestion) | | scikit-learn | >= 1.3 | BSD-3 | ✅ Permitted | `pip install scikit-learn` (for AUC in calibration) |

**License Compliance:** All third-party packages permit commercial use in AI applications.

**System requirements:** CPU-only; no GPU; no internet (unless pulling Adaptyv results via the MCP tool). All scripts run in seconds for batches up to ~1,000 designs.

---

Inputs

**Required:**

• **Lab readout file** (CSV or Excel; `.csv` / `.tsv` / `.xlsx`):
• Must contain a `design_id` column (canonical) **or** a renameable alias mapped via `--alias design_id=<src>`. The `design_i