bio-metagenomics-contamination-controls

What this skill does

## Version Compatibility

Reference examples tested with: decontam 1.22+, Hostile 1.1+, Bowtie2 2.5+, Nonpareil 3.4+, pandas 2.2+, R 4.3+.

Before using code patterns, verify installed versions match. If versions differ:
- R: `packageVersion('decontam')` then `?isContaminant` to verify parameters
- CLI: `hostile --version`, `nonpareil -h` to confirm flags and indexes
- Python: `pip show <package>` then `help(module.function)` to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.

The controls define the result: an extraction blank defines the kitome for its batch/lot, a mock community defines the limit of detection and the extraction-lysis bias, and the host reference (prefer T2T-CHM13 over GRCh38) defines what host is removed. Record the extraction kit and lot, the host index, the blanks, the mock version (whole-cell vs DNA), and the reads removed at each step.

# Contamination Controls

**"Is this signal real, or did my pipeline create it?"** -> Remove host reads, define the kitome with blanks, validate with a mock, and confirm depth - because a low-biomass community can be entirely reagent contamination.
- R: `decontam::isContaminant(seqtab, conc=, neg=, method='combined')` on the classifier output table
- CLI: `hostile clean --fastq1 R1.fq.gz --fastq2 R2.fq.gz --index human-t2t-hla`

Scope: sample-level pre-analysis cleanup and controls - host depletion, kitome/blank/mock controls, decontam, depth adequacy. Adapter/quality trimming mechanics -> read-qc/adapter-trimming, read-qc/quality-filtering. MAG-level decontamination (CheckM2/GUNC chimerism, FCS-GX foreign sequence) -> genome-assembly/metagenome-assembly - a different, genome-level problem. Classification -> kraken-classification, metaphlan-profiling.

## The Single Most Important Modern Insight -- A Metagenomic Result Is a Position in a Choice-Chain

A metagenomic profile is the product of a chain of choices - extraction, host/contaminant depletion, depth, read-vs-assembly, classifier, database, normalization - and each link silently sets what is observable. The community is never observed directly; the report is the community as refracted by this pipeline. Three consequences a newcomer misses:

1. **There is no raw truth to recover.** Even the input DNA is already a biased sample of the cells (lysis bias). Cleaning the data does not get closer to the community; it changes which lens dominates. The honest framing is relative-within-a-consistent-pipeline.
2. **Absence means not-detectable-by-this-chain.** A zero is below the depth detection limit, OR not in the database, OR lost in extraction, OR removed by depletion - almost never simple biological absence. Force the question "which link is responsible?" before interpreting absence.
3. **The pipeline can manufacture the result.** In low biomass the entire community can BE the kitome; with the wrong database the profile is the database's bias; over-aggressive depletion deletes real taxa. Controls plus a consistent chain plus explicit reporting are what convert an uninterpretable number into a defensible measurement.

## Extraction Is the Experiment

Lysis efficiency is taxon-dependent: tough-walled Gram-positives (Firmicutes, *Staphylococcus*, *Enterococcus*), endospores (*Bacillus*, *Clostridium*), acid-fast *Mycobacterium*, and fungi/archaea resist lysis and are under-represented unless bead-beating is used. Gentle/enzymatic kits inflate easy-to-lyse Gram-negatives - so a Firmicutes:Bacteroidetes shift can be an extraction artifact. Extraction had the largest effect on observed composition across 21 protocols (Costea 2017 *Nat Biotechnol* 35:1069). Use bead-beating, hold one method constant across a study, validate lysis with a whole-cell mock, and report kit and lot. Note the tradeoff: aggressive bead-beating shears DNA and hurts long-read assembly, so the best extraction depends on the read-vs-assembly choice.

## Decision Tree by Scenario

| Scenario | Recommended | Why |
|----------|-------------|-----|
| Host-associated sample (gut, oral, skin, tissue) | host-deplete first (Hostile, T2T-CHM13) | host reads waste depth and leak false calls; also a data-sharing/ethics requirement |
| Low-biomass sample (skin, BAL, CSF, tissue, blood) | blanks + DNA quantification + decontam mandatory | the lower the biomass, the larger the kitome fraction |
| Novel taxa claimed in low biomass | treat as kitome until proven (canonical genera) | placenta/tumor "microbiomes" were largely kitome |
| Need limit of detection / lysis check | run a mock (ZymoBIOMICS whole-cell) | the only sample with a known answer |
| Is my depth enough for this question? | Nonpareil coverage curve | depth sets the detection limit; host depletion halves usable depth |
| Confident classifier call, odd taxon | suspect a contaminated reference | confidence is not correctness if the reference is mislabeled |
| Adapter/quality trimming | -> read-qc | this skill owns metagenomics-specific cleanup, not generic trimming |
| MAG chimerism / foreign sequence in a bin | -> genome-assembly/metagenome-assembly | genome-level decontamination is a different problem |

## Host-Read Depletion

```bash
# Hostile removes >99.5% of human reads while discarding far fewer microbial reads than naive mapping.
# Prefer the T2T-CHM13-based index over GRCh38; high-sensitivity Bowtie2 drives removal more than the reference.
hostile clean --fastq1 sample_R1.fq.gz --fastq2 sample_R2.fq.gz \
    --index human-t2t-hla --aligner bowtie2
# Report the reads removed - it is a QC metric, not a footnote. For long reads use --aligner minimap2.
```

Remove host for two reasons: analytical (depth, false positives, runtime) and ethical (raw human-associated reads carry identifiable host genotype; depleting before deposit is increasingly required). Wet-lab depletion (saponin/DNase, methyl-CpG capture) saves sequencing but adds its own bias - a genuine tradeoff.

## Identify Reagent Contaminants with decontam

**Goal:** Separate real low-abundance taxa from the kitome using blanks and DNA concentration.

**Approach:** Run decontam on the classifier output table (taxa x samples) using the frequency signal (contaminants scale inversely with input DNA) and the prevalence signal (contaminants are enriched in blanks); raise the prevalence threshold for low biomass.

```r
library(decontam)
# seqtab: samples x taxa from the Bracken/MetaPhlAn table; conc: per-sample DNA concentration; neg: TRUE for blanks.
contam <- isContaminant(seqtab, conc = dna_conc, neg = is_blank, method = 'combined', threshold = 0.1)
# Low-biomass studies: use the prevalence method at the more aggressive threshold 0.5, and inspect the calls.
contam_lowbio <- isContaminant(seqtab, neg = is_blank, method = 'prevalence', threshold = 0.5, batch = batch_id)
seqtab_clean <- seqtab[, !contam$contaminant]
```

decontam runs per batch (`batch=`) because the kitome differs by lot/run. Always inspect the called contaminants against the canonical kitome genera (*Bradyrhizobium*, *Ralstonia*, *Burkholderia*, *Pseudomonas*, *Acinetobacter*, *Sphingomonas*, *Methylobacterium*, *Stenotrophomonas*) rather than applying blindly - over-aggressive removal deletes real taxa.

## Depth Adequacy

```bash
# Nonpareil estimates how much of the community's sequence space you have sampled, without assembly or a DB.
nonpareil -s reads.fasta -T kmer -f fasta -b sample_np
# Plot the coverage-vs-effort curve in R (Nonpareil.curve); a non-detection below the implied limit is meaningless.
```

Depth is set by the question: dominant taxa need a few million reads, rare-pathogen detection sets a limit of detection, and strain SNVs need high per-genome coverage. Host depletion can silently halve usable depth - budget for it.

## Per-Method Failure Modes

### Extraction bias reported as biology
**Trigger:** a Firmicutes:Bacteroidetes shift or "low Gram-positive" co