/by-screening

id: "skill_e7c1ce2e57a74e8188dafa78231781c6"
name: "by-screening"
display-name: "BY Screening"
short-description: "Comprehensive screening battery — structural confidence (ipTM/pLDDT/RMSD), ipSAE interface quality, PTM liabilities, and developability filters for protein/antibody designs. Use when triaging design outputs from BoltzGen or PXDesign before lab submission."
category: "filtering"
keywords: "screening, ipSAE, ipTM, pLDDT, RMSD, liabilities, developability, PTM, CDR, antibody, nanobody, filter, triage"
version: "1.0"
last-updated: "2026-05-20"
mcp_tools:
  - "mcp__by-screening__screen_liabilities"
  - "mcp__by-screening__screen_developability"
  - "mcp__by-screening__screen_net_charge"
  - "mcp__by-screening__screen_composite"
  - "mcp__by-screening__screen_diversity"
  - "mcp__by-screening__screen_diagnose_failures"
  - "mcp__by-screening__screen_pareto_front"
  - "mcp__by-screening__screen_align_sequences"
  - "mcp__by-screening__screen_cross_validate"
  - "mcp__by-screening__screen_shape_complementarity"
  - "mcp__by-screening__screen_naturalness"
  - "mcp__by-screening__interpret_scores"

BY Screening Skill

Comprehensive screening battery for evaluating protein binder and antibody designs produced by PXDesign and BoltzGen. This skill encodes all quality filters, scoring thresholds, liability checks, and developability assessments used to triage designs before experimental validation.

Always run the full screening pipeline before presenting final candidates to the user. Never present unscreened designs as ready for validation.

---

When to Use This Skill

Use **by-screening** when you have:

• ✅ Raw design outputs from BoltzGen or PXDesign with refolding predictions (Protenix NPZ + scores)
• ✅ A set of candidate sequences that need PASS/FAIL classification before lab submission
• ✅ A campaign nearing the `/by:approve-lab` gate — screening MUST run first
• ✅ Designs that need PTM liability and developability triage prior to ranking
• ✅ A need to diagnose batch-level failures (all FAIL ipTM, all FAIL RMSD, etc.)
• ✅ The need to apply diversity clustering before presenting top-N candidates

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

• ❌ Computing raw scoring metrics → use **by-scoring** (ipSAE NPZ math, composite formula derivation, multi-seed aggregation)
• ❌ Diagnosing root cause of a failed campaign at the *strategy* level → use **by-failure-diagnosis** (modality choice, scaffold selection, target druggability)
• ❌ Generating designs → use **boltzgen** or **pxdesign**
• ❌ Selecting which designs to advance to lab AFTER screening — that is the **by-design-workflow** orchestration step
• ❌ Looking up reference epitopes or target biology → use **by-research**

**Cross-skill hand-off:**

| Situation | Skill to call | |-----------|---------------| | Need raw ipSAE/ipTM numbers from NPZ | **by-scoring** first, then this skill | | Need to apply PASS/FAIL filters to a batch | **by-screening** (this skill) | | Whole batch fails screening (>80% FAIL) | **by-failure-diagnosis** for strategy correction | | Designs pass screening, need rank/select | **by-screening** Stage 2 + 3, then **by-design-workflow** |

---

Quick Start

Run the full composite screen on a single design:

python scripts/screen_batch.py \
  --designs path/to/designs.csv \
  --modality antibody \
  --output path/to/screened.csv

Generate a campaign-ready markdown report:

python scripts/generate_screening_report.py \
  --screened path/to/screened.csv \
  --output path/to/screening_report.md

Parse raw MCP tool output into a tidy table:

python scripts/parse_scores.py \
  --input raw_mcp_output.json \
  --output scores_tidy.csv

Expected runtime: ~2 seconds for 100 designs (pure CPU; no GPU compute).

---

Inputs

**Required:**

• **Design sequences**: CSV or JSON with columns `name`, `sequence` (single-letter AAs)
• **Scoring metrics**: per-design `iptm`, `plddt` (mean over design chain), `rmsd_ca` (refolding CA-RMSD), `ipsae_min` (from `mcp__by-screening__score_ipsae`)
• **Modality**: one of `antibody`, `nanobody`, `binder` (controls threshold table — see [filter-thresholds.md](references/filter-thresholds.md))

**Optional:**

• **CDR regions**: list of `[start, end]` tuples (0-indexed, end-exclusive) — required for CDR-localized liability triage and CDR length checks
• **Interface residue indices**: list of positions for per-residue pLDDT analysis
• **Dual-predictor scores**: BoltzGen + Protenix ipTM/ipSAE pairs for `screen_cross_validate`
• **CDR pLDDT**: mean pLDDT computed over CDR residues only

**Input format example (CSV):**

name,sequence,iptm,plddt,rmsd_ca,ipsae_min,modality
d_001,EVQLVESGGGLVQPGGSLR...,0.82,84.5,1.7,0.65,antibody
d_002,QVQLVQSGAEVKKPGAS...,0.45,72.1,4.8,0.32,antibody

See [filter-thresholds.md](references/filter-thresholds.md) for the master table of all metrics, defaults, and modality overrides.

---

Outputs

**Primary results:**

• **Screened CSV** (per-design row): `name`, `verdict` (PASS/FAIL/MARGINAL), `reason_codes` (semicolon-separated), all input scores, plus computed columns `liability_count`, `weighted_liability_count`, `net_charge`, `hydrophobic_fraction`, `total_cdr_length`, `composite_score`
• **Reason codes**: machine-readable failure tags, e.g. `LOW_IPTM`, `FAIL_RMSD`, `CDR_NG`, `ODD_CYS`, `EXTREME_CHARGE`, `LONG_CDR3`
• **PASS rate**: aggregate fraction of designs that cleared all hard filters

**Reports:**

• **Markdown screening report** (`generate_screening_report.py` output):
• PASS rate summary (overall + per-modality)
• Distribution histograms (ipTM, pLDDT, RMSD, ipSAE)
• Top failed criteria (which reason codes are most common)
• Liability breakdown by location (CDR / interface / framework)
• Top-N PASS candidates ranked by composite score
• **Tidy scores CSV** (`parse_scores.py` output): one row per design, one column per metric — suitable for downstream notebooks or Pareto-front analysis

**Verdict