distance: Add option to calculate the cumulative distance from the root node to each tip instead of the pairwise distance

[huddlej]

Context

augur distance allows users to calculate distances between the root node of a tree and each tip.

Over long time periods, reversions back to the root alleles will cause these pairwise distances to underestimate the total number of mutations that have actually occurred. This underestimation manifests as an apparent "saturation" of mutations over time.

@trvrb recently worked around this issue in the ncov workflow by adding a custom script that calculates the cumulative distance from the root to each tip rather than the pairwise distance.

Description

As @trvrb notes in his ncov PR, we could add a new cumulative option that would calculate the cumulative distance through a pre-order tree traversal instead of the pairwise distance between root and tips.

Possible solution

The actual implementation will require some prototyping, but we may want to add a new --compare-to option like cumulative that performs the desired behavior. A top-level --cumulative argument would be most useful if we wanted cumulative calculations applied for all comparisons including ancestor and pairwise. Cumulative pairwise distances doesn't seem like a real use case, though.

We could use the Claude Code code from @trvrb's PR above as a starting point for the implementation in Augur.

[huddlej]

Noting that the cumulative sum of distances is how the augur titers functions work. If we had an augur distance implementation of cumulative distances, we could estimate antigenic advance for new trees and sequences with a distance map inferred from our titer models, decoupling the process of inferring the titer model effects and annotating the antigenic advance for a tree.

Also, we've recently found H3N2 HA sequences with a HA1:N159Y substitution which reverts the Y159N substitution that defines clade G. Because we count mutations adjacent to the receptor binding site with augur distance relative to the root instead of cumulatively, these viruses with reversions appear to have one fewer RBS-adjacent substitutions when they actually have one more. Since this case occurs even in 2-year HA trees, this probably justifies switching to cumulative distances regardless of the timescale of the tree.