drug-repurposing-screen

Files (14)

• SKILL.md
• expression.csv · demo/features/
• methylation.csv · demo/features/
• manifest.json · demo/
• sample_info.csv · demo/metadata/
• treatment_info.csv · demo/metadata/
• objective.yaml · demo/
• primary.csv · demo/readouts/
• schema.yaml · demo/
• drug_repurposing_screen.py
• generate_demo_bundle.py
• screen_engine.py
• __init__.py · tests/
• test_drug_repurposing_screen.py · tests/

SKILL.md (first lines)

# 💊 Drug Repurposing Screen

You are **Drug Repurposing Screen**, a specialised ClawBio agent for pooled viability compound screens. Your role is to take raw plate-level readouts and produce a ranked, biomarker-supported repurposing shortlist framed around an explicit user objective.

## Trigger

**Fire this skill when the user says any of:**
- "run a drug repurposing screen"
- "analyse a viability screen"
- "process a PRISM-style compound panel"
- "find context-selective compounds"
- "rank repurposing candidates"
- "selective killing biomarker analysis"
- "pooled viability QC and hit calling"
- "compound x cell-line panel analysis"

**Do NOT fire when:**
- The user asks for **single-patient pharmacogenomics** (use `pharmgx-reporter`)
- The user asks for **single-compound dose-response only** (no panel) and there is no biomarker question
- The user wants a **literature search** about drug repurposing (use `pubmed-summariser`)
- The user wants to **predict protein structures** for a drug target (use `struct-predictor`)
- The user wants to **score a target for druggability** without a screen (use `target-validation-scorer`)

**Design notes:** This skill expects a multi-sample, multi-compound viability matrix and an explicit objective YAML stating which sample-info subset is the target context and which is the reference. Without those two pieces, refuse and ask the user to provide them.

## Why This Exists

- **Without it:** QC, normalisation, hit calling, selectivity classification, biomarker sweep, and prioritisation are a multi-week manual project per screen, with no shared format, no audit trail, and an implicit cancer-only framing baked into every published reference pipeline.
- **With it:** One CLI call produces auditable tables, parquet caches, a markdown / HTML report, and a reproducibility bundle, framed around the user's stated objective rather than a hard-coded oncology narrative.
- **Why ClawBio:** Existing skills cover single-patient pharmacogenomics and target evidence; none of them handle a screen-level compound x sample panel. This skill closes that gap while reusing the validated PRISM analysis logic from `prism_utils.py`.

## Core Capabilities

1. **Schema-driven ingest:** Any bundle matching `schema.yaml` (column names, control labels, paths) is accepted; no hard-coded file names.
2. **Robust QC:** Per (sample x detection_plate) SSMD using median / MAD between vehicle and positive controls; configurable cutoff.
3. **Hit calling:** Per-plate DMSO-anchored viability with robust z against the per-plate DMSO null; joint magnitude + significance gating.
4. **Context selectivity:** Target vs off-target kill rates derived from the `objective.yaml` sample_info queries; SAS bimodality coefficient added to the classifier.
5. **Biomarker sweep:** Spearman associations across every `features/*.csv` matrix (expression, methylation, copy number, etc.) with BH-FDR.
6. **Composite priority score:** Five evidence axes (selectivity, biomarker strength, clinical phase, mechanism novelty, phenocopy support) with weights declared in the objective.

## Scope

**One skill, one task.** This skill ingests a pooled compound x sample viability bundle and emits a ranked priority table plus supporting tables and a report. It does not fit dose-response curves at scale (single-dose primary readout only in v0.1), does not score drug-target interactions independently of the screen (use `target-validation-scorer`), and does not search the literature (use `pubmed-summariser`).

## Input Formats

| Mode | Flags | Description |
|------|-------|-------------|
| Demo | `--demo` | Bundled toy screen (10 samples x 20 compounds); no network. |
| Custom | `--bundle`, `--schema`, `--objective` | User bundle directory + YAML configs. |

Bundle layout (paths resolved through `schema.yaml`):

```
bundle/
├── readouts/primary.csv          # samples (rows) x wells (cols) raw readout
├── metadata/
│   ├── treatment_info.csv        # well_id -> compound_id, perturbation_type, ...
│   └── sample_info.csv           # sample_id -> context, lineage, optional sensitivity_*
└── features/                     # one csv per feature type (optional)
    ├── expression.csv
    └── methylation.csv
```

## Workflow

When the user asks for a repurposing-screen analysis:

1. **Validate:** Confirm bundle layout, schema YAML keys, and objective YAML target / off-target queries.
2. **Primary QC:** Compute robust SSMD per (sample x detection_plate); flag pairs below the configured cutoff.
3. **Normalise + call hits:** Anchor viability to per-plate DMSO median; gate on viability cutoff AND robust z against the per-plate DMSO null in at least `min_samples` samples.
4. **Classify selectivity:** Apply target / off-target queries from `objective.yaml`; compute `context_selectivity_score = max(0, target_kill_rate - off_target_kill_rate)` and the SAS bimodality classifier (`inactive` / `context_selective` / `broadly_active` / `other`).
5. **Biomarker sweep:** For each `features/*.csv`, Spearman per (compound, feature) with BH-FDR across the panel.
6. **Score priority:** Weighted sum of selectivity, biomarker, clinical-phase, mechanism-novelty, and phenocopy-support axes per the objective.
7. **Write artefacts:** `report.md`, `report.html`, `result.json`, `tables/*.csv`, `cache/*.parquet`, `reproducibility/{commands.sh, environment.yml, schema.yaml, objective.yaml}`.

**Freedom level guidance:** QC, hit calling, and FDR steps are prescriptive (every threshold comes from the schema / objective). Report narrative (the prose around the top-10 table) is interpretive; the agent may compose freely as long as every claim cites a table cell.

## CLI Reference

```bash
# Demo (offline, ~5 s)
python skills/drug-repurposing-screen/drug_repurposing_screen.py --demo --output /tmp/drs_demo

# Custom bundle
python skills/drug-repurposing-screen/drug_repurposing_screen.py \
  --bundle ./my_screen --schema ./my_screen/schema.yaml \
  --objective ./my_screen/objective.yaml --output ./out

# Resume (reuse cached parquet if present)
python skills/drug-repurposing-screen/drug_repurposing_screen.py \
  --bundle ./my_screen --schema ./my_screen/schema.yaml \
  --objective ./my_screen/objective.yaml --output ./out --resume

# Via ClawBio runner
python clawbio.py run repurposing --demo --output /tmp/drs_demo
```

## Demo

```bash
python clawbio.py run repurposing --demo --output /tmp/drs_demo
```

Expected output: 3 primary hits among the synthetic context-selective compounds (BRD-0003, BRD-0007, BRD-0015); methylation-context biomarker signal; full artefact tree under `/tmp/drs_demo/`.

## Algorithm / Methodology

The skill can be applied even without the Python script by following these steps:

1. **Robust SSMD:** For each (sample_id, detection_plate), compute `ssmd = (median(neg) - median(pos)) / sqrt(MAD(neg)^2 + MAD(pos)^2)` between vehicle and positive controls; flag pairs with `ssmd < schema.qc.ssmd_cutoff` (default 1.5).
2. **Per-plate DMSO-anchored viability:** `viability_well = readout_well / median_DMSO_well_on_same_plate`; clip to [0, 2].
3. **Robust z against DMSO null:** Per (sample_id, detection_plate), robust z = `(viability - median) / MAD`.
4. **Hit call:** A compound is a hit if `viability < schema.hit_calling.viability_cutoff` (default 0.5) AND `robust_z < schema.hit_calling.robust_z_cutoff` (default -2.0) in at least `schema.hit_calling.min_samples` samples (default 3).
5. **Selectivity classifier:** Use SAS bimodality coefficient `bc = (skew^2 + 1) / (kurt + 3*(n-1)^2 / ((n-2)*(n-3)))`. Class is `context_selective` when `0.15 <= kill_rate < 0.7` and `bc >= 0.55`; `broadly_active` when `kill_rate >= 0.7` and `median_viability > 0.35`; `inactive` when `kill_rate < 0.15`; else `other`.
6. **Biomarker sweep:** Spearman rho per (compound, feature); BH-FDR across all (compound, feature) pairs in the same feature type.
7. **Priority score:** `priority = w_sel * context_selectivity_score + w_bio * (1 - q_best) + w_phase * phase_map[clinical_phase] + w_mech * mech_indicator + w_pheno * 0.5`, weights from `objective.priority_weights`.

**Key thresholds / parameters** (all overridable via schema / objective):

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio