Cumulative root-to-node S1 mutation count

[trvrb]

Via Claude

Motivation

The S1_mutations coloring counts spike S1 amino-acid changes (sites 14–685). Today it's computed with augur distance --compare-to root, which compares each node's reconstructed sequence directly against the root — i.e. the number of S1 sites that currently differ from the root.

Six-plus years in, S1 sites now mutate recurrently (like flu). Under a net-vs-root count, a second hit at an already-changed site adds nothing and a reversion subtracts, so the metric saturates and looks like S1 evolution is slowing — when the underlying substitution process isn't.

Why not just use augur distance?

augur distance can't express a path sum. Every --compare-to mode (root / ancestor / pairwise) makes a single node-pair comparison and never walks/sums along branches — root mode compares each node to the root sequence once. So no combination of its flags yields "total changes accumulated from root to node." Hence a small new script.

I'd propose that we add some sort of --cumulative option to augur distance as often want this sort of cumulative counting rather than direct comparison to reference.

What this does

New scripts/root_to_node_distance.py sums the per-branch S1 distance along every edge from the root to each node, so each substitution event accrues. It doesn't reimplement the distance logic; it reuses augur's own machinery per branch:

• augur.distance.read_distance_map — load defaults/distance_maps/S1.json
• augur.distance.get_distance_between_nodes(parent, child, map) — per-branch distance, identical semantics to the current metric
• augur.reconstruct_sequences.load_alignments — the existing aligned.gene.S_withInternalNodes.fasta already holds reconstructed sequences for every node (internal + tip)

It walks the tree in iterative preorder (safe for deep trees) accumulating cumulative[child] = cumulative[parent] + branch_distance.

Gaps and ambiguities are excluded via a new "ignored_characters": ["-", "X", "N"] in S1.json, so artifactual gaps in submitted sequences can't inflate divergence.

[trvrb]

We can see that saturation is indeed occurring by comparing new cumulative S1 mutations against old S1 mutations against reference.

An interesting side note: it looks like the successful saltational trunk is not reverting as much as side branches.

[trvrb]

@huddlej --- Tagging you here mostly as FYI. This form of counting is going to be relevant for longer timescale analyses, and may be relevant to 12y H3N2 for example. I do think this eventually deserves to live as something like a --cumulative option in augur distance.

[huddlej]

Thanks, @trvrb! I added an issue to Augur describing this new feature.