Reproducible Bioinformatics with WDL & Containers

Reproducible Bioinformatics with WDL & Containers

Course: Bioinformatics & Computational Genomics — Module 7: Workflow Engineering Imagine you publish a pharmacogenomics analysis showing that a variant in CYP2D6 correlates with altered drug metabolism. Two years later, a collaborator re-runs your pipeline and gets different results. Was it a different software version? A different reference genome? A silently changed parameter? This scenario, sometimes called the reproducibility crisis in computational biology, is why modern bioinformatics pipelines are engineered for reproducibility rather than merely written as ad hoc scripts. In regulated environments—clinical genomics, pharmaceutical R&D, and biotech quality control—reproducibility is not optional; it is a regulatory and ethical requirement. Two complementary technologies solve this problem. First, containers (most commonly Docker or Apptainer/Singularity images) package a tool together with its exact operating system libraries, dependencies, and configuration. If your alignment step used a specific build of BWA and a specific version of zlib, the container guarantees those exact components on any machine, from your laptop to a cloud cluster. Second, workflow languages such as WDL (Workflow Description Language) describe the logic of your pipeline—which tasks run, in what order, with which inputs—in a declarative, human-readable format. A workflow engine like Cromwell then executes the WDL, calling the containerized tools for each task. The division of labor is important to grasp: containers solve the “which software?” problem, while WDL solves the “which logic?” problem. A container does not know that QC must precede alignment, and a WDL script does not know how FastQC was compiled. Combining them yields a pipeline that runs identically today, next year, and on a different continent—a property researchers call bitwise reproducibility when pushed to its strictest form. Below is a minimal but realistic WDL example: a quality-control workflow that runs FastQC on a set of FASTQ files. Note the three pillars of reproducible task design: pinned inputs ( File declarations), an explicit command block, and a runtime section that names the exact container image. version 1.0 task fastqc { input { File fastq } command <<< fastqc --outdir=qc_reports "~{fastq}" >>> output { File report = "qc_reports/~{basename(fastq, '.fastq.gz')}_fastqc.html" } runtime { docker: "biocontainers/fastqc:v0.11.9_cv1" memory: "2 GB" cpu: 1 } } workflow qc_pipeline { input { Array[File] fastq_files } scatter (sample in fastq_files) { call fastqc { input: fastq = sample } } output { Array[File] qc_reports = fastqc.report } } Several WDL features deserve attention. The scatter block fans the workflow out across all input files in parallel, which matters when your cohort contains hundreds of patient samples. The runtime block is where reproducibility is enforced: by pinning the Docker image tag v0.11.9_cv1 (rather than a floating latest tag), you guarantee that every execution uses the same FastQC build. The basename() function keeps output naming deterministic regardless of the input file's directory location. Now consider how the container itself is built. A well-constructed Dockerfile records every installation decision, and—crucially—pins version numbers so the image can be rebuilt identically if the original image ever disappears from a registry: FROM ubuntu:22.04 ENV DEBIAN_FRONTEND=noninteractive RUN apt-get update && apt-get install -y --no-install-recommends \ fastqc=0.11.9+dfsg-6 \ samtools=1.16.1-1 \ default-jre-headless \ && rm -rf /var/lib/apt/lists/* WORKDIR /data CMD ["/bin/bash"] Every line of this Dockerfile is a documentation artifact. FROM ubuntu:22.04 pins the base operating system; the version-pinned apt-get install lines freeze tool versions; and removing the package cache keeps the image small. In practice, teams push such images to a registry (Docker Hub, Quay.io, or Google Artifact Registry) and reference them by digest —an immutable cryptographic hash—in their WDL runtime blocks for maximum rigor. Combined with version-controlled WDL files in Git, this produces a pipeline whose entire software stack and logic can be restored from a single repository snapshot. For pharmacy and biotech applications, the payoff is concrete: a bioequivalence study's variant-calling results can be audited years later; a companion diagnostic assay can be validated once and deployed identically across clinical laboratories; and a publication's methods section becomes a one-line statement—“run with WDL version X and container digest Y”—instead of a fragile list of installation instructions. Containers (Docker/Apptainer) freeze the software environment; WDL freezes the analytical logic—together they enable true reproducibility. Always pin container image tags or digests in the WDL runtime block; never rely on floating tags like latest . WDL's task , workflow , scatter , and output blocks let an engine like Cromwell orchestrate parallel, scalable executions. A version-pinned Dockerfile doubles as human-readable documentation of your software environment. Version-controlling WDL files (Git) alongside container digests creates a complete, restorable snapshot of a pipeline. Practice exercise: Using the WDL syntax above as a template, write a new task called call_variants that runs bcftools mpileup and bcftools call on an input BAM file and its reference FASTA, declares both as File inputs, outputs the resulting VCF, and pins a specific bcftools container image of your choosing in the runtime block. Then write a one-task workflow that calls it, and briefly explain (2–3 sentences) why replacing quay.io/biocontainers/bcftools:latest with a pinned digest matters for a clinical pharmacogenomics pipeline.