auspice
Version:
Web app for visualizing pathogen evolution
154 lines (139 loc) • 22.4 kB
HTML
<html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Writing a Narrative · Auspice</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="This documentation will walk us through constructing a narrative from scratch, based on [this example (nextstrain.org)](https://nextstrain.org/narratives/intro-to-narratives)."/><meta name="docsearch:language" content="en"/><meta property="og:title" content="Writing a Narrative · Auspice"/><meta property="og:type" content="website"/><meta property="og:url" content="https://nextstrain.github.io/auspice/"/><meta property="og:description" content="This documentation will walk us through constructing a narrative from scratch, based on [this example (nextstrain.org)](https://nextstrain.org/narratives/intro-to-narratives)."/><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>Narratives</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 navListItemActive"><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"><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">Writing a Narrative</h1></header><article><div><span><p>This documentation will walk us through constructing a narrative from scratch, based on <a href="https://nextstrain.org/narratives/intro-to-narratives">this example (nextstrain.org)</a>.
If you run into any bugs, please <a href="mailto:hello@nextstrain.org">get in contact with us (email)</a>.</p>
<h2><a class="anchor" aria-hidden="true" id="step-1-get-the-underlying-datasets"></a><a href="#step-1-get-the-underlying-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>Step 1: Get the Underlying Datasets</h2>
<p>You can skip this step if you have generated your own dataset, but for the purposes of this tutorial we will need the mumps dataset.</p>
<pre><code class="hljs css language-bash">mkdir datasets
curl http://data.nextstrain.org/mumps_na.json --compressed -o datasets/mumps_na.json
</code></pre>
<p>You should now be able to visualise the dataset (without any narrative functionality) via <code>auspice view --datasetDir datasets</code></p>
<h2><a class="anchor" aria-hidden="true" id="step-2-start-a-simple-narrative"></a><a href="#step-2-start-a-simple-narrative" 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>Step 2: Start a Simple Narrative</h2>
<p>We're going to start by creating a narrative with only one page (the title page).</p>
<pre><code class="hljs css language-bash">mkdir narratives
touch narratives/example.md
</code></pre>
<p>Open up <code>narratives/example.md</code> and start by pasting in the following YAML frontmatter, which is used to define some basic set-up for the narrative and create the first narrative page.</p>
<pre><code class="hljs css language-yaml"><span class="hljs-meta">---</span>
<span class="hljs-attr">title:</span> <span class="hljs-string">Example</span> <span class="hljs-string">narrative</span> <span class="hljs-string">tutorial</span>
<span class="hljs-attr">authors:</span> <span class="hljs-string">"your name"</span>
<span class="hljs-attr">authorLinks:</span> <span class="hljs-string">"url, twitter link, mailto etc"</span>
<span class="hljs-attr">affiliations:</span> <span class="hljs-string">"your affiliation"</span>
<span class="hljs-attr">date:</span> <span class="hljs-string">"August 2018"</span>
<span class="hljs-attr">dataset:</span> <span class="hljs-string">"http://localhost:4000/mumps/na?d=tree"</span>
<span class="hljs-attr">abstract:</span> <span class="hljs-string">"This narrative is going to test the potential of the Auspice narrative functionality using the publicly available North American mumps dataset."</span>
<span class="hljs-meta">---</span>
</code></pre>
<p>The really important bit here is the <code>dataset</code> line -- this references the dataset we downloaded above.
(A <a href="/auspice/narratives/introduction##nown-bugs-limitations">current limitation</a> of narratives is that they cannot change the dataset.)</p>
<h2><a class="anchor" aria-hidden="true" id="step-3-view-the-narrative-so-far"></a><a href="#step-3-view-the-narrative-so-far" 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>Step 3: View the Narrative so Far</h2>
<p>We don't really have much, but we can still load it up in Auspice and check it's working as expected. If it is, we will see a narrative with only one page.</p>
<pre><code class="hljs css language-bash">auspice view --datasetDir datasets/ --narrativeDir narratives/
</code></pre>
<p>And you should see something like this at <a href="http://localhost:4000/narratives/example">localhost:4000/narratives/example</a></p>
<p><img src="/auspice/assets/narrative-tutorial-p1.png" alt="Narrative frontpage"></p>
<h2><a class="anchor" aria-hidden="true" id="step-4-adding-a-paragraph"></a><a href="#step-4-adding-a-paragraph" 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>Step 4: Adding a Paragraph</h2>
<p>Each "paragraph" or page of the narrative is made up of a section of Markdown starting with a h1 heading, which is a link with text beneath.
It is these h1 headings that define when we have a new narrative pararaphs.</p>
<blockquote>
<p>If you're new to Markdown, take a look <a href="https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet">at this page</a> to get started.</p>
</blockquote>
<p>The heading is itself a link that defines the view of Auspice at that time.
You may have noticed that as you interact with Auspice -- for this example at <a href="http://localhost:4000/mumps/na">localhost:4000/mumps/na</a> -- then the URL changes.
For instance, if we use the sidebar to toggle "off" the tree and entropy, just keeping the map then you'll see that the URL has changed to <a href="http://localhost:4000/mumps/na?d=map">localhost:4000/mumps/na?d=map</a>.
We're going to use this functionality to "save" the view of Auspice into the Markdown file, so that the narrative knows what view to show.</p>
<p>Let's use this knowledge to make a page in the narrative which switches to just show the map.
Add the following text to the narrative Markdown file:</p>
<pre><code class="hljs css language-md"><span class="hljs-section"># [Map View](http://localhost:4000/mumps/na?d=map)</span>
We can control which panels are displayed, for instance choosing to show only the map.
</code></pre>
<p>Now, we should have a second page available in the narrative:</p>
<p><img src="/auspice/assets/narrative-tutorial-p2.png" alt="narrative page2"></p>
<h2><a class="anchor" aria-hidden="true" id="step-5-adding-more-paragraphs"></a><a href="#step-5-adding-more-paragraphs" 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>Step 5: Adding More Paragraphs</h2>
<p>We're going to use the same iterative technique to add more pagragraphs:</p>
<ol>
<li>Use Auspice (<a href="http://localhost:4000/mumps/na">localhost:4000/mumps/na</a>) to change the view as you desire</li>
<li>Copy this URL and create a h1 header in the markdown file</li>
<li>Write some text in the Markdown to form the narrative paragraph</li>
<li>Repeat until happy 😁</li>
</ol>
<p>You can see the contents of the Markdown file behind <a href="https://nextstrain.org/narratives/intro-to-narratives">the example (nextstrain.org)</a> that we're basing this tutorial on <a href="https://raw.githubusercontent.com/nextstrain/narratives/master/intro-to-narratives.md">here</a>.
You can use this markdown file as inspiration for creating your own paragraphs, or just copy and paste the content!
For reference, here are three paragraphs from that file:</p>
<pre><code class="hljs css language-md">
<span class="hljs-section"># [Phylogenies](http://localhost:4000/mumps/na?d=tree&dmax=2014-07-14&dmin=2012-03-30&p=full)</span>
Here we've returned to the tree and begun slicing time.
<span class="hljs-section"># [Explore clock signal](http://localhost:4000/mumps/na?d=tree&l=clock&p=full)</span>
Different tree layouts are possible, this one shows the temporal
divergence vs. inferred substitutions to see the presence of a
constant clock signal.
<span class="hljs-section"># [Mutations I](http://localhost:4000/mumps/na?c=gt-SH_22&d=tree,entropy&p=full)</span>
Here we have coloured the tree according to a single mutation (residue 22 in
the SH gene) where there are two variants present in this dataset -- yellow tips
have a Methionine (<span class="hljs-code">`M`</span>) at this position, while aqua nodes indicate Isoleucine (<span class="hljs-code">`I`</span>).
</code></pre>
<h2><a class="anchor" aria-hidden="true" id="step-6-upload-your-example-to-the-nextstrain-community-to-share-with-everyone"></a><a href="#step-6-upload-your-example-to-the-nextstrain-community-to-share-with-everyone" 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>Step 6: Upload Your Example to the Nextstrain Community to Share with Everyone</h2>
<p>In the <a href="http://localhost:3000/auspice/narratives/introduction#sharing-narratives">narratives introduction</a> we introduced the possibility of using the community functionality of Nextstrain to share your narratives.</p>
<blockquote>
<p>A quick reminder of the difference between Auspice & nextstrain.org is warranted.
Nextstrain is a "user" of Auspice, in that it uses Auspice to visualise genomic data and makes it available via <a href="https://nextstrain.org">nextstrain.org</a>.
It has additional functionality available, such as the ability to source datasets (and narratives!) from any public GitHub repo -- <a href="https://nextstrain.org/docs/contributing/community-builds">see documentation here (nextstrain.org)</a>.
Note that the <em>dataset</em> (i.e. the JSON(s)) doesn't have to live in the same GitHub repo, in fact it doesn't even need to be a community build.</p>
</blockquote>
<blockquote>
<p>This step requires knowledge of GitHub -- <a href="https://guides.github.com/activities/hello-world/">see here</a> for an introduction.</p>
</blockquote>
<p>If you turn the directory containing the <code>datasets</code> and <code>narratives</code> directories into a Git repository and upload it to your GitHub account, then you can share your narrative with anyone through Nextstrain.
For instance, let's assume your GitHub username is "yourname" and your repo is called "auspice-narrative-example". You'll need to rename the narrative markdown to start with the repo name, e.g.</p>
<pre><code class="hljs css language-bash">mv narratives/example.md narratives/auspice-narrative-example.md
</code></pre>
<p>Then, by uploading the repo to GitHub it will be available to everyone at nextstrain.org/narratives/yourname/auspice-narrative-example.</p>
<p>This is how the narrative file at <a href="https://github.com/emmahodcroft/tb/blob/master/narratives/tb_crispell.md">GitHub > emmahodcroft > tb > narratives</a> can be accessed via <a href="https://nextstrain.org/community/narratives/emmahodcroft/tb/crispell">nextstrain.org/community/narratives/emmahodcroft/tb/crispell</a>.</p>
</span></div></article></div><div class="docLastUpdate"><em>Last updated on 11/15/2019</em></div><div class="docs-prevnext"><a class="docs-prev button" href="/auspice/narratives/introduction"><span class="arrow-prev">← </span><span>Communicating Results Using Narratives</span></a><a class="docs-next button" href="/auspice/narratives/create-pdf"><span>Converting a narrative to PDF</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#step-1-get-the-underlying-datasets">Step 1: Get the Underlying Datasets</a></li><li><a href="#step-2-start-a-simple-narrative">Step 2: Start a Simple Narrative</a></li><li><a href="#step-3-view-the-narrative-so-far">Step 3: View the Narrative so Far</a></li><li><a href="#step-4-adding-a-paragraph">Step 4: Adding a Paragraph</a></li><li><a href="#step-5-adding-more-paragraphs">Step 5: Adding More Paragraphs</a></li><li><a href="#step-6-upload-your-example-to-the-nextstrain-community-to-share-with-everyone">Step 6: Upload Your Example to the Nextstrain Community to Share with Everyone</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>