From a3969da465664f41d50de653bb298de7c91a2f0f Mon Sep 17 00:00:00 2001
From: Victor Lin <vlin@fredhutch.org>
Date: Wed, 15 Jul 2026 10:50:13 -0700
Subject: [PATCH] Use CLI argument strings in config

Command-line parameters for filter, refine, ancestral, traits, and
tip_frequencies are now defined as a single argument string under
rule.build in config. This reverts "Use 'refine.build.option' pattern"
(eed11d0b) and provides a consistent and flexible pattern for passing
non-file arguments to Augur.
---
 CHANGELOG.md                               |   1 +
 phylogenetic/defaults/config.yaml          | 102 +++++++++++++++------
 phylogenetic/rules/annotate_phylogeny.smk  |  14 +--
 phylogenetic/rules/construct_phylogeny.smk |  20 +---
 phylogenetic/rules/export.smk              |  13 +--
 phylogenetic/rules/prepare_sequences.smk   |  15 +--
 6 files changed, 88 insertions(+), 77 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 04d3b40..06a75d7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@ the outputs of the workflows.
 
 ## 2026
 
+* 20 July 2026: Command-line parameters for `filter`, `refine`, `ancestral`, `traits`, and `tip_frequencies` are now defined as a single argument string under `<rule>.<build>` in config. This reverts the change from 14 July 2026 and provides a consistent and flexible pattern for passing **non-file** arguments to Augur **This is a breaking change**.
 * 14 July 2026: The refine option for clock filtering has moved from `refine.<build>: "--clock-filter-iqd <N>"` to `refine.<build>.clock_filter_iqd: <N>`. **This is a breaking change**.
 * 14 July 2026: The following refine options can be configured using `refine.<build>.<option>`: `coalescent`, `date_inference`, `timetree`, `date_confidence`, `clock_filter_iqd`, `divergence_units`.
 
diff --git a/phylogenetic/defaults/config.yaml b/phylogenetic/defaults/config.yaml
index 7f03592..1a25445 100644
--- a/phylogenetic/defaults/config.yaml
+++ b/phylogenetic/defaults/config.yaml
@@ -10,39 +10,74 @@ inputs:
 strain_id_field: "accession"
 reference: "reference.gb"
 
+
+####### Rule-specific parameters #######
+#
+# Most parameters are configured in argument strings given to Augur's command
+# line interface. See each command's reference page for detailed usage docs.
+#
+#   <rule>:
+#     <build>: <argument string>
+#
+# Strings can be formatted across multiple lines in YAML for readability. The '>'
+# block style indicator replaces newlines with spaces, and the '-' block chomping
+# indicator strips trailing newlines.
+#
+# File references have dedicated YAML config parameters. While they are
+# mentioned on Augur command reference pages, they should *not* be configured in
+# argument strings, but instead using their dedicated YAML config parameters.
+# They can be customized per build by referencing '{build}' in the path.
+
+# https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/filter.html
 filter:
-  min_length: 8000
-  group_by: country year month MuV_genotype division
   exclude: "{build}/exclude.txt"
   include: "{build}/include.txt"
-  specific:
-    north-america: --subsample-max-sequences 4000 --min-date 2006 --query "region=='North America' & (MuV_genotype=='G')"
-    global: --subsample-max-sequences 4000 --min-date 1950
+  north-america: >-
+    --min-length 8000
+    --group-by country year month MuV_genotype division
+    --subsample-max-sequences 4000
+    --min-date 2006
+    --query "region=='North America' & (MuV_genotype=='G')"
+  global: >-
+    --min-length 8000
+    --group-by country year month MuV_genotype division
+    --subsample-max-sequences 4000
+    --min-date 1950
 
+# https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/refine.html
 refine:
-  north-america:
-    coalescent: "opt"
-    date_inference: "marginal"
-    timetree: true
-    date_confidence: true
-    clock_filter_iqd: 4
-    divergence_units: "mutations-per-site"
-  global:
-    coalescent: "opt"
-    date_inference: "marginal"
-    timetree: true
-    date_confidence: true
-    clock_filter_iqd: null
-    divergence_units: "mutations-per-site"
+  north-america: >-
+    --coalescent "opt"
+    --date-inference "marginal"
+    --timetree
+    --date-confidence
+    --clock-filter-iqd 4
+    --divergence-units "mutations-per-site"
+  global: >-
+    --coalescent "opt"
+    --date-inference "marginal"
+    --timetree
+    --date-confidence
+    --divergence-units "mutations-per-site"
 
+# https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/ancestral.html
 ancestral:
-  inference: "joint"
   root_sequence: "reference.gb"
+  north-america: >-
+    --inference "joint"
+  global: >-
+    --inference "joint"
 
+# https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/traits.html
 traits:
-  north-america: country division MuV_genotype MuV_genotype_nextclade_sh MuV_genotype_nextclade_genome
-  global: region MuV_genotype MuV_genotype_nextclade_sh MuV_genotype_nextclade_genome
-  sampling_bias_correction: 3
+  north-america: >-
+    --columns country division MuV_genotype MuV_genotype_nextclade_sh MuV_genotype_nextclade_genome
+    --sampling-bias-correction 3
+    --confidence
+  global: >-
+    --columns region MuV_genotype MuV_genotype_nextclade_sh MuV_genotype_nextclade_genome
+    --sampling-bias-correction 3
+    --confidence
 
 colors:
   color_schemes: "color_schemes.tsv"
@@ -53,10 +88,19 @@ export:
   auspice_config: "{build}/auspice_config.json"
   description: "description.md"
 
+# https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/frequencies.html
 tip_frequencies:
-  # 2006 since there is an increase in mumps samples at that time
-  min_date: "2006-01-01"
-  max_date: "12M"
-  # Quarterly narrow_bandwidth or every 3 months (3 /12.0 = 0.25)
-  narrow_bandwidth: 0.25
-  proportion_wide: 0.0
\ No newline at end of file
+  # --min-date: 2006 since there is an increase in mumps samples at that time
+  # --narrow-bandwidth: Quarterly or every 3 months (3 /12.0 = 0.25)
+  north-america: >-
+    --min-date "2006-01-01"
+    --max-date "12M"
+    --narrow-bandwidth 0.25
+    --proportion-wide 0.0
+    --method kde
+  global: >-
+    --min-date "2006-01-01"
+    --max-date "12M"
+    --narrow-bandwidth 0.25
+    --proportion-wide 0.0
+    --method kde
diff --git a/phylogenetic/rules/annotate_phylogeny.smk b/phylogenetic/rules/annotate_phylogeny.smk
index 1cf71ab..d56ada2 100644
--- a/phylogenetic/rules/annotate_phylogeny.smk
+++ b/phylogenetic/rules/annotate_phylogeny.smk
@@ -44,7 +44,7 @@ rule ancestral:
     benchmark:
         "benchmarks/{build}/ancestral.txt",
     params:
-        inference = config["ancestral"]["inference"],
+        args = lambda w: config["ancestral"][w.build],
         root_sequence=lambda w: (
             ("--root-sequence " + resolve_config_path(config["ancestral"]["root_sequence"])(w))
             if config["ancestral"].get("root_sequence")
@@ -59,7 +59,7 @@ rule ancestral:
             --alignment {input.alignment:q} \
             --output-node-data {output.node_data:q} \
             {params.root_sequence} \
-            --inference {params.inference:q}
+            {params.args}
         """
 
 rule translate:
@@ -87,8 +87,7 @@ rule translate:
 
 rule traits:
     """
-    Inferring ancestral traits for {params.columns!s}
-      - increase uncertainty of reconstruction by {params.sampling_bias_correction} to partially account for sampling bias
+    Inferring ancestral traits
     """
     input:
         tree = "results/{build}/tree.nwk",
@@ -100,8 +99,7 @@ rule traits:
     benchmark:
         "benchmarks/{build}/traits.txt",
     params:
-        columns = lambda wildcard: config['traits'][wildcard.build],
-        sampling_bias_correction = config["traits"]["sampling_bias_correction"],
+        args = lambda w: config['traits'][w.build],
         strain_id = config.get("strain_id_field", "strain"),
     shell:
         r"""
@@ -112,7 +110,5 @@ rule traits:
             --metadata {input.metadata:q} \
             --metadata-id-columns {params.strain_id:q} \
             --output {output.node_data:q} \
-            --columns {params.columns} \
-            --confidence \
-            --sampling-bias-correction {params.sampling_bias_correction:q}
+            {params.args}
         """
diff --git a/phylogenetic/rules/construct_phylogeny.smk b/phylogenetic/rules/construct_phylogeny.smk
index 4026e40..fcbe9ac 100644
--- a/phylogenetic/rules/construct_phylogeny.smk
+++ b/phylogenetic/rules/construct_phylogeny.smk
@@ -41,10 +41,6 @@ rule tree:
 rule refine:
     """
     Refining tree
-      - estimate timetree
-      - use {params.coalescent} coalescent timescale
-      - estimate {params.date_inference} node dates
-      - filter tips more than {params.clock_filter_iqd} IQDs from clock expectation
     """
     input:
         tree = "results/{build}/tree_raw.nwk",
@@ -58,12 +54,7 @@ rule refine:
     benchmark:
         "benchmarks/{build}/refine.txt",
     params:
-        coalescent = lambda w: conditional("--coalescent", config["refine"][w.build].get("coalescent")),
-        date_inference = lambda w: conditional("--date-inference", config["refine"][w.build].get("date_inference")),
-        timetree = lambda w: conditional("--timetree", config["refine"][w.build].get("timetree")),
-        date_confidence = lambda w: conditional("--date-confidence", config["refine"][w.build].get("date_confidence")),
-        clock_filter_iqd = lambda w: conditional("--clock-filter-iqd", config["refine"][w.build].get("clock_filter_iqd")),
-        divergence_units = lambda w: conditional("--divergence-units", config["refine"][w.build].get("divergence_units")),
+        args = lambda w: config["refine"][w.build],
         strain_id = config.get("strain_id_field", "strain"),
     shell:
         r"""
@@ -74,12 +65,7 @@ rule refine:
             --alignment {input.alignment:q} \
             --metadata {input.metadata:q} \
             --metadata-id-columns {params.strain_id:q} \
-            {params.timetree} \
-            {params.coalescent} \
-            {params.date_confidence} \
-            {params.date_inference} \
-            {params.clock_filter_iqd} \
-            {params.divergence_units} \
             --output-tree {output.tree:q} \
-            --output-node-data {output.node_data:q}
+            --output-node-data {output.node_data:q} \
+            {params.args}
         """
diff --git a/phylogenetic/rules/export.smk b/phylogenetic/rules/export.smk
index dafbe64..b62af25 100644
--- a/phylogenetic/rules/export.smk
+++ b/phylogenetic/rules/export.smk
@@ -99,23 +99,16 @@ rule tip_frequencies:
     log:
         "logs/{build}/tip_frequencies.txt"
     params:
+        args = lambda w: config["tip_frequencies"][w.build],
         strain_id = config["strain_id_field"],
-        min_date = config["tip_frequencies"]["min_date"],
-        max_date = config["tip_frequencies"]["max_date"],
-        narrow_bandwidth = config["tip_frequencies"]["narrow_bandwidth"],
-        proportion_wide = config["tip_frequencies"]["proportion_wide"]
     shell:
         r"""
         exec &> >(tee {log:q})
 
         augur frequencies \
-            --method kde \
             --tree {input.tree} \
             --metadata {input.metadata} \
             --metadata-id-columns {params.strain_id} \
-            --min-date {params.min_date} \
-            --max-date {params.max_date} \
-            --narrow-bandwidth {params.narrow_bandwidth} \
-            --proportion-wide {params.proportion_wide} \
-            --output {output.tip_freq}
+            --output {output.tip_freq} \
+            {params.args}
         """
\ No newline at end of file
diff --git a/phylogenetic/rules/prepare_sequences.smk b/phylogenetic/rules/prepare_sequences.smk
index bf1f995..c97ace2 100644
--- a/phylogenetic/rules/prepare_sequences.smk
+++ b/phylogenetic/rules/prepare_sequences.smk
@@ -24,12 +24,7 @@ See Augur's usage docs for these commands for more details.
 
 rule filter:
     """
-    Filtering to
-      - various criteria based on the auspice JSON target
-      - from {params.min_date} onwards
-      - excluding strains in {input.exclude}
-      - including strains in {input.include}
-      - minimum genome length of {params.min_length}
+    Filtering sequences
     """
     input:
         sequences = "results/sequences.fasta",
@@ -44,9 +39,7 @@ rule filter:
     benchmark:
         "benchmarks/{build}/filtered.txt",
     params:
-        min_length = config['filter']['min_length'],
-        group_by = config['filter']['group_by'],
-        filter_params = lambda wildcard: config['filter']['specific'][wildcard.build],
+        args = lambda w: config['filter'][w.build],
         strain_id = config.get("strain_id_field", "strain"),
     shell:
         r"""
@@ -60,9 +53,7 @@ rule filter:
             --include {input.include:q} \
             --output-sequences {output.sequences:q} \
             --output-metadata {output.metadata:q} \
-            --min-length {params.min_length:q} \
-            --group-by {params.group_by} \
-            {params.filter_params}
+            {params.args}
         """
 
 rule align: