001tmf/blatant-why/by-screening

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:

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)

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 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 semantics:

• PASS — clears all Stage 1 hard filters
• MARGINAL — clears hard filters but flagged on at least one soft criterion (e.g., interface pLDDT 70–75)
• FAIL — one or more hard filters tripped; reason_codes lists which

Clarification Questions

⚠️ CRITICAL: ASK THIS FIRST. Before running any screening, always confirm you have the required inputs.

1. Input data location (ASK THIS FIRST):

• Where are the design sequences and refolding scores? (campaign dir, CSV path, NPZ files?)
• Have you already run mcp__by-screening__score_ipsae on the Protenix outputs? If not, run by-scoring first.

1. Modality of the designs:

• Antibody (Fv / scFv), nanobody (VHH), or de novo protein binder? Each has different default thresholds (see filter-thresholds.md).

1. CDR annotations:

• For antibodies/nanobodies, do you have IMGT or Kabat CDR boundaries? Without them, liability location (CDR vs framework) cannot be assessed.

1. Screening stringency:

• Default thresholds (production-grade), relaxed (exploratory tier, accept marginal), or strict (lab-ready only)?

1. Output format:

• Tidy CSV for downstream analysis, markdown report for the campaign summary, or both?

1. Cross-validation needed?:

• Are these designs heading to /by:approve-lab? If yes, dual-predictor cross-validation is REQUIRED.

1. Failure recovery:

• If all designs fail, do you want automatic diagnosis (calls by-failure-diagnosis) or a raw failure report?

Standard Workflow

🚨 MANDATORY: USE SCRIPTS EXACTLY AS SHOWN — DO NOT WRITE INLINE CODE 🚨

The screening pipeline has three sequential stages plus optional cross-validation. Run them in order.

Step 1: Parse raw scoring outputs

python scripts/parse_scores.py \
  --input campaigns/{target}/design_run_{id}/raw_scores.json \
  --output campaigns/{target}/design_run_{id}/scores_tidy.csv

✅ VERIFICATION: ✓ parsed scores: 247 designs / scores_tidy.csv

Step 2: Apply screening battery (hard filters + soft ranking)

python scripts/screen_batch.py \
  --designs campaigns/{target}/design_run_{id}/scores_tidy.csv \
  --modality nanobody \
  --output campaigns/{target}/design_run_{id}/screened.csv \
  --thresholds-profile production

✅ VERIFICATION: ✓ screening completed: 247 designs / 38 PASS (15.4%) / 12 MARGINAL / 197 FAIL

Step 3: Generate the campaign-ready report

python scripts/generate_screening_report.py \
  --screened campaigns/{target}/design_run_{id}/screened.csv \
  --output campaigns/{target}/design_run_{id}/screening_report.md

✅ VERIFICATION: ✓ report written: screening_report.md (PASS rate 15.4%, top reason: LOW_IPTM)

Step 4 (optional): Cross-validate with second predictor

Only required when designs are heading to lab. Use mcp__by-screening__screen_cross_validate:

mcp__by-screening__screen_cross_validate(
    designs_json='[{"name":"d_001","boltzgen_iptm":0.82,"protenix_iptm":0.78,...}]'
)

Anti-patterns

⚠️ CRITICAL — DO NOT:

• ❌ Re-implement the composite formula inline → it lives in screen_batch.py and is also a tested MCP tool
• ❌ Hard-code absolute paths in scripts → pass via CLI flags
• ❌ Skip Step 1 and parse MCP output ad-hoc → reason codes will be inconsistent
• ❌ Lower the hard-filter thresholds without documenting why → audit trail required
• ❌ Present FAIL designs as candidates "because they look interesting" → MARGINAL is the only escape valve

When Scripts Fail

Follow the script failure hierarchy:

1. Fix and Retry (90%) — Missing package? Install. Schema drift in input CSV? Run parse_scores.py first.
2. Modify Script (5%) — Threshold needs adjusting for a specific campaign? Edit the script's THRESHOLDS dict and re-run.
3. Use as Reference (4%) — Custom screening flow? Read scripts, adapt the approach.
4. Write from Scratch (1%) — Only if the input format is fundamentally incompatible (e.g., non-protein design). Document the reason.

If the failure is at the campaign level (whole batch fails, multiple metrics fail together), stop and call by-failure-diagnosis instead of patching scripts.

Decision Points

Threshold profile selection

Modality threshold overrides

• Antibody (Fv/scFv): total CDR length ≤70, sequence identity clustering at 90% over CDRs only
• Nanobody (VHH): total CDR length ≤45, CDR-H3 ≤25, lower CDR-H3 pLDDT acceptable (≥60)
• De novo binder: no CDR concept; cluster at 70% sequence identity across full chain

Liability triage decision tree

For each liability:
  IF location == CDR AND severity == high      → REJECT design
  ELIF location == interface AND severity == high → MARGINAL + flag
  ELIF location == framework AND severity == high → TOLERABLE, document
  ELSE → ACCEPTABLE, count toward soft ranking penalty (weighted)

Weights: CDR=3x, interface=2x, framework=1x. See liability-rules.md.

Common Issues