feat: mark each mutation pattern match and allow patterns without clusters

[ivan-aksamentov]

• Follow-up to: feat: add mutation pattern analysis #1767
• Related to: feat: add example ebolavirus mutation pattern configs nextclade_data#456

This is a follow-up to the mutation pattern analysis, based on feedback from users who tried it on mpox and ebolavirus datasets. The sibling data pull request adds example pattern configurations for the ebolavirus datasets, covering adenosine deaminase acting on RNA (ADAR) and apolipoprotein B mRNA-editing catalytic polypeptide-like 3 (APOBEC3) editing, and an APOBEC3-like pattern with "cluster": false for the mpox datasets.

Bundibugyo ebolavirus (bdbv), example sequences with ADAR and APOBEC3 signatures:

video-bdbv-mutation-patterns.mp4

Mpox, all clades, with the APOBEC3 pattern set to "cluster": false:

video-mpox-mutation-patterns.mp4

Create:

• kb/issues/N-mutation-patterns-cluster-hidden-defaults.md: record that the cluster object fills in undocumented defaults and accepts misspelled fields
• kb/issues/N-mutation-patterns-without-reference-tree.md: record that patterns report nothing for datasets without a reference tree
• kb/issues/N-mutation-pattern-marks-hidden-in-crowded-rows.md: record that match marks are hard to find in rows with many other markers

Change: Nextclade Web now marks every mutation pattern match with its own triangle in the sequence view [src], and draws frames only for real clusters. Pattern results appear only when the view is relative to "Parent" [src], because the analysis runs on private mutations. A pattern can now state "cluster": false [src], which means the same as omitting cluster.

Context: Before this change, the web application showed only cluster frames. A pattern without cluster still produced matches in the JSON and TSV outputs, but nothing in the web application, so it looked as if the pattern did not work. The workaround, "cutoff": 0, turned every match into a one-mutation cluster. For processes that leave scattered substitutions, such as APOBEC3 editing in mpox, this filled the view with frames and the mutations tooltip with one card per match.

Justification: Scattered and clustered signatures are different questions about the same matches. Every match is always marked, so no match is hidden by the cluster rule, and a frame means a real dense group. Matches are private mutations relative to the nearest node on the reference tree, so drawing them over mutations relative to the reference or a clade founder would put them next to substitutions they were never computed from. The labeled substitutions list already follows the same rule.

Feedback addressed

• Patterns without cluster did not appear in the web application: every match now has its own mark and is listed in the mutations tooltip, with or without clustering
• "cutoff": 0 produced many one-mutation clusters: "cluster": false, or no cluster, gives the list of matches without frames, and frames appear only where a dataset asks for clusters
• Tooltips did not say that matches are relative to the parent: the mark, frame and mutations tooltips now say "private mutations relative to parent (nearest node on the reference tree)"
• Patterns were shown in every reference node view: patterns now show only in the "Parent" view, the same as labeled substitutions. The pathogen config documentation explains how to select it [src]
• Long lists of matches: the mutations tooltip shows one section per pattern with counts per substitution type, a grid of matches truncated like the other mutation lists, and one truncated line of cluster ranges [src]

Additional improvements:

• Colored markers hid the pattern marks: hovering a mark or a frame fades all other markers in every row [src], so the matches of that pattern stand out across the table
• Match marks looked like insertion markers: marks point down from the top of their lane, while insertion markers point up from the bottom of the row [src]
• Mutation badges overflowed the tooltips: the mark and frame tooltips widen to fit their badges [src]
• "cluster": true was ambiguous: it is rejected with an error that asks for windowSize and cutoff, because no window or cutoff suits every virus [src]

Work items

• Accept cluster as a cluster rule, false, or absent, and reject true; update the JSON schemas, the pathogen config documentation and the tests [src]
• Replace the cluster-only sequence view component with pattern lanes that draw a triangle for each match and a frame for each cluster [src]
• Show patterns only in the "Parent" view, in the sequence view and in the mutations tooltip; remove them from the view relative to the reference [src]
• Share the focused pattern across rows and fade the markers of other mutations and patterns [src]
• List matches, counts per substitution type and cluster ranges per pattern in the mutations tooltip [src]
• Rename the "Mutation clusters" marker height setting to "Mutation patterns", since it now covers marks and frames

Possible improvements

• Require or document the default values of the cluster object (kb/issues/N-mutation-patterns-cluster-hidden-defaults.md)
• Warn, or evaluate relative to the reference, when a dataset with patterns has no reference tree (kb/issues/N-mutation-patterns-without-reference-tree.md)
• Keep match marks visible in rows crowded with other markers (kb/issues/N-mutation-pattern-marks-hidden-in-crowded-rows.md)

Screenshots

Bundibugyo ebolavirus (bdbv), example sequences with ADAR and APOBEC3 signatures:

"Parent" view: frames mark clusters, triangles mark each match

ADAR cluster tooltip, with other markers faded in every row

Tooltip of a scattered match, with its motif

Two patterns on one sequence, each in its own lane

Mutations tooltip with one section per pattern

"Reference" view: no pattern marks, and a hint to switch to "Parent"

Mpox, all clades, with the APOBEC3 pattern set to "cluster": false:

"Parent" view with scattered APOBEC3 matches

Tooltip of an APOBEC3 match in W(G)A context

Mutations tooltip listing the matches without clusters

Zaire ebolavirus (ebov), public example sequences:

"Parent" view across the example sequences

An ADAR hypermutation cluster of T>C substitutions

A match of the second pattern (C>T in CpG context)

[github-actions]

Preview: https://nextstrain--nextclade--pr-1780.previews.neherlab.click

(ci)