Bio Assembly QC

Assemble genomes/metagenomes and produce assembly QC artifacts.

Instructions

Validate the assembly manifest and inspect a restartable execution plan before starting expensive work:
```
uv run --no-project python skills/bio-assembly-qc/scripts/run_assembly_qc.py \
  assemblies.tsv --out results/bio-assembly-qc
uv run --no-project python skills/bio-assembly-qc/scripts/run_assembly_qc.py \
  assemblies.tsv --out results/bio-assembly-qc --execute
```
The driver rejects samples whose upstream read_qc_status is not passed, normalizes assembler-specific outputs to per-sample contigs.fasta, chooses QUAST versus MetaQUAST from the declared mode, and reuses only non-empty declared outputs.
Select an assembler based on read type, genome/metagenome scope, and sample diversity:
- Illumina short-read isolates and hybrid assemblies: SPAdes v4.0.0+ (final feature release; bug-fix-only series continues). Use metaSPAdes for short-read metagenomes.
- Long-read bacterial isolates (PacBio CLR, ONT): Flye v2.9.5+ for the draft/baseline assembly. Use Autocycler v0.6+ when a complete, high-confidence bacterial consensus genome is needed from multiple independent long-read assembly attempts; do not use it for mixed-community metagenomes.
- Long-read metagenomes: Flye v2.9.5+ in --meta mode (metaFlye) as the baseline for ONT/CLR mixed-community assemblies.
- HiFi metagenomes: prefer metaMDBG v1.1 (~2× more circularized high-quality MAGs vs metaFlye on HiFi, better virus/plasmid recovery; Nature Biotechnology 2024, DOI: 10.1038/s41587-023-01983-6). Keep metaFlye as a comparator when a per-sample failure mode is suspected.
- Diverse or very large long-read datasets where speed dominates: myloasm (2025) as a faster long-read metagenome assembler when its profile matches the dataset; document the choice in the run log.
Run assembly with resource-aware settings and record exact CLI, version, thread count, and RAM ceiling.
- For very large ONT/metagenome FASTQs, use /bio-reads-qc-mapping guidance for filtering and avoid redundant full-file raw-read preflights before filtering. Record raw file metadata (stat path, size, mtime), optionally run a small sampled check, and write seqkit stats after each produced read set.
- Use atomic output patterns for long-running filters and assemblies: write to .tmp, verify non-empty/readable output, then mv into the final path. Resume mode should skip existing final outputs only after sanity checks; when checks fail, use a tool-supported overwrite option or remove the corrupt final output before rerunning.
- For Flye/metaFlye failures or interrupted jobs, prefer --resume or --resume-from in the existing output directory when the prior run is structurally intact. Do not delete a large partial assembly unless logs or missing stage files show it is corrupted.
Run QUAST v5.3+ (use MetaQUAST for metagenomes) and summarize metrics.
For every produced contigs.fasta, invoke /tracking-taxonomy-updates to run the BBTools-container QuickClade percontig domain screen before choosing downstream genome/MAG/viral/eukaryotic workflows.
Use the QuickClade domain routing table to decide the next step:
- Bacteria/Archaea -> /bio-gene-calling, /bio-annotation, and GTDB-Tk taxonomy assignment.
- Viral or virus-like -> /bio-viromics before prokaryotic MAG tooling.
- Eukaryota -> eukaryote-aware gene/QC workflows and EukCC where bins or genomes are present.
- Mixed/low-confidence -> split or flag contigs before domain-specific analysis.

Quick Reference

| Task | Action | |------|--------| | Run workflow | Follow the steps in this skill and capture outputs. | | Validate inputs | Confirm required inputs and reference data exist. | | Review outputs | Inspect reports and QC gates before proceeding. | | Tool docs | See docs/README.md. |

Input Requirements

Prerequisites:

Tools declared in the project's pinned Pixi environment. See docs/README.md for expected tools.
Sufficient disk and RAM for chosen assembler. Inputs:
reads/.fastq.gz or reads/.fastq (raw or filtered reads; verify actual compression by content when suffixes are suspect).
assemblies.tsv with sample_id, mode, read1, read2, and read_qc_status; supported core modes are short_isolate, long_isolate, short_metagenome, long_metagenome, and hifi_metagenome.

Output

results/bio-assembly-qc/contigs.fasta
results/bio-assembly-qc/assembly_metrics.tsv
results/bio-assembly-qc/domain_routing.tsv
results/bio-assembly-qc/qc_report.html
results/bio-assembly-qc/logs/

Quality Gates

[ ] Assembly size range and N50 distribution meet project thresholds.
[ ] Every assembler output is normalized to a non-empty per-sample contigs.fasta before QC or downstream routing.
[ ] On failure: retry with alternative parameters; if still failing, record in report and exit non-zero.
[ ] Verify reads are present and readable. If gzip -t fails on a .gz-named file, inspect magic bytes or file type before labeling it corrupt; it may be plain FASTQ with the wrong suffix.
[ ] Check available disk space before assembly.
[ ] For large ONT/metagenome inputs, raw file metadata and post-filter seqkit stats are recorded without redundant full-file raw preflight scans.
[ ] Long-running filter outputs use .tmp plus atomic rename, and resume guards distinguish valid completed outputs from partial/corrupt files.
[ ] Flye/metaFlye logs are inspected before deciding whether to resume, rerun, or clean a partial output directory.
[ ] For Autocycler isolate consensus, record each input assembler/run and confirm the sample is not a mixed community.
[ ] QuickClade percontig domain screen completed or the reason for skipping it is explicitly recorded.
[ ] Domain routing table is reviewed before selecting MAG, viral, bacterial/archaeal, or eukaryotic downstream tools.

Examples

Example 1: Expected input layout

reads/*.fastq.gz (raw reads).
assembler choice (spades | flye).

Use fixtures/assemblies.tsv as the executable short-read, long-read, and metagenome planning fixture.

Troubleshooting

Issue: Missing inputs or reference databases Solution: Verify paths and permissions before running the workflow.

Issue: Low-quality results or failed QC gates Solution: Review reports, adjust parameters, and re-run the affected step.

Issue: Large ONT assembly workflow appears stalled before assembly Solution: Check whether the script is doing a raw full-file preflight (gzip -t, raw seqkit stats) instead of productive filtering. For urgent routing/assembly, replace raw full scans with metadata plus sampled checks, then run filtering and post-filter stats.

Issue: Flye job timed out or was interrupted Solution: Inspect flye.log and stage files. If the output directory is intact, resubmit with Flye resume options rather than restarting from scratch.