align: Improve handling of duplicate reference sequence

[victorlin]

augur align will error if the reference is present in the input --sequences and also given as --reference-sequence:

Duplicate strains of "XXXXXX" detected

It is not obvious from the error message, but this is by design: if the reference is already in --sequences, --reference-name should be used.

--reference-name
strip insertions relative to reference sequence; use if the reference is already in the input sequences

--reference-sequence
Add this reference sequence to the dataset & strip insertions relative to this. Use if the reference is NOT already in the input sequences

In a standard phylogenetic workflow, when the reference sequence is available in the curated sequences input file, the workflow must explicitly exclude the reference sequence before alignment (e.g. zika). It's easy to forget this extra step, and the error is stochastic if the reference sequence is only sometimes included in --sequences due to random sampling (e.g. measles).

Possible solutions

1. Add a special error message in this case:

   Duplicate reference sequence "XXXXXX" detected. You have two options:
   1. Use --reference-name instead of --reference-sequence
   2. Remove the reference sequence from --sequences (e.g. with augur filter)
   

2. Automatically drop the reference from input sequences if --remove-reference is specified. This option currently only applies to --output, but it could easily be extended to apply to the input --sequences as well.

[joverlee521]

Totally thought I saw (2) as a solution before, but looks like I misremembered.
It was part of a commit message, from nextstrain/lassa@ee21b9f

Augur align detects the reference strain in the reference file and the curated dataset, and throws a "duplicate strain error"

Duplicate strains of "KM822127" detected

Usually I bypass this using augur align --remove-reference but this error is still showing up. Ergo, adding a postfix to the reference IDs to bypass error.

[victorlin]

I see nextstrain/lassa@ee21b9f and nextstrain/measles@25aab7d as workarounds for a flawed design. I think (2) or even by default not erroring on (identical) duplicate reference sequences would be a better design.

[kimandrews]

Yeah, I thought augur align --remove-reference was dealing with situations where the reference was randomly sampled, but now I see that is not the case. I like option 2.