Auspice

Auspice

  • Docs

›Advanced Functionality

Introduction

  • Overview
  • Install Auspice
  • How to Run Auspice

Advanced Functionality

  • Displaying multiple trees
  • View Settings
  • Adding extra metadata via CSV/TSV
  • Miscellaneous

Customising Auspice

  • Customising Auspice
  • Client Customisation API
  • Requests Made from the Client

Using a Custom Server

  • Auspice servers
  • Server API
  • Authentication

Narratives

  • Communicating Results Using Narratives
  • Writing a Narrative
  • Converting a narrative to PDF

Release Notes

  • Changelog
  • Auspice Version 2.0

Contributing

  • Contributing to Auspice

View Settings

View settings refer to things such as how we display the tree (radal? root-to-tip?), what panels we display (map? tree? both?), what colouring we are using etcetera. There are three ways these can be controlled:

  1. The defaults are configured by the dataset creators (and stored as "display defaults" in the dataset JSON). This allows
  2. Interacting with the visualisation (e.g. changing the color-by) modifies the view, and the URL is changed accordingly. For instance, change nextstrain.org/zika to have a color-by of author, and you'll see the URL silently update to ?c=author. If you reload the page or share this URL, then the color-by is set via this URL.
  3. Narratives, in which the narrative author chooses different "views" for each page, are created by associating each page with a URL (see (2)) which defines a specific view into the data.

Auspice (hardcoded) defaults

Auspice has some hardcoded defaults, largely for historical reasons. Each of these can be overridden by the JSON display_defaults, and then the view can be further modified by the URL query (see below).

  • Default phylogeny layout is rectangular.
  • Default phylogeny distance measure is time, if available.
  • Default geographic resolution is "country", if available.
  • Default colouring is "country", if available.
  • Default branch labelling is "clade", if available.

Dataset (JSON) configurable defaults

These are exported as the (optional) property of the dataset JSON meta.display_defaults (see JSON schema here). The defaults (as set here) will be what are displayed when the page is loaded with no URL queries, but be aware that URL queries (see below) can modify how the view looks. For instance, if you set display_defaults.color_by to country, but load the page with ?c=region then the view will be coloured by region.

PropertyDescriptionExample
color_byColouring"country"
geo_resolutionGeographic resolution"country"
distance_measurePhylogeny x-axis measure"div" or "num_date"
map_triplicateShould the map repeat, so that you can pan further in each direction?Boolean
layoutTree layout"rect", "radial", "clock" or "unrooted
branch_labelWhich set of branch labels are to be displayed"aa", "lineage"

Furthermore, a JSON property meta.panels lists which panels auspice displays. If this is not included, then auspice tries to display as many as possible. See the JSON schema for more details.

See this in action:

For instance, go to nextstrain.org/flu/seasonal/h3n2/ha/2y and you'll see how the colouring is "Clade" -- this has been set via the display_defaults in the JSON.

URL query options

URL queries are the part of the URL coming after the ? character, and typically consist of key=value -- for instance nextstrain.org/zika?c=author has a query with a key c and value author. Multiple queries are separated by the & character. All URL queries modify the view away from the default settings -- if you change back to a default then that URL query will dissapear.

KeyDescriptionExample(s)
cColouring to usec=author, c=region
rGeographic resolutionr=region
mPhylogeny x-axis measurem=div
lPhylogeny layoutl=clock
dminTemporal range (minimum)dmin=2008-05-13
dmaxTemporal range (maximum)dmax=2010-05-13
f_<name>Data filter. Multiple values per key are , separated.f_region=Oceania
dList of panels to display, , separatedd=tree,map
pPanel layout (buggy!)p=full, p=grid
gminEntropy panel zoom (minimum) boundgmin=1000
gminEntropy panel zoom (maximum) boundgmax=2000
animateAnimation settings
nNarrative page numbern=1 goes to the first page
sSelected strains=1_0199_PF
branchLabelBranch labels to displaybranchLabel=aa
labelLabeled branch that tree is zoomed tolabel=clade:B3, label=lineage:relapse
cladeDEPRECATED Labeled clade that tree is zoomed toclade=B3 should now become label=clade:B3
sidebarForce the sidebar into a certain statesidebar=closed or sidebar=open
legendForce the legend into a certain statelegend=closed or legend=open
onlyPanelsDo not display the footer / header. Useful for iframes.onlyPanels

See this in action:

For instance, go to nextstrain.org/flu/seasonal/h3n2/ha/2y?c=num_date&d=tree,map&m=div&r=region and you'll see how we've changed the coloring to a temporal scale (c=num_date), we're only showing the tree & map panels (d=tree,map), the tree x-axis is divergence (m=div) and the map resolution is region (r=region).

Last updated on 3/9/2020
← Displaying multiple treesAdding extra metadata via CSV/TSV →
  • Auspice (hardcoded) defaults
  • Dataset (JSON) configurable defaults
  • URL query options
Auspice
External Links
GitHub repoNPM packageNextstrain
Contact Us
emailtwitter
Website built by James Hadfield using Docusaurus
If you use auspice, please cite Hadfield et al., 2018
Copyright © 2014-2020 Richard Neher & Trevor Bedford