Valid Auspice Config Metadata

Help and Getting Started
1

I am working to set up a custom view for Auspice. I have found the documentation and example config json files; however, I do not have a good sense of what valid inputs for some of the sections are if I want to go outside the parameters of the examples.

For example, in the ‘colorings’ subheading, if I want the ‘Clades’ color as defined during the run, must I specify it in the colorings options and if so how? I understand you can color by metadata from the metadata file, but there are additional pieces of information generated during the run, which I do not know the backend naming. The same goes for filters. I was able to find '“clade_membership” in the default auspice json, but took me awhile to think to look there.

Is there a document that has information with valid inputs for auspice: ‘display_defaults (and subheadings withing)’, ‘filters’, ‘panels’, 'colorings (those not included in metadata)?

2

Answered my own question partly:

3

Hi Mike – I think there’s two slightly different questions being asked so I’ll answer in two parts!

  1. How to define how auspice looks when loaded

For a given dataset within auspice, there is a large space of different views a user can take the viz in (e.g. changing coloring, changing the tree layout, toggling on/off different panels, zooming into the tree, selecting a time slice). A dataset (JSON) can define the defaults for a few of these and URL queries can define a lot of them – these are best explained in the “View Settings” doc page you’ve found or by looking at the dataset JSON schema. Feel free to ask questions here too!

Note that such a view must be available within the dataset – for instance, you can’t set a default coloring to “age” if age doesn’t exist as a coloring in the dataset JSON.

  1. How to make certain options (e.g. colorings) available in Auspice

In theory, the dataset JSON schema (link above) defines how one should define a particular coloring in the JSON for auspice to be able to read it. In practice, this boils down to the augur export command which is what produces the JSON file in most situations. The docs could be better here, but a good place to start is here – in essence augur export needs to be told which bits of metadata and generated data should be exported as valid colorings, and what names they should be given. This approach allows augur export to be agnostic about the tools used to generate such data.

The clades example is a good one as it’s one of the most complex :scream: (due to historical reasons). If you are running augur clades then this will produce an intermediate JSON which associates nodes on the tree with a “clade_membership” value. Normally, for this to be in the resulting dataset JSON, two things are required:

  • (i) this file is provided as an input to augur export's --node-data argument
  • (ii) a entry in the config JSON (supplied to augur export's --auspice_config argument) along the lines of
"colorings": [
      {
      "key": "clade_membership",
      "title": "Clade",
      "type": "categorical"
    }
]

BUT clades is an exeption to the general rule in that part (ii) is not needed – augur export will automagically create a coloring for Clade if it is given a suitable node data JSON which defines “clade_membership” values. This is why you don’t see such an entry in the config JSON behind nextstrain.org/ncov/global, but clade is indeed a valid coloring in that dataset.

Please don’t hesitate to ask any further questions!

4

Thanks very much! I really appreciate the extra details you provided.