git:20260711.5ae6f6f to git:20260712.3675171

5 added, 0 removed. Audit A to A.

---

name: bio-binning-qc

description: Bin and refine metagenomic contigs, then assess MAG quality. Use when recovering genomes with QuickBin and checking completeness, contamination, and bin consistency.

---

# Bio Binning QC

Perform metagenomic binning, refinement, and QC with completeness/contamination checks.

## Instructions

1. Compute per-sample depth/coverage with CoverM v0.7.0+ (or BBMap for short reads, minimap2 for long reads).

2. Bin contigs with **QuickBin** through Bryce Foster's official BBTools container (`bryce911/bbtools:39.85`; record digest when pulled). QuickBin is high-fidelity, CheckM2-agnostic, and scales well on both short-read and long-read assemblies. On a GPU node, run **SemiBin2 v2.3.0+** instead — self-supervised contrastive learning with CUDA-backed PyTorch. MetaBAT2 v2.18+ is kept only as a legacy fallback for reproducing prior pipelines.

3. Run `/tracking-taxonomy-updates` for BBTools-container QuickClade domain triage on the bin directory and the source assembly with `percontig`. Persist the per-contig screen so mixed bins are visible.

4. Route bins by the QuickClade domain screen:

- Bacteria or Archaea -> run GTDB-Tk taxonomy assignment. If the GTDB-Tk reference package is missing, set it up under `$BIO_DB_ROOT`, export `GTDBTK_DATA_PATH`, run `gtdbtk check_install`, and record the release before classification.

- Eukaryota -> run EukCC v2.1.3+ for eukaryotic bins.

- Viral or virus-like -> remove from MAG QC and route candidate contigs/genomes to `/bio-viromics`; use vConTACT3 for phage/prokaryotic-virus evidence and GVClass for giant-virus/Nucleocytoviricota candidates.

- Mixed or low-confidence -> flag as potential chimeras and inspect per-contig assignments before QC scoring.

5. Run domain-specific QC:

- CheckM2 v1.1.0+ for bacterial and archaeal bins (v1.1.0 is a breaking upgrade: update the pinned Pixi environment and refresh the DIAMOND v3 database from Zenodo DOI 10.5281/zenodo.14897628).

- EukCC v2.1.3+ for eukaryotic bins.

- GUNC v1.0.6+ for bacterial and archaeal bins only; treat it as a complement to CheckM2 for chimerism detection. Do not apply GUNC to eukaryotic bins.

+ 6. Normalize routed outputs with `scripts/build_bin_qc_tables.py`. The join

+ rejects GUNC rows for non-prokaryotic routes and refuses prokaryotic or

+ eukaryotic bins that lack their domain-specific QC/taxonomy outputs.

## 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`. |

+ | Build normalized tables | `uv run --no-project python scripts/build_bin_qc_tables.py --routing domain_routing.tsv --checkm2 checkm2.tsv --gunc gunc.tsv --eukcc eukcc.tsv --gtdbtk gtdbtk.tsv --out-dir results/bio-binning-qc` |

## Input Requirements

Prerequisites:

- Tools declared in the project's pinned Pixi environment. See `docs/README.md` for expected tools.

- Reference DB root: set `BIO_DB_ROOT` to the project or site-local database directory.

- Coverage/depth tables or reads available to compute coverage.

- Docker or Apptainer/Singularity available for `bryce911/bbtools` QuickBin runs, or a documented local BBTools install.

Inputs:

- contigs.fasta

- coverage.tsv (per-sample depth table)

## Output

- results/bio-binning-qc/bins/

- results/bio-binning-qc/quickclade_percontig.tsv

- results/bio-binning-qc/domain_routing.tsv

- results/bio-binning-qc/gtdbtk_taxonomy.tsv

- results/bio-binning-qc/bin_metrics.tsv

- results/bio-binning-qc/bin_qc_report.html

- results/bio-binning-qc/logs/

## Quality Gates

- [ ] Completeness and contamination meet project thresholds.

- [ ] Chimera and contamination flags are below thresholds.

- [ ] On failure: retry with alternative parameters; if still failing, record in report and exit non-zero.

- [ ] Verify contigs.fasta and coverage.tsv are non-empty.

- [ ] Verify reference DBs for QC tools exist under the reference root.

- [ ] QuickClade `percontig` screen exists for the source assembly and bin set before CheckM2/EukCC/GTDB-Tk decisions.

- [ ] Bacterial and archaeal bins have GTDB-Tk taxonomy with the database release recorded.

- [ ] Viral/virus-like bins are routed to `/bio-viromics` instead of reported as MAGs.

- [ ] Mixed-domain bins are flagged as possible contamination/chimeras with per-contig evidence.

+ - [ ] Normalized `bin_metrics.tsv` and `gtdbtk_taxonomy.tsv` cover every routed bin, including explicit viral/manual-review rows.

## Examples

### Example 1: Expected input layout

```text

contigs.fasta

coverage.tsv (per-sample depth table)

```

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