busco-assessor

🧬 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

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

# 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)

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)

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

Lineage: saccharomycetes_odb10   [NCBI Taxonomy API]
C:2.1%[S:2.1%,D:0.0%],F:0.9%,M:97.0%,n:2137

The low completeness (2.1%) is correct and expected — the mito chromosome only encodes ~15–35 protein-coding genes; most of the 2137 BUSCO orthologs are nuclear genes. This is an educational feature, not a bug.

NCBI Taxonomy Integration

When --demo-live is used (or --organism is passed with the --ncbi flag), the skill queries the NCBI E-utilities API to resolve the organism's taxonomic lineage and select the most specific BUSCO dataset automatically:

esearch  → https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=taxonomy&term={name}&retmode=json
            returns: {"esearchresult": {"idlist": ["4932"]}}

efetch   → https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=taxonomy&id=4932&retmode=xml
            returns: XML with <LineageEx> containing {rank, ScientificName} pairs

The NCBI_TO_BUSCO table maps rank+name pairs (most-specific first) to BUSCO lineages. For S. cerevisiae:

• class Saccharomycetes → saccharomycetes_odb10 (2137 BUSCOs)

Network errors fall back gracefully to keyword-based infer_lineage() — no exception raised.

Agentic Lineage Routing

The --organism flag is the primary agentic bridge. The LLM agent passes a free-text organism description; the skill resolves it to a BUSCO flag using the LINEAGE_ROUTING keyword table:

Algorithm / Methodology

1. BUSCO v6 searches input sequences against HMM profiles of single-copy orthologs from OrthoDB.
2. Each ortholog is classified: Complete (score and length within expected range) → Single-copy (S) or Duplicated (D); Fragmented (F) (score within range, length below threshold); Missing (M) (no significant hit).
3. Completeness percentage = (C + F) / n × 100. C alone is the primary quality metric.
4. Auto-lineage uses SEPP placement of marker genes to identify the correct clade; requires SEPP exactly 4.5.5.
5. OrthoDB10 datasets cover eukaryotes; OrthoDB12 covers prokaryotes and archaea — do not mix suffixes.

Example Queries

• "Check the completeness of my bacteria genome assembly"
• "Run BUSCO on my Drosophila transcriptome using diptera lineage"
• "What is the BUSCO score for this human genome assembly?"
• "Run BUSCO in proteins mode with the vertebrata lineage"
• "Show me a BUSCO demo with synthetic data"
• "BUSCO assessment with auto-lineage prokaryote mode on my E. coli assembly"

Example Output

# BUSCO Assessor Report

**Date**: 2026-04-23 10:00 UTC
**Mode**: genome (demo)
**Lineage**: bacteria_odb12
**Input**: demo_assembly.fna (5 sequences)

## Completeness Summary

| Metric | Count | Percentage |
|--------|-------|-----------|
| Complete (C) | 118 | 95.2% |
|   Single-copy (S) | 115 | 93.1% |
|   Duplicated (D) | 3 | 2.1% |
| Fragmented (F) | 3 | 2.3% |
| Missing (M) | 3 | 2.5% |
| Total searched (n) | 124 | — |

**Score string**: `C:95.2%[S:93.1%,D:2.1%],F:2.3%,M:2.5%,n:124`

## Interpretation

High completeness (95.2% C) indicates a near-complete assembly for this lineage.
Duplication rate of 2.1% is within expected range.

## Top Gene Results (first 10)
| BUSCO ID | Status | Sequence | Score | Length |
|----------|--------|----------|-------|--------|
| 1098at2  | Complete   | seq1 | 742.3 | 312 |
| 1099at2  | Complete   | seq1 | 698.1 | 287 |
| 1103at2  | Fragmented | seq2 | 341.2 |  98 |
| 1104at2  | Missing    | N/A  |   0.0 |   0 |

*ClawBio is a research and educational tool. It is not a medical device...*

Output Structure

output_dir/
├── report.md                        # PRIMARY: completeness report
├── result.json                      # scores, lineage, mode, run parameters
├── busco_run/
│   ├── short_summary.txt            # BUSCO score summary (raw BUSCO format)
│   ├── short_summary.json           # Structured score summary
│   └── full_table.tsv               # Per-gene completeness table
└── reproducibility/
    ├── commands.sh                  # Exact replay command
    ├── environment.yml              # Pins busco=6.0.0, sepp=4.5.5
    └── checksums.sha256             # SHA-256 of all output files

Dependencies

Required (runtime; not needed for --demo)

Optional

Install (conda — recommended):

conda create -n busco_env -c conda-forge -c bioconda busco=6.0.0 sepp=4.5.5
conda activate busco_env

Gotchas

1. SEPP version must be exactly 4.5.5. SEPP v4.5.6 is incompatible with BUSCO auto-lineage files and produces wrong lineage assignments silently. Always pin sepp=4.5.5 in environment.yml.

2. Do NOT mix OrthoDB10 and OrthoDB12 lineage suffixes. Eukaryote lineages use _odb10; prokaryote/archaea lineages use _odb12. Passing bacteria_odb10 (non-existent) fails; passing primates_odb12 (non-existent) fails. The lineage suffix must match the domain.

3. BUSCO v6 changed the short_summary filename. Depending on the BUSCO version and configuration, the file may be named short_summary.txt or short_summary.specific.<lineage>.<run>.txt. Always glob for both patterns — never hardcode the filename.

4. Demo mode must never invoke the BUSCO binary. run_demo() generates all output files synthetically in Python. Do not add BUSCO subprocess calls to the demo path; it must work in CI environments without any bioinformatics tools installed.

5. Proteins mode with a nucleotide FASTA returns zero hits silently. If --mode proteins is specified with a .fna/.fa file, BUSCO will complete successfully but report 0% completeness. The script emits a WARNING in this case; always use .faa (amino-acid FASTA) for proteins mode.

Safety

• Local-first: All processing is local. No sequence data is uploaded to external services. Lineage datasets are downloaded from BUSCO servers only when the BUSCO binary is running and --download_path is specified.
• No hallucinated scores: The agent must NOT invent completeness percentages, lineage names, or gene counts. All numbers in the report derive from parsing BUSCO output or the synthetic demo constants.
• Disclaimer: Every generated report.md ends with: "ClawBio is a research and educational tool. It is not a medical device and does not provide clinical diagnoses. Consult a healthcare professional before making any medical decisions."

Agent Boundary

• Agent dispatches: FASTA file path, --mode, --organism (free-text hint), optional explicit --lineage or --auto-lineage* flags.
• Skill executes: Lineage resolution, BUSCO command construction, subprocess management, output parsing, report writing.
• Agent explains: Results to the user, including what the completeness scores mean for their specific use case.
• Agent must NOT: Override the routing table with guessed lineage names, invent BUSCO score numbers, or run BUSCO commands manually outside this skill.

Integration with Bio Orchestrator

Trigger conditions for routing here:

• User mentions "genome completeness", "BUSCO score", "assembly quality", or "assembly QC"
• User has produced a FASTA file from an assembler (Flye, SPAdes, Hifiasm, etc.)
• User asks "how complete is my assembly/transcriptome/protein set"

Chaining partners:

Output is chainable: result.json is machine-readable JSON; busco_run/short_summary.txt is directly readable by MultiQC's BUSCO module.

Maintenance

• Review cadence: Monthly or on new BUSCO major release.
• Staleness signals: Auto-lineage tests fail; OrthoDB download URLs change; new _odb13 datasets released; SEPP constraint changes.
• Update LINEAGE_ROUTING when new OrthoDB versions introduce new clade-specific datasets or rename existing ones.
• Deprecation path: Move to skills/_deprecated/busco-assessor/ if BUSCO v7 introduces breaking CLI changes that require a full rewrite.

Citations

• Manni M. et al. (2021). BUSCO Update: Novel and Streamlined Workflows along with Broader and Deeper Phylogenetic Coverage. Molecular Biology and Evolution. https://doi.org/10.1093/molbev/msab199
• Simão F.A. et al. (2015). BUSCO: assessing genome assembly and annotation completeness with single-copy orthologs. Bioinformatics. https://doi.org/10.1093/bioinformatics/btv351
• OrthoDB v10/v12: https://www.orthodb.org/
• BUSCO GitLab: https://gitlab.com/ezlab/busco
• BUSCO User Guide v6: https://busco.ezlab.org/busco_userguide.html