Auspice

Auspice

  • Docs

โ€บNarratives

Introduction

  • Overview
  • Install Auspice
  • How to Run Auspice

Advanced Functionality

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

Customising Auspice

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

Using a Custom Server

  • Auspice servers
  • Server API
  • Authentication

Narratives

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

Release Notes

  • Changelog
  • Auspice Version 2.0

Contributing

  • Contributing to Auspice development

Communicating Results Using Narratives

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.

Examples

Narratives are easier to understand with examples:

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.

Click the link ๐Ÿ‘‡ and explore the content by scrolling the text in the left hand panel (or click on the arrows). The data visualizations will change accordingly. Clicking "explore the data yourself" above will display sidebar controls.

Example #1: Twenty years of West Nile virus (nextstrain.org)

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?


Here's another example written to show the various Auspice views you can utilise in narratives:

Example #2: Exploring the narrative functionality using the ongoing mumps epidemic in North America (nextstrain.org).

We'll go through this in more detail in the writing a narrative docs.

How to Write a Narrative

If you have a dataset that you (or anyone else) created then you can write a narrative to enhance it ๐Ÿ’ซ

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 writing a narrative tutorial will use the mumps example from above to explain how you can write your own narrative.

Sharing Narratives

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:

  1. Use the community functionality of nextstrain.org (the easier option, detailed in writing a narrative).
  2. Implement an Auspice server yourself (the harder option, see the server documentation).

Known Bugs / Limitations

Narratives are now being used in various settings, however some bugs remain. Please get in touch (email) with any and all questions about narratives, or file an issue on GitHub ๐Ÿ™

  • Datasets currently cannot be changed between paragraphs (i.e. the initial dataset is used for all subsequent paragraphs).

  • Text which is larger than the sidebar / page height is cut off.

  • Styling may be slightly off on different browsers.

  • 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.

  • The frontmatter parsing will be extended to allow arrays of authors (etc).

Take a look at the GitHub issues tagged as related to narrative functionality for a potentially more up-to-date list of these.

Last updated on 10/17/2019
โ† AuthenticationWriting a Narrative โ†’
  • Examples
  • How to Write a Narrative
  • Sharing Narratives
  • Known Bugs / Limitations
Auspice
External Links
GitHub repoNPM packageNextstrain
Contact Us
emailtwitter
Website built by James Hadfield using Docusaurus
If you use auspice, please cite Hadfield et al., 2018
Copyright ยฉ 2014-2020 Richard Neher & Trevor Bedford