Auspice fork from github of https://github.com/urbanslug/auspice
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

137 lines
21 KiB

<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>How to Run Auspice · Auspice</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="Auspice is run as a command line program -- `auspice` -- with various subcommands."/><meta name="docsearch:language" content="en"/><meta property="og:title" content="How to Run Auspice · Auspice"/><meta property="og:type" content="website"/><meta property="og:url" content="https://nextstrain.github.io/auspice/"/><meta property="og:description" content="Auspice is run as a command line program -- `auspice` -- with various subcommands."/><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>Introduction</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 navListItemActive"><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></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"><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</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">How to Run Auspice</h1></header><article><div><span><p>Auspice is run as a command line program -- <code>auspice</code> -- with various subcommands.
You can run each command with <code>--help</code> attached to see help from the command line.</p>
<ul>
<li><code>auspice view --help</code> (this is the main command for interacting with Auspice)</li>
<li><code>auspice build --help</code></li>
<li><code>auspice develop --help</code></li>
<li><code>auspice convert --help</code></li>
</ul>
<h2><a class="anchor" aria-hidden="true" id="how-to-get-an-example-dataset-up-and-running"></a><a href="#how-to-get-an-example-dataset-up-and-running" 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>How to Get an Example Dataset Up and Running</h2>
<p>In order to get up and running you'll need to have some datasets to visualise.
For the purposes of getting Auspice up and running you can download the current Zika dataset via:</p>
<pre><code class="hljs css language-bash">mkdir datasets
curl http://data.nextstrain.org/zika_meta.json --compressed -o datasets/zika_meta.json
curl http://data.nextstrain.org/zika_tree.json --compressed -o datasets/zika_tree.json
</code></pre>
<p>And then run <code>auspice</code> via:</p>
<pre><code class="hljs css language-bash">auspice view --datasetDir datasets
</code></pre>
<p>This will allow you to run Auspice locally (i.e. from your computer) and view the dataset which is behind <a href="https://nextstrain.org/zika">nextstrain.org/zika</a>.
<a href="#obtaining-a-set-of-input-files">See below</a> for how to download all of the data available on <a href="https://nextstrain.org">nextstrain.org</a>.</p>
<p>To analyse your own data, please see the tutorials on the <a href="https://nextstrain.org/docs/">nextstrain docs</a>.</p>
<h2><a class="anchor" aria-hidden="true" id="auspice-view"></a><a href="#auspice-view" 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></h2>
<p>This is the main command we'll run Auspice with, as it makes Auspice available in a web browser for you.
There are two common arguments used:</p>
<table>
<thead>
<tr><th>argument name</th><th>data supplied</th><th>description</th></tr>
</thead>
<tbody>
<tr><td>datasetDir</td><td>PATH</td><td>Directory where datasets (JSONs) are sourced. This is ignored if you define custom handlers.</td></tr>
<tr><td>narrativeDir</td><td>PATH</td><td>Directory where narratives (Markdown files) are sourced. This is ignored if you define custom handlers.</td></tr>
</tbody>
</table>
<p>For more complicated setups, where you define your own server handlers, see <a href="/auspice/server/api#suppling-custom-handlers-to-the-auspice-server">suppling custom handlers to the Auspice server</a>.</p>
<h2><a class="anchor" aria-hidden="true" id="auspice-build"></a><a href="#auspice-build" 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 build</code></h2>
<p>Build the client source code bundle.
This is needed in three cases:</p>
<ol>
<li>You have installed Auspice from source, or updated the source code.</li>
<li>You are editing the source code and need to rebuild the client</li>
<li>You wish to build a customised version of the Auspice client.
See <a href="/auspice/customise-client/introduction">Customising Auspice</a> for more info.</li>
</ol>
<h2><a class="anchor" aria-hidden="true" id="auspice-develop"></a><a href="#auspice-develop" 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 develop</code></h2>
<p>Launch Auspice in development mode. This runs a local server and uses
hot-reloading to allow automatic updating as you edit the code.</p>
<p>This is only useful if you are editing the client source code!</p>
<h2><a class="anchor" aria-hidden="true" id="auspice-convert"></a><a href="#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><code>auspice convert</code></h2>
<p>This is a utility command to convert between dataset formats.
Currently, it only converts &quot;Auspice v1&quot; JSONs into &quot;Auspice v2&quot; 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 &quot;v1&quot; JSONs into &quot;v2&quot; JSONs, so there's no need to do this yourself.</p>
<h2><a class="anchor" aria-hidden="true" id="input-file-formats"></a><a href="#input-file-formats" 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>Input File Formats</h2>
<blockquote>
<p>Auspice is agnostic about the data it visualises -- they don't have to be viral genomes, or real-time, or generated in Augur.
(They do, however have to be in a specific file format.)</p>
</blockquote>
<p>Auspice takes two different file types: datasets (the tree, map, etc.), which are defined as one or more JSON files and narratives, which are specified as a Markdown file.</p>
<h3><a class="anchor" aria-hidden="true" id="dataset-jsons"></a><a href="#dataset-jsons" 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>Dataset JSONs</h3>
<p>For datasets, Auspice (v2.x) can currently load either</p>
<ul>
<li>&quot;Auspice v1&quot; JSONs (metadata + tree JSONs) -- see the JSON schemas <a href="https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v1-meta.json">here</a> and <a href="https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v1-tree.json">here</a>.
<em>The zika dataset we download above is in this format</em></li>
<li>&quot;Auspice v2&quot; JSONs. See the JSON schema <a href="https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v2.json">here</a>.</li>
</ul>
<p>See the <a href="/auspice/server/api">Server API</a> for more details about the file formats an Auspice server (e.g. <code>auspice view</code>) sends to the client.</p>
<p>Currently we mainly use <a href="https://github.com/nextstrain/augur">Augur</a> to create these datasets.
See <a href="https://nextstrain.org/docs/bioinformatics/introduction-to-augur">the Nextstrain documentation</a> for more details.</p>
<blockquote>
<p>We are working on ways to make datasets in Newick / Nexus formats available. You can see an early prototype of this at <a href="https://auspice-us.herokuapp.com/">auspice-us.herokuapp.com</a> where you can drop on Newick (and CSV) files.
Using BEAST trees is possible, but you have to use Augur to convert them first.</p>
</blockquote>
<h3><a class="anchor" aria-hidden="true" id="narratives"></a><a href="#narratives" 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>Narratives</h3>
<p>For narratives, please see <a href="/auspice/narratives/how-to-write">Writing a Narrative</a> for a description of the file format.</p>
<h2><a class="anchor" aria-hidden="true" id="obtaining-a-set-of-input-files"></a><a href="#obtaining-a-set-of-input-files" 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>Obtaining a Set of Input Files</h2>
<p>If you'd like to download the datasets and narratives on <a href="https://nextstrain.org">nextstrain.org</a> then there are two scripts which allow you to do this:</p>
<ul>
<li>You can download the dataset JSONs by running <a href="https://github.com/nextstrain/auspice/blob/master/scripts/get-data.sh">this script</a> which will create a <code>./data</code> directory for you.</li>
<li>You can download the narrative Markdown files by running <a href="https://github.com/nextstrain/auspice/blob/master/scripts/get-narratives.sh">this script</a> which will create a <code>./narratives</code> directory for you.</li>
</ul>
<p>You can then run <code>auspice view --datasetDir data --narrativeDir narratives</code> to visualise all of the <a href="https://nextstrain.org">nextstrain.org</a> datasets locally.</p>
</span></div></article></div><div class="docLastUpdate"><em>Last updated on 10/17/2019</em></div><div class="docs-prevnext"><a class="docs-prev button" href="/auspice/introduction/install"><span class="arrow-prev"></span><span>Install Auspice</span></a><a class="docs-next button" href="/auspice/advanced-functionality/second-trees"><span>Displaying mutliple trees</span><span class="arrow-next"></span></a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#how-to-get-an-example-dataset-up-and-running">How to Get an Example Dataset Up and Running</a></li><li><a href="#auspice-view"><code>auspice view</code></a></li><li><a href="#auspice-build"><code>auspice build</code></a></li><li><a href="#auspice-develop"><code>auspice develop</code></a></li><li><a href="#auspice-convert"><code>auspice convert</code></a></li><li><a href="#input-file-formats">Input File Formats</a><ul class="toc-headings"><li><a href="#dataset-jsons">Dataset JSONs</a></li><li><a href="#narratives">Narratives</a></li></ul></li><li><a href="#obtaining-a-set-of-input-files">Obtaining a Set of Input Files</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-2019 Richard Neher &amp; Trevor Bedford</section></footer></div></body></html>