controlFreq

A small pipeline for monitoring taxonomic contamination in laboratory control libraries over time.

The workflow extracts control libraries from sequencing runs, summarizes taxonomic assignments, and generates an HTML report with visualizations of contamination trends.

The report includes:

• Total contamination levels over time
• Taxonomic composition (plants, animals, microbes)
• Heatmaps of recurrent contaminants
• Ordination of control libraries
• DNA damage patterns of dominant taxa
• Identification of highly contaminated libraries

This allows quick detection of persistent laboratory contaminants, reagent contamination, or temporal shifts in contamination profiles.

Workflow Overview

The pipeline runs three main steps:

1. Extract control data from SMDB
2. Get metaDMG statistics from the production pipeline
3. Generate an HTML contamination report

Repository Structure

controlFreq/
│
├── README.md
│
├── scripts/
│   ├── main.sh              # main pipeline entrypoint
│   ├── getControls.R        # extracts control libraries from SMDB files
│   ├── controlFreq.Rmd      # RMarkdown report generator
│   ├── findLibrary.sh       # helper script for locating libraries
│ 
├── smdb/                    # SMDB summary tables
│
├── controls/                # aggregated control contamination tables
│
├── plots/                   # plots generated by reports
│
├── reports/                 # rendered HTML reports
│
└── tmpdir/                  # temporary files

Generated Outputs

Each run produces:

Control contamination table

controls/control_<timestamp>.tsv

Contains aggregated taxonomic assignments for control libraries.

Contamination report

reports/controlFreq_<timestamp>.html

Interactive HTML report containing:

• contamination trends
• taxonomic heatmaps
• PCoA ordination
• DNA damage plots

Figures

plots/<timestamp>/

All figures used in the report are saved separately.

Running the Pipeline

Run the pipeline using the main script:

bash scripts/main.sh

Add --push to also commit public/dashboard-data.json and push it to the current branch on the origin remote:

bash scripts/main.sh --push

This will:

1. Download the SMDB
2. Extract control libraries
3. Get metaDMG results
4. Generate the contamination report
5. Refresh public/dashboard-data.json for the React dashboard

Dependencies

R packages

tidyverse
ggplot2
ggh4x
ggrepel
vegan
patchwork
rmarkdown

Install with:

install.packages(c(
  "tidyverse",
  "ggh4x",
  "ggrepel",
  "vegan",
  "patchwork",
  "rmarkdown"
))

Example Output

The generated report includes sections such as:

• Total contamination over time
• Biological-group contamination composition
• Plant contaminants
• Animal contaminants
• Other eukaryotic contaminants
• Bacterial contaminants
• Library similarity (PCoA)
• DNA damage patterns of dominant taxa

These visualizations help identify systematic contamination sources and temporal trends in control libraries.

Notes

• Extraction positive controls are excluded from contamination summaries.
• Taxa are filtered by minimum read thresholds to reduce noise.
• Bacterial taxa are summarized at the order level due to high diversity.