Skip to content

11 — Conditional Execution#

Rule-level when conditions switch pipeline branches on config values: WGS vs WES coverage modes, optional QC gating, and downstream annotation gated on flags and thresholds.

What It Demonstrates

  • when supports bare boolean config keys (config.run_qc), string comparisons (config.sequencing_mode == "WGS"), and compound expressions with && / || / !
  • Condition-skipped rules count as satisfied for their dependents — safe to depends_on them
  • Directory inputs infer edges to producers writing under them; the report rule still uses depends_on to keep that ordering explicit
  • Read groups are set at alignment so every downstream tool (GATK included) sees proper SM tags

Pipeline Overview#

graph TD
    A[align] --> C[haplotype_caller]
    A --> D[wes_coverage]
    A --> E[wgs_coverage]
    A2[fastqc] --> F[report]
    C --> G[vep_annotate]
    G --> F
    D --> F
    E --> F

align and fastqc start in parallel. The alignment output feeds three consumers: germline variant calling and two alternative coverage rules — wgs_coverage and wes_coverage — of which exactly one runs per invocation, chosen by config.sequencing_mode. Annotation is gated on config.run_annotation && config.min_coverage >= 20, and the final report collects everything, including the QC branch.

Workflow Definition#

# examples/gallery/11_conditional_workflow.oxoflow
# 11 — Conditional Execution
# Demonstrates when-conditionals: WGS/WES mode switching, optional QC,
# and downstream gating on config flags and thresholds.

[workflow]
name = "conditional-workflow"
version = "1.0.0"
description = "Illustrates when-conditional rule execution"
author = "oxo-flow examples"

[config]
sequencing_mode = "WGS"
reference = "/ref/hg38.fa"
target_bed = ""
min_coverage = 30
run_annotation = true
run_qc = true

[defaults]
threads = 4
memory = "8G"

[[rules]]
name = "align"
input = [
    "raw/sample_R1.fq.gz",
    "raw/sample_R2.fq.gz",
]
output = ["aligned/sample.sorted.bam"]
shell = """
rg="@RG\\tID:sample\\tSM:sample\\tPL:ILLUMINA"
bwa mem -t {threads} -R "$rg" {config.reference} {input[0]} {input[1]} | samtools sort -o {output[0]}
samtools index {output[0]}
"""

[rules.resources]
threads = 8

[rules.environment]
conda = "envs/bwa.yaml"

[[rules]]
name = "fastqc"
input = [
    "raw/sample_R1.fq.gz",
    "raw/sample_R2.fq.gz",
]
output = [
    "qc/sample_R1_fastqc.html",
    "qc/sample_R2_fastqc.html",
]
shell = "fastqc {input[0]} {input[1]} -o qc/"
when = "config.run_qc"

[rules.environment]
conda = "envs/fastqc.yaml"

[[rules]]
name = "wgs_coverage"
input = ["aligned/sample.sorted.bam"]
output = ["qc/sample.mosdepth.summary.txt"]
shell = "mosdepth --quantize 0:1:10:50: qc/sample aligned/sample.sorted.bam"
when = 'config.sequencing_mode == "WGS"'

[rules.environment]
conda = "envs/mosdepth.yaml"

[[rules]]
name = "wes_coverage"
input = ["aligned/sample.sorted.bam"]
output = ["qc/sample.mosdepth.summary.txt"]
shell = "mosdepth --by {config.target_bed} qc/sample aligned/sample.sorted.bam"
when = 'config.sequencing_mode == "WES" && config.target_bed != ""'

[rules.environment]
conda = "envs/mosdepth.yaml"

[[rules]]
name = "haplotype_caller"
input = ["aligned/sample.sorted.bam"]
output = ["variants/sample.g.vcf.gz"]
shell = "gatk HaplotypeCaller --read-validation-stringency SILENT -I {input[0]} -R {config.reference} -O {output[0]} -ERC GVCF"

[rules.resources]
threads = 4

[rules.environment]
conda = "envs/gatk.yaml"

[[rules]]
name = "vep_annotate"
input = ["variants/sample.g.vcf.gz"]
output = ["annotated/sample.annotated.vcf.gz"]
shell = "vep --input_file {input[0]} --output_file {output[0]} --format vcf --vcf --offline --cache"
when = "config.run_annotation && config.min_coverage >= 20"

[rules.resources]
threads = 4

[rules.environment]
conda = "envs/vep.yaml"

[[rules]]
name = "report"
input = [
    "annotated/sample.annotated.vcf.gz",
    "qc/",
]
output = ["reports/sample_report.html"]
shell = "python scripts/report.py --vcf {input[0]} --qc qc/ --out {output[0]}"
when = "config.run_annotation && config.run_qc"
# The qc/ directory input infers edges to producers writing under it;
# depends_on keeps the ordering explicit (condition-skipped deps count
# as satisfied).
depends_on = [
    "fastqc",
    "wgs_coverage",
    "wes_coverage",
]

[rules.resources]
threads = 2

[rules.environment]
conda = "envs/report.yaml"

Running the Workflow#

Validate#

$ oxo-flow validate examples/gallery/11_conditional_workflow.oxoflow
✓ examples/gallery/11_conditional_workflow.oxoflow — 7 rules, 8 dependencies

  ⚠ Warning: The following input files do not exist:
    - raw/sample_R1.fq.gz
    - raw/sample_R2.fq.gz
    - raw/sample_R1.fq.gz
    - raw/sample_R2.fq.gz
    - qc/

The ✓ line is what matters — validate exits 0 and the workflow is well-formed. The warnings are expected here: the raw/ FASTQs and the qc/ directory don't exist until you stage real data (see the note at the bottom of this page).

Dry-Run#

$ oxo-flow dry-run examples/gallery/11_conditional_workflow.oxoflow
Plan: would run: 6 | skip: 1 | completed: 0 (DAG size: 7)
  ...
  4. wes_coverage  [skip: when condition false]
     ...
  5. wgs_coverage  [run: never completed]
     ...

Summary: 7 rules, total 30 threads declared, max 8 threads/rule
         7 rules with memory requirements

To execute:  oxo-flow run examples/gallery/11_conditional_workflow.oxoflow -j 2

The template ships with sequencing_mode = "WGS", so wes_coverage is reported as skip: when condition false while wgs_coverage stays in the plan. Note that wes_coverage still appears in the DAG — a when-skipped rule remains in the graph but counts as satisfied, which is why the report rule can depends_on both coverage variants without ever deadlocking. Flip sequencing_mode (and set a target_bed) in [config] and the dry-run flips with it.

DAG Structure#

$ oxo-flow graph examples/gallery/11_conditional_workflow.oxoflow
Workflow DAG: 7 rules, 8 dependencies
Depth: 4, Width: 3, Critical path: 4 steps

Critical path: align → haplotype_caller → vep_annotate → report

The graph command shows the template DAG (before expansion — see the gallery index note). The critical path runs through variant calling and annotation; the coverage rules and fastqc hang off it as parallel branches.

Expected Outputs#

Path Producer
aligned/sample.sorted.bam align
qc/sample_R1_fastqc.html, qc/sample_R2_fastqc.html fastqc
qc/sample.mosdepth.summary.txt wes_coverage or wgs_coverage (exactly one)
variants/sample.g.vcf.gz haplotype_caller
annotated/sample.annotated.vcf.gz vep_annotate (gated)
reports/sample_report.html report

What's Next?#

Input data and environments

Input paths under /data/references/... and raw/ are placeholders — replace them with your own data. The validate warnings about missing raw/ files and the qc/ directory are expected until real data is staged. The referenced envs/*.yaml specs ship in examples/envs/.