feat: mutations relative to arbitrary node

[ivan-aksamentov]

Resolves #991 #1237 #1142

This extends concept of private mutations (private mutations are mutations relative to the parent node on the ref tree) to a more general concept of mutations relative to an arbitrary node of interest.

The ref nodes of interest are described by the user in the .meta.extensions.nextclade.reference_nodes of the input Auspice JSON. The description can also contain constraints: we can match node to only query samples belonging to a certain clade or lineage.

Private mutations functionality is unchanged. New functionality, inputs and outputs are added on top. Though the implementation algo is largely reused.

Test

PR in data for testing: nextstrain/nextclade_data#198 (branch with the same name):

• nextstrain/flu/h1n1pdm/ha/CY121680
• nextstrain/flu/h1n1pdm/ha/MW626062
• nextstrain/flu/h1n1pdm/na/MW626056
• nextstrain/flu/h3n2/ha/CY163680
• nextstrain/flu/h3n2/ha/EPI1857216
• nextstrain/flu/h3n2/na/EPI1857215
• nextstrain/flu/vic/ha/KX058884
• nextstrain/flu/vic/na/CY073894
• nextstrain/sars-cov-2/BA.2.86
• nextstrain/sars-cov-2/BA.2
• nextstrain/sars-cov-2/wuhan-hu-1/orfs
• nextstrain/sars-cov-2/wuhan-hu-1/proteins
• nextstrain/sars-cov-2/XBB

Work items

• read input config from Auspice JSON
• calculate relative nuc mutations
• calculate relative aa mutations
• filter by clade and clade-like attributes
• output to Nextclade JSON
• output to Nextclade NDJSON
• output to TSV and CSV
• pass required data between js and wasm
• display in web app

For consideration:

• ? use regex for matching clade-like values, rather than string equality
• ? filter by gene

Inputs

Example configuration object. Put it into .meta of Auspice JSON (such that it becomes .meta.extensions.nextclade.reference_nodes)

Click to expand

{
  "extensions": {
    "nextclade": {
      "reference_nodes": [
        {
          "name": "NODE_0000659",
          "displayName": "BA.2.86 (23I)",
          "description": "Ancestral BA.2.86 sequence"
        },
        {
          "name": "XBB.1.5",
          "displayName": "XBB.1.5 (23A)",
          "description": "Ancestral XBB.1.5 sequence. Vaccine strain 2023/2024",
          "include": {
            "clade": ["23A"]
          }
        },
        {
          "name": "NODE_0000862",
          "displayName": "BA.5 (22B)",
          "description": "Ancestral BA.5 sequence. Vaccine strain 2022/2023",
          "include": {
            "clade": ["22B"]
          }
        }
      ]
    }
  }
}

• The name field should match the name field of one of the nodes on the tree.

• The displayName and description are optional arbitrary strings used for display purposes.

• The include field should be an object, which contains:

  • keys: names from the .meta.extensions.nextclade.clade_node_attrs (for clade-like attributes) or string "clade" (for the built-in clades).
  • values: a list of values of the clade-like attribute or a list of built-in clades. Only query sequences which match these attributes are considered for calculation of mutations relative to that node.

  If the include field is not present, then no constraints applied (all query sequences are considered).

Outputs

Output JSON and NDJSON

Example fragment of output json entry (entry in the .results[] array) (mutation lists are truncated for demonstration purposes)

Click to expand

{
  "relativeNucMutations": [
    {
      "refNode": {
        "name": "NODE_0000659",
        "displayName": "BA.2.86 (23I)",
        "description": "Ancestral BA.2.86 sequence"
      },
      "muts": {
        "privateSubstitutions": [
          {"pos": 404, "refNuc": "A", "qryNuc": "G"},
          {"pos": 896, "refNuc": "A", "qryNuc": "C"}
        ],
        "privateDeletions": [],
        "reversionSubstitutions": [
          {"pos": 896, "refNuc": "A", "qryNuc": "C"},
          {"pos": 3430, "refNuc": "T", "qryNuc": "G"}
        ],
        "labeledSubstitutions": [
          {
            "substitution": {"pos": 404, "refNuc": "A", "qryNuc": "G"},
            "labels": ["23A", "23D", "23F", "23B", "22F", "23E", "23H", "23G"]
          },
          {
            "substitution": {"pos": 2333, "refNuc": "C", "qryNuc": "T"},
            "labels": ["23F", "23H"]
          }
        ],
        "unlabeledSubstitutions": [
          {"pos": 4089, "refNuc": "C", "qryNuc": "T"},
          {"pos": 11344, "refNuc": "C", "qryNuc": "T"}
        ],
        "totalPrivateSubstitutions": 75,
        "totalPrivateDeletions": 0,
        "totalReversionSubstitutions": 37,
        "totalLabeledSubstitutions": 34,
        "totalUnlabeledSubstitutions": 4
      }
    }
  ],
  "relativeAaMutations": [
    {
      "refNode": {
        "name": "NODE_0000659",
        "displayName": "BA.2.86 (23I)",
        "description": "Ancestral BA.2.86 sequence"
      },
      "muts": {
        "E": {
          "privateSubstitutions": [
            {"cdsName": "E", "pos": 10, "refAa": "T", "qryAa": "A"}
          ],
          "privateDeletions": [],
          "reversionSubstitutions": [],
          "totalPrivateSubstitutions": 1,
          "totalPrivateDeletions": 0,
          "totalReversionSubstitutions": 0
        },
        "S": {
          "privateSubstitutions": [
            {"cdsName": "S", "pos": 20, "refAa": "T", "qryAa": "R"},
            {"cdsName": "S", "pos": 26, "refAa": "-", "qryAa": "S"}
          ],
          "privateDeletions": [
            {"cdsName": "S", "pos": 23, "refAa": "S"},
            {"cdsName": "S", "pos": 143, "refAa": "Y"}
          ],
          "reversionSubstitutions": [
            {"cdsName": "S", "pos": 20, "refAa": "T", "qryAa": "R"},
            {"cdsName": "S", "pos": 49, "refAa": "L", "qryAa": "S"}
          ],
          "totalPrivateSubstitutions": 39,
          "totalPrivateDeletions": 2,
          "totalReversionSubstitutions": 25
        }
      }
    }
  ]
}

Output TSV and CSV

New columns are added. Currently, 4 columns added per each additional node:

relativeMutations['{node_name}'].substitutions
relativeMutations['{node_name}'].deletions
relativeMutations['{node_name}'].aaSubstitutions
relativeMutations['{node_name}'].aaDeletions

where {node_name} is the display_name if present, or name if not.

Mutations are in the same format as in the other columns containing mutations.

Visualization in Nextclade Web

• a new dropdown "Relative to" in the table heading allows to select among "Reference", "Parent" (for private mutations, .i.e. relative to the parent node on the tree) or any of the nodes of interest defined in the tree. Sequence views will then switch to showing mutations relative to the selected node.

• "Mut" column now shows mutations (count and fill list in the tooltip) only relative to the currently selected node

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
nextclade	✅ Ready (Inspect)	Visit Preview	Jun 28, 2024 2:25pm