feat: add secondary clade-like values

[ivan-aksamentov]

Resolves #984

Adds secondary (nested under primary) attributes for custom clade-like node attributes.

The secondary key-value pairs will appear in the Nextclade Web in tooltips of primary custom clade-like columns (displayed in the cells).

How to:

Modify reference tree as follows:

Add array of descriptions of secondary attributes under meta.extensions.nextclade.clade_node_attrs[].secondaryAttrs[]:

{
  "meta": {
    "extensions": {
      "nextclade": {
        "clade_node_attrs": [
          {
            "name": "Nextclade_pango",
            "displayName": "Pango lineage (Nextclade)",
            "description": "...",
            "secondaryAttrs": [
              {
                "name": "foo",
                "displayName": "Foo",
                "description": "..."
              },
              {
                "name": "bar",
                "displayName": "Bar",
                "description": "..."
              }
            ]
          }
        ]
      }
    }
  }
}

Add values (strings) to the node attribute object with the keys matching clade_node_attrs[].secondaryAttrs[].name:

{
  "name": "NODE_0000000",
  "node_attrs": {
    "Nextclade_pango": { "value": "B" },
    "foo": { "value": "Hello" },
    "bar": { "value": "42" },
  },
  "branch_attrs": {}
}

Compatibility

These changes are backwards compatible: previous versions of Nextclade don't know about secondaryAttrs field and will ignore it.

These changes are forward compatible: new versions ignore secondary attributes if secondaryAttrs property is missing, an empty array, or (for each node) if node_attrs does not contain a value for a given attributive.

[vercel]

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

Name	Status	Preview	Updated
nextclade	✅ Ready (Inspect)	Visit Preview	Sep 5, 2022 at 9:48AM (UTC)

[ivan-aksamentov]

Example tree: tree_.json.gz

[corneliusroemer]

Nice - this is really good. A definitive improvement - we could all sorts of info in the toolbox - beyond unaliased stuff.

Right now this is a simple lookup from "clade" to "value".

At some point we may want to add placement certainty - that would not map straightforwardly from "clade" to "value" because "clade" is no longer the right key here, every row could have different attributes, in the same way we show normal columns right now.

So we may also want to add a different extension type that acts as a column but instead of being shown as column, the value is put into a tooltip. Does that make sense?

This extension here will still be useful so this is just to keep you up to date about further extension needs that may arise.

[ivan-aksamentov]

@corneliusroemer

So we may also want to add a different extension type that acts as a column but instead of being shown as column, the value is put into a tooltip. Does that make sense?

This is in fact how I implemented it initially. But then you'd need to tell which primary attribute's tooltip you want to target for each secondary attribute. That is quite complex, and error prone, because it involves matching values in 3 places. But column to tooltip is a one-to-many mapping (constrained by how results table is constructed), so I later simplified it to a nested array.

Nextclade does not care what values you put, it only cares where you want to put them, i.e. the format describes placement, not meaning. You can display different sets of attributes for different rows already, by:

• adding meta descriptions for all secondary attributes to the corresponding primary attribute where it might (or might not) appear
• adding node_attr values only to rows where you want a particular secondary value to be displayed

If value is described in meta, but not found under node_attr, then it will not be shown.

Does that work for you?

[corneliusroemer]

I'm not quite sure I understand your explanation of being able to display different sets of attributes, involving meta descriptions and node_attr.

Could we go through a concrete example?

Imagine I create a new custom node attribute country. I know I can show this in a custom column. But can I make it show as a tooltip when hovering over another custom column instead? I understand that that's not possible.

But instead, I seem to be able to add the country annotation to the clade annotation as an extra meta description? Bit confused how that would look in practice.

[ivan-aksamentov]

@corneliusroemer In the first message of the PR, in JSON examples, replace "foo" with "country". Then "country: " will be shown in the tooltips of table cells of "Pango_lineage" column.

Try to follow instructions in the first message of the PR. Create a tree, try it in the app and let me know how it goes. And once you understand simple case, and if you need more complex cases, we can talk in details.