auspice
Version:
Web app for visualizing pathogen evolution
209 lines (202 loc) • 41.2 kB
HTML
<html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Auspice Version 2.0 · Auspice</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="## What's New"/><meta name="docsearch:language" content="en"/><meta property="og:title" content="Auspice Version 2.0 · Auspice"/><meta property="og:type" content="website"/><meta property="og:url" content="https://nextstrain.github.io/auspice/"/><meta property="og:description" content="## What's New"/><meta property="og:image" content="https://nextstrain.github.io/auspice/img/icon.svg"/><meta name="twitter:card" content="summary"/><meta name="twitter:image" content="https://nextstrain.github.io/auspice/img/icon.svg"/><link rel="shortcut icon" href="/auspice/img/favicon.ico"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-dark.min.css"/><script type="text/javascript" src="https://buttons.github.io/buttons.js"></script><script src="/auspice/js/scrollSpy.js"></script><link rel="stylesheet" href="/auspice/css/main.css"/><script src="/auspice/js/codetabs.js"></script></head><body class="sideNavVisible separateOnPageNav"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/auspice/"><img class="logo" src="/auspice/img/logo-light.svg" alt="Auspice"/><h2 class="headerTitleWithLogo">Auspice</h2></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li class="siteNavGroupActive"><a href="/auspice/introduction/overview" target="_self">Docs</a></li></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><div class="docsNavContainer" id="docsNav"><nav class="toc"><div class="toggleNav"><section class="navWrapper wrapper"><div class="navBreadcrumb wrapper"><div class="navToggle" id="navToggler"><div class="hamburger-menu"><div class="line1"></div><div class="line2"></div><div class="line3"></div></div></div><h2><i>›</i><span>Release Notes</span></h2><div class="tocToggler" id="tocToggler"><i class="icon-toc"></i></div></div><div class="navGroups"><div class="navGroup"><h3 class="navGroupCategoryTitle">Introduction</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/introduction/overview">Overview</a></li><li class="navListItem"><a class="navItem" href="/auspice/introduction/install">Install Auspice</a></li><li class="navListItem"><a class="navItem" href="/auspice/introduction/how-to-run">How to Run Auspice</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Advanced Functionality</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/advanced-functionality/second-trees">Displaying mutliple trees</a></li><li class="navListItem"><a class="navItem" href="/auspice/advanced-functionality/misc">Miscellaneous</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Customising Auspice</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/customise-client/introduction">Customising Auspice</a></li><li class="navListItem"><a class="navItem" href="/auspice/customise-client/api">Client Customisation API</a></li><li class="navListItem"><a class="navItem" href="/auspice/customise-client/requests">Requests Made from the Client</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Using a Custom Server</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/server/introduction">Auspice servers</a></li><li class="navListItem"><a class="navItem" href="/auspice/server/api">Server API</a></li><li class="navListItem"><a class="navItem" href="/auspice/server/authentication">Authentication</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Narratives</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/narratives/introduction">Communicating Results Using Narratives</a></li><li class="navListItem"><a class="navItem" href="/auspice/narratives/how-to-write">Writing a Narrative</a></li><li class="navListItem"><a class="navItem" href="/auspice/narratives/create-pdf">Converting a narrative to PDF</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Release Notes</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/releases/changelog">Changelog</a></li><li class="navListItem navListItemActive"><a class="navItem" href="/auspice/releases/v2">Auspice Version 2.0</a></li></ul></div><div class="navGroup"><h3 class="navGroupCategoryTitle">Contributing</h3><ul class=""><li class="navListItem"><a class="navItem" href="/auspice/contributing/overview">Contributing to Auspice</a></li></ul></div></div></section></div><script>
var coll = document.getElementsByClassName('collapsible');
var checkActiveCategory = true;
for (var i = 0; i < coll.length; i++) {
var links = coll[i].nextElementSibling.getElementsByTagName('*');
if (checkActiveCategory){
for (var j = 0; j < links.length; j++) {
if (links[j].classList.contains('navListItemActive')){
coll[i].nextElementSibling.classList.toggle('hide');
coll[i].childNodes[1].classList.toggle('rotate');
checkActiveCategory = false;
break;
}
}
}
coll[i].addEventListener('click', function() {
var arrow = this.childNodes[1];
arrow.classList.toggle('rotate');
var content = this.nextElementSibling;
content.classList.toggle('hide');
});
}
document.addEventListener('DOMContentLoaded', function() {
createToggler('#navToggler', '#docsNav', 'docsSliderActive');
createToggler('#tocToggler', 'body', 'tocActive');
var headings = document.querySelector('.toc-headings');
headings && headings.addEventListener('click', function(event) {
var el = event.target;
while(el !== headings){
if (el.tagName === 'A') {
document.body.classList.remove('tocActive');
break;
} else{
el = el.parentNode;
}
}
}, false);
function createToggler(togglerSelector, targetSelector, className) {
var toggler = document.querySelector(togglerSelector);
var target = document.querySelector(targetSelector);
if (!toggler) {
return;
}
toggler.onclick = function(event) {
event.preventDefault();
target.classList.toggle(className);
};
}
});
</script></nav></div><div class="container mainContainer"><div class="wrapper"><div class="post"><header class="postHeader"><h1 class="postHeaderTitle">Auspice Version 2.0</h1></header><article><div><span><h2><a class="anchor" aria-hidden="true" id="whats-new"></a><a href="#whats-new" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What's New</h2>
<ul>
<li>A new JSON format for datasets, which condenses metadata and tree data into a single JSON and allows for expanded functionality in v2.</li>
<li>A whole host of UI updates to improve Auspice's visualisations, including pie charts, better rendering of dates, and more easily accessible metadata.</li>
</ul>
<p>Read on for rationale behind this update and a detailed explanation of the changes.</p>
<p><img src="/auspice/assets/v2-pie-charts.gif" alt="auspice-v2-gif">
<em>Switching between colorings in Auspice v2</em></p>
<h2><a class="anchor" aria-hidden="true" id="backstory"></a><a href="#backstory" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Backstory</h2>
<p>Auspice started as the <a href="https://nextstrain.org">nextstrain.org</a> visualisation tool, in fact for a long time nextstrain.org <em>was</em> Auspice.
Slowly, we turned Auspice into a stand-alone tool and started expanding its capacity.
This resulted in many v1.x releases (we made it all the way to v1.39.0), and things had a habit of changing a little too frequently, with not enough focus on documentation and communication.</p>
<p>So in a way, this is the first proper Auspice release!
There are a few big and visible changes, including using pie charts to represent discrete variables on a map, but a lot of the changes were done to make things easier behind the scenes.
There are also a bunch of really cool features such as the ability to define custom servers, change the aesthetics of the Auspice client, display multiple trees and write narratives which were technically part of Auspice v1 but undocumented.
This documentation website is now up to date and should allow you to understand how to use Auspice to its full potential (<a href="/auspice/contributing/overview">contributions are always welcome!</a>)</p>
<p>In general, we hope that this documentation and the help messages of the various <code>auspice</code> subcommands are vastly improved.
The major changes which Auspice v2 brings are detailed below 👇
If you have any comments please <a href="mailto:hello@nextstrain.org">email us</a> or say hi on <a href="https://twitter.com/nextstrain">twitter</a>.</p>
<h2><a class="anchor" aria-hidden="true" id="i-dont-want-to-upgrade-how-can-i-continue-to-use-auspice-v1"></a><a href="#i-dont-want-to-upgrade-how-can-i-continue-to-use-auspice-v1" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>I don't want to upgrade - how can I continue to use Auspice v1?</h2>
<p>While we don't think there is any reason not to upgrade, version 1 will always be available via npm:</p>
<pre><code class="hljs css language-bash">npm install --global auspice@version1
</code></pre>
<h2><a class="anchor" aria-hidden="true" id="pie-charts-to-represent-discrete-variables-on-a-map"></a><a href="#pie-charts-to-represent-discrete-variables-on-a-map" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Pie charts to represent discrete variables on a map</h2>
<p>We used to use colour blending to represent all the different traits present at a given location.
This worked pretty well for continuous traits (e.g. the dates of isolates in each country), but performed poorly for discrete traits (e.g. the different flu clades present in each country).
We now use pie charts for discrete traits which give a much nicer summary of the data:</p>
<p><img src="/auspice/assets/v2-pie-charts.png" alt="pie-charts">
<em>Notice the difference? Auspice v1 (left) & v2 (right)</em></p>
<h2><a class="anchor" aria-hidden="true" id="new-dataset-json-format"></a><a href="#new-dataset-json-format" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>New dataset JSON format</h2>
<p>For about a year we've been seeing the limitations of the "v1" meta + tree JSONs (the dataset files behind Auspice).
Additionally the format of the input JSONs to Auspice changed a bit throughout the lifetime of Auspice v1 - fine when it's an internal tool, but not so great when other people start to use it!</p>
<p>We've settled on a new single "v2" JSON, containing pretty similar information to the v1 JSONs but in a format which allows us to expand the functionality of Auspice.</p>
<blockquote>
<p>Don't panic - <code>auspice view</code> and <a href="https://nextstrain.org">nextstrain.org</a> will automatically convert the "v1" JSONs into the new format for you so all of the old datasets will continue to work with Auspice v2.</p>
</blockquote>
<table>
<thead>
<tr><th>file</th><th>schema</th><th>auspice versions</th><th>description</th></tr>
</thead>
<tbody>
<tr><td>"tree" JSON</td><td><a href="https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v1-tree.json">Link</a></td><td>v1, v2</td><td>Decorated phylogenetic tree</td></tr>
<tr><td>"meta" JSON</td><td><a href="https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v1-meta.json">Link</a></td><td>v1, v2</td><td>The "metadata" associated with a phylogenetic tree</td></tr>
<tr><td>"v2" JSON</td><td><a href="https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v2.json">Link</a></td><td>v2</td><td>The single input format required for Auspice v2</td></tr>
</tbody>
</table>
<p>If you use Augur to construct your JSONs, then the next version of Augur (v6) will give you the option to produce "v1" or "v2" JSONs.
If you have specific queries, the JSON schemas (above) should help you out, but here is a list of the main changes (with links to PRs where relevent, if you're <em>really</em> keen!):</p>
<h4><a class="anchor" aria-hidden="true" id="strings-parsed-unchanged"></a><a href="#strings-parsed-unchanged" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Strings parsed unchanged</h4>
<p>For historical reasons, we used to "prettify" certain strings in Auspice - e.g. "usa" became "USA", "new_zealand" became "New Zealand".
We dug ourselves into a bit of a hole here, as you can imagine the list of exceptions kept growing and growing.
Auspice v2 now generally parses strings as they appear in the JSON, allowing you full control over how things appear.
(For backwards compatability, we've kept the "prettifying" function in the v1-v2 conversion logic so the look of v1 JSONs shouldn't change.)</p>
<h4><a class="anchor" aria-hidden="true" id="both-metadata-and-tree-data-in-a-single-json"></a><a href="#both-metadata-and-tree-data-in-a-single-json" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Both metadata and tree data in a single JSON</h4>
<p>The most visible change is probably the reduction of two JSONs (<code>_meta.json</code> + <code>_tree.json</code>) into a single JSON.
This single JSON has three required (and no optional) keys:</p>
<pre><code class="hljs css language-json">{
<span class="hljs-attr">"version"</span>: <span class="hljs-string">"schema version"</span>,
<span class="hljs-attr">"meta"</span>: {},
<span class="hljs-attr">"tree"</span>: {}
}
</code></pre>
<h4><a class="anchor" aria-hidden="true" id="gene-genome-definitions-are-now-in-gff-format"></a><a href="#gene-genome-definitions-are-now-in-gff-format" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Gene / Genome definitions are now in GFF format.</h4>
<p>v1 Auspice JSONs used 0-based starts for the gene positions and <code>1</code>/<code>-1</code> for which strand the gene was on.
We now use one-based start & end coordinates, following GFF format, and a "+" or "-" to denote the strand.
These definitions are now under the <code>genome_annotations</code> property (formerly <code>annotations</code>).
See <a href="https://github.com/nextstrain/auspice/pull/770">PR #770</a>.</p>
<h4><a class="anchor" aria-hidden="true" id="changes-to-how-node-data-is-stored"></a><a href="#changes-to-how-node-data-is-stored" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Changes to how node data is stored</h4>
<p>Each tree node (internal & terminal) can now contain the following properties</p>
<ul>
<li><code>name</code> (required) -- formerly this was <code>strain</code></li>
<li><code>node_attrs</code> -- attributes associated with the node (sequence, date, location) as opposed to changes from one node to another.
<ul>
<li>Node attributes can now be objects and contain confidence information if available.</li>
<li>A <code>hidden</code> node attribute can control Auspice's display of the node</li>
<li>Author information is now contained under the <code>author</code> key, and the <code>author_info</code> dictionary is no longer present in the JSON.</li>
</ul></li>
<li><code>branch_attrs</code> -- attributes associated with the branch from the parent node to this node, such as branch lengths, mutations, support values
<ul>
<li><code>branch_attrs.mutations</code> -- both AA & nucleotide mutations are now defined in the same object.</li>
</ul></li>
<li><code>children</code> (unchanged)</li>
</ul>
<h4><a class="anchor" aria-hidden="true" id="colorings-geographic-resolutions-and-defaults"></a><a href="#colorings-geographic-resolutions-and-defaults" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Colorings, geographic resolutions, and defaults</h4>
<p>The <code>colorings</code> property (formerly <code>color_options</code>) is now an array of objects, the properties of which are easier to understand.
This guarantees the ordering appears in Auspice as you define it in the JSON.
See <a href="https://github.com/nextstrain/auspice/pull/748">PR #748</a>.</p>
<p>The <code>geo_resolutions</code> property (formerly <code>geo</code>) is similarly an array of objects.</p>
<p>The <code>display_defaults</code> property (formerly <code>defaults</code>) now contains keys which are snake_case instead of camelCase.</p>
<h4><a class="anchor" aria-hidden="true" id="multiple-maintainers"></a><a href="#multiple-maintainers" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Multiple maintainers</h4>
<p>The maintainer, displayed in the Auspice footer, was previously limited to a single string value and corresponding URL.
We now allow multiple maintainers, each with their own (optional) URL.</p>
<h4><a class="anchor" aria-hidden="true" id="continous-categorical-ordinal-and-boolean-color-scales"></a><a href="#continous-categorical-ordinal-and-boolean-color-scales" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Continous, Categorical, Ordinal, and Boolean Color Scales</h4>
<p>Traits with the "boolean" colour type which will use a pre-defined yellow & blue colour scale.
Currently "continous" and "categorical" scales both use the same colour scale.
Note that "discrete" types from v1 JSONs will be interpreted as "categorical".</p>
<h2><a class="anchor" aria-hidden="true" id="more-information-in-tree-info-boxes"></a><a href="#more-information-in-tree-info-boxes" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>More information in tree info boxes</h2>
<p>We've made more things available when you hover over the tree or click on a tree tip.
For instance, v1 would use the aa-nt toggle in the entropy panel to decide which mutations to display, and it was frustrating to have to scroll down to switch the toggle just to see what nucleotide mutations were on a branch!
We now show both.</p>
<p><img src="/auspice/assets/v2-tree-info.png" alt="more-tree-info">
<em>Auspice v1 (left) & v2 (right). v2 shows more information on both tree hover (upper panel) & when clicking on tips (lower panel).</em></p>
<h2><a class="anchor" aria-hidden="true" id="display-of-second-trees"></a><a href="#display-of-second-trees" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Display of second trees</h2>
<p>Auspice has had the ability to display two trees side-by-side for a while now (and <a href="/auspice/advanced-functionality/second-trees">finally documented</a>).
If you wanted to, say, compare influenza HA & NA trees, the URL used to look like "flu/seasonal/h3n2/ha:na/2y".
This turned out to be problematic when coming up with suitable candidates for potential second-trees, and also made it impossible to compare, for instance, "ha/2y" with "na/3y"</p>
<p>We now use a more verbose syntax to define the display of multiple trees, specifying the entire pathname for both datasets.
The above example is now "flu/seasonal/h3n2/ha/2y:flu/seasonal/h3n2/na/2y".
Any available datasets can be compared using this URL syntax, even if the result is rather nonsensical.
The old syntax will continue to work and will automatically correct to the new syntax (and show you a warning).</p>
<p>P.S. The list of available second trees, which is displayed in the sidebar, is now handed to Auspice by the <a href="/auspice/server/api#charon-getavailable">getAvailable API request</a>.</p>
<h2><a class="anchor" aria-hidden="true" id="display-better-dates-on-the-tree-axis"></a><a href="#display-better-dates-on-the-tree-axis" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Display better dates on the tree axis</h2>
<p>Internally, we use decimal dates (e.g. 2012.3 is around the start of may) so that's what we displayed on the tree.
It turns out this is pretty hard to interpret when looking at small timespans!
We now (a) show dates on the tree's x-axis using months & days, depending on the timespan displayed, and (b) try to use more informative grid spacings.
These help with the interpretation of trees over smaller time scales.
See <a href="https://github.com/nextstrain/auspice/pull/804">PR #804</a>.</p>
<p><img src="/auspice/assets/v2-time-labels.png" alt="time-labels">
<em>Above: Auspice v1's decimal labels were somewhat hard to interprete. Below: v2 displays calendar dates as appropriate, and uses more intelligent grid spacing.</em></p>
<h2><a class="anchor" aria-hidden="true" id="map-reset-zoom-button-zooms-to-include-all-demes"></a><a href="#map-reset-zoom-button-zooms-to-include-all-demes" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Map "reset zoom" button zooms to include all demes</h2>
<p>There's now a button at the top-right of the map which will trigger the map to reset the zoom.
See <a href="https://github.com/nextstrain/auspice/pull/802">PR #802</a>.</p>
<h2><a class="anchor" aria-hidden="true" id="consistent-colouring-of-missing-data-in-the-tree"></a><a href="#consistent-colouring-of-missing-data-in-the-tree" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Consistent colouring of missing data in the tree</h2>
<p>If your analysis produces results in <code>-</code> (gaps), <code>X</code> (unknown residue) or <code>N</code> (unknown nucelotide) then we now colour these grey, making it much easier to see when data is missing.
See <a href="https://github.com/nextstrain/auspice/pull/799">PR #799</a>.</p>
<p><img src="/auspice/assets/v2-base-colours.png" alt="base-colours">
<em>Same analysis, different colour schemes, different interpretation.</em></p>
<h2><a class="anchor" aria-hidden="true" id="removal-of-twitter-google-analytics"></a><a href="#removal-of-twitter-google-analytics" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Removal of Twitter & Google Analytics</h2>
<p>These were a holdover from the early days when <a href="https://nextstrain.org">nextstrain.org</a> and Auspice were the same thing.
We've now removed all calls to Twitter, and made Google Analytics opt in.
See <a href="/auspice/customise-client/requests">requests made from the client</a> for details on exactly what requests are made and how to opt-in to Google Analytics if you desire.</p>
<h2><a class="anchor" aria-hidden="true" id="improvements-in-the-entropy-panel"></a><a href="#improvements-in-the-entropy-panel" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Improvements in the entropy panel</h2>
<p>We improved the usability of the entropy (genomic diversity) panel, as well as fixing a few hidden bugs -- see <a href="https://github.com/nextstrain/auspice/pull/771">PR #771</a>.
For instance, you can now see which codon a nucleotide codes for (and vice-versa).</p>
<p><img src="/auspice/assets/v2-entropy.gif" alt="entropy"></p>
<h2><a class="anchor" aria-hidden="true" id="auspice-responds-to-server-redirects-for-datasets"></a><a href="#auspice-responds-to-server-redirects-for-datasets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Auspice responds to server redirects for datasets</h2>
<p>This allows custom servers (<a href="https://nextstrain.org">nextstrain.org</a>, for instance!) to smoothly inform Auspice that, e.g., a <code>getDataset</code> request to "/flu" (which doesn't actually exist) should be "/flu/seasonal/h3n2/ha/3y".
See <a href="https://github.com/nextstrain/auspice/pull/778">PR #778</a>.</p>
<h2><a class="anchor" aria-hidden="true" id="importing-server-code-from-auspice"></a><a href="#importing-server-code-from-auspice" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Importing (server) code from Auspice</h2>
<p>Auspice now makes a few helper commands available for those who are writing custom Auspice servers.
See <a href="/auspice/server/api#importing-code-from-auspice">these docs</a> for more info.</p>
<h2><a class="anchor" aria-hidden="true" id="new-auspice-subcommand-auspice-convert"></a><a href="#new-auspice-subcommand-auspice-convert" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>New Auspice subcommand: <code>auspice convert</code></h2>
<p>This is a utility command to convert between dataset formats.
Currently, it only converts "Auspice v1" JSONs into "Auspice v2" JSONs, using the same code that is <a href="/auspice/server/api#convertfromv1">programatically importable</a>.</p>
<p>Right now, <code>auspice view</code> will automatically convert "v1" JSONs into "v2" JSONs, so there's no need to do this yourself.</p>
<h2><a class="anchor" aria-hidden="true" id="ability-to-show-a-build-source-url-in-the-sidebar"></a><a href="#ability-to-show-a-build-source-url-in-the-sidebar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Ability to show a "build" source URL in the sidebar</h2>
<p>Auspice used to contain some hard-coded logic which was used by nextstrain to display a link to the GitHub repo behind community URLs.
We have now generalised this, and the <a href="/auspice/server/api#charon-getavailable">getAvailable API request</a> can define a <code>buildUrl</code> property for each dataset which auspice will display in the sidebar.</p>
<h2><a class="anchor" aria-hidden="true" id="auspice-view-uses-a-custom-auspice-client-if-present"></a><a href="#auspice-view-uses-a-custom-auspice-client-if-present" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code>auspice view</code> uses a custom Auspice client if present</h2>
<p>It's possible to use <code>auspice build</code> to <a href="/auspice/customise-client/introduction">build a custom auspice client</a>.
If this has been done, then running <code>auspice view</code> will serve it -- before you had to run <code>auspice view --customBuild</code>.
This streamlines generating custom auspice bundles and serving them locally.</p>
</span></div></article></div><div class="docLastUpdate"><em>Last updated on 10/21/2019</em></div><div class="docs-prevnext"><a class="docs-prev button" href="/auspice/releases/changelog"><span class="arrow-prev">← </span><span>Changelog</span></a><a class="docs-next button" href="/auspice/contributing/overview"><span>Contributing to Auspice</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#whats-new">What's New</a></li><li><a href="#backstory">Backstory</a></li><li><a href="#i-dont-want-to-upgrade-how-can-i-continue-to-use-auspice-v1">I don't want to upgrade - how can I continue to use Auspice v1?</a></li><li><a href="#pie-charts-to-represent-discrete-variables-on-a-map">Pie charts to represent discrete variables on a map</a></li><li><a href="#new-dataset-json-format">New dataset JSON format</a></li><li><a href="#more-information-in-tree-info-boxes">More information in tree info boxes</a></li><li><a href="#display-of-second-trees">Display of second trees</a></li><li><a href="#display-better-dates-on-the-tree-axis">Display better dates on the tree axis</a></li><li><a href="#map-quot-reset-zoom-quot-button-zooms-to-include-all-demes">Map "reset zoom" button zooms to include all demes</a></li><li><a href="#consistent-colouring-of-missing-data-in-the-tree">Consistent colouring of missing data in the tree</a></li><li><a href="#removal-of-twitter-amp-google-analytics">Removal of Twitter & Google Analytics</a></li><li><a href="#improvements-in-the-entropy-panel">Improvements in the entropy panel</a></li><li><a href="#auspice-responds-to-server-redirects-for-datasets">Auspice responds to server redirects for datasets</a></li><li><a href="#importing-server-code-from-auspice">Importing (server) code from Auspice</a></li><li><a href="#new-auspice-subcommand-auspice-convert">New Auspice subcommand: <code>auspice convert</code></a></li><li><a href="#ability-to-show-a-quot-build-quot-source-url-in-the-sidebar">Ability to show a "build" source URL in the sidebar</a></li><li><a href="#auspice-view-uses-a-custom-auspice-client-if-present"><code>auspice view</code> uses a custom Auspice client if present</a></li></ul></nav></div><footer class="nav-footer" id="footer"><section class="sitemap"><div><a href="/auspice/"><img style="padding-left:20px" src="/auspice/img/logo-light.svg" alt="Auspice" width="66" height="58"/></a></div><div><h5>External Links</h5><a href="https://github.com/nextstrain/auspice">GitHub repo</a><a href="https://www.npmjs.com/package/auspice">NPM package</a><a href="https://nextstrain.org">Nextstrain</a></div><div><h5>Contact Us</h5><a href="mailto:hello@nextstrain.org">email</a><a href="https://twitter.com/hamesjadfield">twitter</a></div></section><section class="copyright">Website built by <a href="https://twitter.com/hamesjadfield">James Hadfield</a> using <a href="https://docusaurus.io">Docusaurus</a></section><section class="copyright">If you use auspice, please cite <a href="https://doi.org/10.1093/bioinformatics/bty407">Hadfield et al., 2018</a></section><section class="copyright">Copyright © 2014-2020 Richard Neher & Trevor Bedford</section></footer></div></body></html>