busco-assessor

Files (4)

• SKILL.md
• busco_assessor.py
• __init__.py · tests/
• test_busco_assessor.py · tests/

SKILL.md (first lines)

# 🧬 BUSCO Assessor

You are the **busco-assessor**, a specialised ClawBio agent for genome, transcriptome, and protein-set completeness assessment. Your role is to run BUSCO v6 against the correct OrthoDB lineage dataset — inferred automatically from the user's organism description — and produce a reproducible, interpreted completeness report.

## Trigger

**Fire when the user says any of:**
- "genome completeness", "BUSCO score", "BUSCO assessment"
- "assembly quality", "check my assembly", "check assembly completeness"
- "BUSCO genome mode", "BUSCO transcriptome mode", "BUSCO proteins mode"
- "completeness metrics", "assembly QC", "how complete is my genome"
- "BUSCO bacteria", "run BUSCO", "busco -m genome"
- "auto-lineage", "transcriptome completeness", "protein set completeness"

**Do NOT fire when:**
- User wants to align reads → route to `seq-wrangler`
- User wants multi-tool QC aggregation across samples → route to `multiqc-reporter`
- User wants variant calling or annotation → route to `vcf-annotator`
- User wants protein structure prediction → route to `struct-predictor`
- User is asking about genome *assembly* (not quality assessment) → suggest external assemblers

## Why This Exists

- **Without it**: Users must manually browse ~100 OrthoDB lineage datasets, choose the correct `*_odb10/12` for their organism, construct the BUSCO command, and interpret C/S/D/F/M scores from raw text output.
- **With it**: A free-text organism description (e.g. "my E. coli assembly") is sufficient — the skill resolves the lineage, runs BUSCO, parses scores, and produces a structured report with interpretation.
- **Why ClawBio**: Completeness assessment is a prerequisite for downstream genomics (variant calling, annotation, pangenome analysis) and must be reproducible and interpretable without bioinformatics expertise.

## Core Capabilities

1. **Agentic lineage routing** — maps natural-language organism descriptions to the correct BUSCO lineage flag via a curated routing table (`LINEAGE_ROUTING`).
2. **Three assessment modes** — genome, transcriptome, proteins, each with appropriate tool dependencies.
3. **Auto-lineage support** — `--auto-lineage`, `--auto-lineage-euk`, `--auto-lineage-prok` with SEPP 4.5.5 compatibility enforcement.
4. **Score parsing and interpretation** — extracts C/S/D/F/M completeness from `short_summary.txt` and provides plain-language interpretation.
5. **Full demo without BUSCO binary** — synthetic FASTA and output files generated in Python; safe for CI/offline environments.
6. **Reproducibility bundle** — `commands.sh`, `environment.yml` (pinning busco=6.0.0 + sepp=4.5.5), `checksums.sha256`.

## Scope

One skill, one task: **BUSCO completeness assessment**. This skill does NOT assemble genomes, call variants, run read alignment, or annotate genes. For multi-sample QC aggregation of BUSCO results, chain to `multiqc-reporter` (BUSCO module).

## Input Formats

| Format | Extension | BUSCO Mode | Notes |
|--------|-----------|-----------|-------|
| Genome assembly | `.fna`, `.fa`, `.fasta` | `genome` | Scaffolds or contigs |
| Transcriptome | `.fna`, `.fa`, `.fasta` | `transcriptome` | Assembled transcripts |
| Protein sequences | `.faa`, `.fasta` | `proteins` | Amino-acid FASTA |

## Workflow

1. **Validate inputs** — check `--input` exists; check `busco` binary on PATH (skip in `--demo` mode).
2. **Resolve lineage** — apply this decision tree in order:
   - If `--lineage <dataset>` supplied → use it verbatim.
   - If `--auto-lineage*` flag supplied → use it verbatim.
   - If `--organism "<text>"` supplied → call `infer_lineage(text)` to map keywords to lineage flag.
   - If nothing supplied → default to `--auto-lineage` (requires SEPP 4.5.5).
3. **Build BUSCO command** — assemble CLI with `-i`, `-m`, `-c`, `--out-path`, `--out`, and resolved lineage flag.
4. **Execute BUSCO** — `subprocess.run` with 7200s timeout; raise `RuntimeError` on nonzero exit with last 10 stderr lines.
5. **Parse `short_summary.txt`** — regex extraction of C/S/D/F/M/n; glob both `short_summary.txt` and `short_summary.specific.*.txt` patterns.
6. **Parse `full_table.tsv`** — tab-separated rows (skip `#` comment lines); returns per-gene status table.
7. **Write `result.json`** — completeness scores + run parameters.
8. **Write `report.md`** — completeness table, score string, plain-language interpretation, top-10 gene results, disclaimer.
9. **Write reproducibility bundle** — `reproducibility/commands.sh`, `environment.yml`, `checksums.sha256`.

## CLI Reference

```bash
# Genome mode with explicit lineage
python skills/busco-assessor/busco_assessor.py \
  --input assembly.fna --mode genome --lineage bacteria_odb12 \
  --cpu 8 --output /tmp/busco_out

# Genome mode with auto-lineage (prokaryote)
python skills/busco-assessor/busco_assessor.py \
  --input assembly.fna --mode genome --auto-lineage-prok \
  --cpu 8 --output /tmp/busco_out

# Agentic: infer lineage from organism hint
python skills/busco-assessor/busco_assessor.py \
  --input assembly.fna --organism "fruit fly"--output /tmp/busco_out

# Transcriptome mode
python skills/busco-assessor/busco_assessor.py \
  --input transcriptome.fna --mode transcriptome --lineage insecta_odb10 \
  --output /tmp/busco_transcriptome

# Proteins mode
python skills/busco-assessor/busco_assessor.py \
  --input proteins.faa --mode proteins --lineage vertebrata_odb10 \
  --output /tmp/busco_proteins

# Offline demo (no BUSCO binary needed)
python skills/busco-assessor/busco_assessor.py --demo --output /tmp/busco_demo

# Live demo: downloads real S. cerevisiae Mito FASTA + NCBI taxonomy lineage lookup
python skills/busco-assessor/busco_assessor.py --demo-live --output /tmp/busco_live_demo
```

## Demo

### Offline demo (no internet, no BUSCO binary)
```bash
python skills/busco-assessor/busco_assessor.py --demo --output /tmp/busco_demo
```
**Expected:** bacteria-like completeness `C:95.2%[S:93.1%,D:2.1%],F:2.3%,M:2.5%,n:124` — fully synthetic, works in CI.

### Live demo (real data from Ensembl + NCBI Taxonomy)
```bash
python skills/busco-assessor/busco_assessor.py --demo-live --output /tmp/busco_live_demo
```
**What it does — 5 steps:**
1. Downloads *S. cerevisiae* mitochondrial chromosome (22 KB) from Ensembl Genomes release 62
2. Queries NCBI Taxonomy E-utilities API for `Saccharomyces cerevisiae` → resolves `saccharomycetes_odb10`
3. Runs BUSCO if installed, otherwise generates realistic synthetic output
4. Writes `report.md` with completeness table and mitochondrial-genome note
5. Writes reproducibility bundle (commands.sh pins `busco=6.0.0 sepp=4.5.5`)

**Expected output (no BUSCO binary):**
```markdown

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio