auspice
Version:
Web app for visualizing pathogen evolution
99 lines (92 loc) • 15.9 kB
HTML
<html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Communicating Results Using Narratives · Auspice</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="Narratives are a method of data-driven storytelling."/><meta name="docsearch:language" content="en"/><meta property="og:title" content="Communicating Results Using Narratives · Auspice"/><meta property="og:type" content="website"/><meta property="og:url" content="https://nextstrain.github.io/auspice/"/><meta property="og:description" content="Narratives are a method of data-driven storytelling."/><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 navListItemActive"><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"><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">Communicating Results Using Narratives</h1></header><article><div><span><p>Narratives are a method of data-driven storytelling.
They allow scientists (or anyone!) to author content which is displayed alongside the "normal" Auspice view of the data.
This content drives the way in which data is displayed, so instead of the user changing how things are displayed, the view automatically changes as you move between paragraphs in the narrative.
This allows you to communicate results with the appropriate views into the data, whilst maintaining the ability for the user to jump back to the "normal" viewing mode and interact with the data.</p>
<h2><a class="anchor" aria-hidden="true" id="examples"></a><a href="#examples" 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>Examples</h2>
<p>Narratives are easier to understand with examples:</p>
<p>We've been looking into West Nile Virus (WNV) spread throughout North America and used Auspice to visualise the spread of the virus from east to west over a 20 year period.
To communicate these results, we constructed a narrative to walk people through this, which we suggest taking a look at to grasp the power of narratives.</p>
<blockquote>
<p><em>Click the link 👇 and explore the content by scrolling the text in the left hand panel (or click on the arrows).</em>
<em>The data visualizations will change accordingly.</em>
<em>Clicking "explore the data yourself" above will display sidebar controls.</em></p>
</blockquote>
<p><strong>Example #1</strong>: <a href="https://nextstrain.org/narratives/twenty-years-of-WNV">Twenty years of West Nile virus (nextstrain.org)</a></p>
<p>Hopefully that gave you an idea about how the interplay between bits of text and views into the data allows for better communication of our interpretation of the data.
Did you notice that, at any point in the narrative, people can dive into the data themselves if they want to?</p>
<hr>
<p>Here's another example written to show the various Auspice views you can utilise in narratives:</p>
<p><strong>Example #2</strong>: <a href="https://nextstrain.org/narratives/intro-to-narratives">Exploring the narrative functionality using the ongoing mumps epidemic in North America (nextstrain.org)</a>.</p>
<p>We'll go through this in more detail in the <a href="/auspice/narratives/how-to-write">writing a narrative</a> docs.</p>
<h2><a class="anchor" aria-hidden="true" id="how-to-write-a-narrative"></a><a href="#how-to-write-a-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>How to Write a Narrative</h2>
<p>If you have a dataset that you (or anyone else) created then you can write a narrative to enhance it 💫</p>
<p>Behind the scenes a narrative is a single Markdown file written in a particular format -- i.e. each of the example narratives linked above comprises a single Markdown file.
The <a href="/auspice/narratives/how-to-write">writing a narrative</a> tutorial will use the mumps example from above to explain how you can write your own narrative.</p>
<h2><a class="anchor" aria-hidden="true" id="sharing-narratives"></a><a href="#sharing-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>Sharing Narratives</h2>
<p>If you've got a narrative working locally (i.e. running Auspice on your computer) and want to share the results then you have two options:</p>
<ol>
<li>Use the community functionality of nextstrain.org (the easier option, detailed in <a href="/auspice/narratives/how-to-write#step-6-upload-your-example-to-nextstrain-community-to-share-with-everyone">writing a narrative</a>).</li>
<li>Implement an Auspice server yourself (the harder option, see <a href="/auspice/server/introduction">the server documentation</a>).</li>
</ol>
<h2><a class="anchor" aria-hidden="true" id="known-bugs-limitations"></a><a href="#known-bugs-limitations" 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>Known Bugs / Limitations</h2>
<p>Narratives are now being used in various settings, however some bugs remain.
Please <a href="mailto:hello@nextstrain.org">get in touch (email)</a> with any and all questions about narratives, or <a href="https://github.com/nextstrain/auspice/issues/new">file an issue on GitHub</a> 🙏</p>
<ul>
<li><p>Datasets currently cannot be changed between paragraphs (i.e. the initial dataset is used for all subsequent paragraphs).</p></li>
<li><p>Text which is larger than the sidebar / page height is cut off.</p></li>
<li><p>Styling may be slightly off on different browsers.</p></li>
<li><p>Not all state is mirrored in the URLs (for instance, map bounds are not set in the URL).
This limits what views can be defined by paragraphs in the narratives.</p></li>
<li><p>The frontmatter parsing will be extended to allow arrays of authors (etc).</p></li>
</ul>
<p>Take a look at the <a href="https://github.com/nextstrain/auspice/labels/narratives">GitHub issues tagged as related to narrative functionality</a> for a potentially more up-to-date list of these.</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/server/authentication"><span class="arrow-prev">← </span><span>Authentication</span></a><a class="docs-next button" href="/auspice/narratives/how-to-write"><span>Writing a Narrative</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#examples">Examples</a></li><li><a href="#how-to-write-a-narrative">How to Write a Narrative</a></li><li><a href="#sharing-narratives">Sharing Narratives</a></li><li><a href="#known-bugs-limitations">Known Bugs / Limitations</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>