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"