QC label for recombinant sequences

[nneune]

I would like to propose the addition of a QC label specifically for "recombinant" sequences (e.g., an "R" label). This feature should:

• Assess the number of (private) mutations and reversions in a sequence.
• Highlight and label the sequence as recombinant when the count exceeds a configurable threshold.

This will help users quickly identify sequences that are likely recombinant and may require special attention in downstream analyses.

Details:

• The threshold for labeling should be adjustable/configurable.
• The label should be visible in the QC results and ideally in the output reports.
• Optionally, provide a summary or explanation for sequences that receive the label (e.g., why it was labeled recombinant).

Let me know if you need further details or use case examples 😊

[ivan-aksamentov]

Playing with AI slop. Different recombination detection strategies from Claude:

• A: Weighted Threshold - PR, preview
• B: Spatial Uniformity - PR, preview
• C: Cluster Gaps - PR, preview
• D: Reversion Clustering - PR, preview
• E: Multi-Ancestor - PR, preview
• F: Label Switching - PR, preview

[nneune]

Hi Ivan,
Thanks for creating all these strategies.
I like a few of them, but none are exactly what we are looking for.
The key features for catching recombinant sequences are probably:

• A high number of reversions
• A high number of private mutations (labeled > unlabeled) in specific parts of the genome. This could only look at labeled mutations or both, or in case the nucMutLabelMap is not defined, only unlabeled (private) mutations.
• A higher number of SNP clusters (although they could all be counted as one cluster).

Ideally, I would like a combination of strategies F (labeled mutations), D (reversions per segment), and B (mutations per segment). Something like strategy C could potentially work, but I'm not sure what "gap size" means.
I liked the idea of strategy E, but having references for all sequences for the ref_nodes.search is not feasible. Is there a way to do this without defining ancestors in ref_nodes.search?

Also, could we keep the QC parameters simpler? For example:

{
  "qc": {
    "recombinants": {
      "enabled": true,
      "numSegments": 10,
      "labeledMutsThreshold": 50,
      "privateMuts":  100,
      "snpCluster": 3,
      "scoreWeight": 100.0
    }
  }
}

I think the goal is to keep it simple yet sensitive.

Claude made a table for me: 😃

Strategy	Title	Your Need	Fit
A	Weighted Threshold	General scoring	⚠️ Too generic
B	Spatial Uniformity	Mutation distribution per segment	✓✓ Detects clustering
C	Cluster Gaps	Gap-based SNP detection	✓ For clustering (if gap = max distance)
D	Reversion Clustering	Reversions per segment	✓✓✓ Direct match
E	Multi-Ancestor	Requires ancestor references	✗ Already ruled out
F	Label Switching	Labeled mutation patterns	✓✓ Detects mutation switching (recombination signature)

[ivan-aksamentov]

@nneune

I combined strategies B, C, D, F in #1742

They can be individually enabled or disabled in pathogen.json. See example dataset in the PR.

---

What does "gap size" mean in Strategy C?

Gap size (bad term; need renaming) is the distance in nucleotides between consecutive SNP clusters. Strategy C looks for multiple distinct mutation clusters separated by large gaps - the idea being that recombinants have high-mutation regions (from divergent parent) alternating with low-mutation regions (from closer parent). The minGapSize parameter (default: 1000 nt) sets the minimum gap required to consider clusters as distinct. If two clusters are closer than this, they're effectively treated as one continuous region.

Is there a way to use Strategy E without defining ancestors in ref_nodes.search?

Not sure. Indeed, this seems theoretically okay, but impractical in reality.

Can the QC parameters be simpler?

Currently I combined the params for separate strategies as sub-objects. For me it seems clearer, compared to mixing it all together. Strategies can also be toggled on and off independently this way. And it's easier in the code - each strategy function receives its own sub-object. But feel free to propose a simpler option if you want something else. In your proposed option there's not all params involved? What happens to the rest of them?

---

The open question: how to combine scores from individual strategies into a single score. Currently it's a weighted sum (weight inside each strategy).