Commit 43674923 authored by Misja Ilcisin's avatar Misja Ilcisin
Browse files

Edits to auspice docs

Copy edit for grammar/spelling errors and inconsistencies as well as flow across all auspice docs and a particular focus on edits to auspice V2 release notes 
parent 9105cb36
......@@ -15,7 +15,7 @@ cd
## version 1.38.0 - 2019/08/29
* Add support for frequency projections. [See PR 777](https://github.com/nextstrain/auspice/pull/777)
* Local auspice servers listen on only localhost by default instead of all interfaces. [See PR 781](https://github.com/nextstrain/auspice/pull/781)
* Local Auspice servers listen on only localhost by default instead of all interfaces. [See PR 781](https://github.com/nextstrain/auspice/pull/781)
* update dependencies
......@@ -482,7 +482,7 @@ The new interface is both easier to understand and quicker.
## version 1.10.0 - 2018/02/05
### Features
* Local Branching Index (LBI) coloring can be calculated in auspice (code identical to nextflu) if specified in `color_options` (meta JSON) ([PR 491](https://github.com/nextstrain/auspice/pull/491))
* Local Branching Index (LBI) coloring can be calculated in Auspice (code identical to nextflu) if specified in `color_options` (meta JSON) ([PR 491](https://github.com/nextstrain/auspice/pull/491))
### Internals
* `get_data.sh` script updated to no longer download sequences & entropy JSONs
......@@ -503,12 +503,12 @@ The new interface is both easier to understand and quicker.
## version 1.8.0 - 2018/01/18
#### entropy calculated via tree
* The entropy panel data is now computed within auspice by examining mutations throughout the tree, and is throttled to improve speed under load.
* The entropy panel data is now computed within Auspice by examining mutations throughout the tree, and is throttled to improve speed under load.
* Both entropy and number of mutations are available via a toggle similar to AA/NT
* This results in `entropy.JSON` no longer being fetched.
* The entropy data is stored in redux state rather than the react component
* The D3 code has been reorganised
* Note that the entropy values are slightly different to those exported by augur in some situations - see https://github.com/nextstrain/auspice/pull/478#issuecomment-358496901
* Note that the entropy values are slightly different to those exported by Augur in some situations - see https://github.com/nextstrain/auspice/pull/478#issuecomment-358496901
#### genotype calculated via tree
* This results in `sequences.JSON` no longer being fetched.
......
......@@ -4,22 +4,22 @@ title: Contributing
Auspice is developed via GitHub and issues and comments are very welcome.
Alternatively, [email us](mailto:hello@nextstrain.org) with any questions or comments you may have.
Alternatively, you can [email us](mailto:hello@nextstrain.org) with any questions or comments you may have.
## Contributing to these docs
## Contributing to tbe Docs
This documentation is all contained within the auspice GitHub repo -- see [the docs-src directory](https://github.com/nextstrain/auspice/tree/master/docs-src) for more details and instructions on how to contribute here.
This documentation is all contained within the Auspice GitHub repo -- see [the docs-src directory](https://github.com/nextstrain/auspice/tree/master/docs-src) for more details and instructions on how to contribute.
## Contributing to devlopment
If you are interested in contrubuting code then it'd be best to create a [GitHub issue](https://github.com/nextstrain/auspice/issues) before spending time in the codebase!
For pull requests, please use [eslint](https://eslint.org/) as much as possible -- thanks!
## Contributing to Devlopment
If you are interested in contrubuting code then we would recommend that you create a [GitHub issue](https://github.com/nextstrain/auspice/issues) before spending time in the codebase.
For pull requests, please use [eslint](https://eslint.org/) as much as possible -- thanks!
## Releasing new version of auspice
## Releasing New Versions of Auspice
New versions are released via the `./releaseNewVersion.sh` script from an up-to-date `master` branch.
It will prompt you for the version number increase, push changes to the `release` branch and, as long as Travis-CI is successful then a new version will be automatically published to [npm](https://www.npmjs.com/package/auspice).
It will prompt you for the version number increase, push changes to the `release` branch and, as long as Travis-CI is successful, then a new version will be automatically published to [npm](https://www.npmjs.com/package/auspice).
---
title: Client customisation API
title: Client Customisation API
---
> The functionality detailed in the page needs more attention, both from testing & code development.
> The functionality detailed in this page needs more attention, both in terms of testing and code development.
We expect there to be some bugs and possible API changes.
If you rely on this functionality, we recommend you pin your installation of auspice to a specific version.
If you rely on this functionality, we recommend you pin your installation of Auspice to a specific version.
Please [get in touch with us](mailto:hello@nextstrain.org) if you are using these customisations so that we can work with you!
This page details the available options and format of the customisations available at (client) build time.
They are contained in a JSON file supplied to auspice via
They are contained in a JSON file supplied to Auspice via
```bash
auspice build --extend <JSON>
```
*Note that the hot-reloading development functionality does not work for code which is included via this client customisation mecahnism.*
*Note that the hot-reloading development functionality does not work for code which is included via this client customisation mechanism.*
*Thus, while you can run `auspice develop --extend <JSON>` it will not update as you may expect!*
## Available customisations
## Available Customisations
The following are definable as top-level keys of the JSON file.
A useful reference may be the [customisation JSON file](https://github.com/nextstrain/nextstrain.org/blob/master/auspice/client/config.json) used by nextstrain.org.
* `sidebarTheme` allows modifications to the aesthetics of the sidebar. See below.
* `navbarComponent` a (relative) path to a JS file exporting a React component to be rendered as the nav bar. See below.
* `browserTitle` The browser title for the page. Defaults to "auspice" if not defined.
* `googleAnalyticsKey` You can specify a google analytics key to enable (some) analytics functionality. More documentation to come.
* `browserTitle` The browser title for the page. Defaults to "Auspice" if not defined.
* `googleAnalyticsKey` You can specify a Google Analytics key to enable (some) analytics functionality. More documentation to come.
> For customisation code which uses [React](https://reactjs.org/) components, you must import these as `import React from "@libraries/react";` to ensure that the version of react is the same as what auspice uses!
> For customisation code which uses [React](https://reactjs.org/) components, you must import these as `import React from "@libraries/react";` to ensure that the version of react is the same as what Auspice uses.
---
## Sidebar Theme
The appearence of the sidebar can be customised by specifing a theme in the config JSON used to build auspice.
The appearence of the sidebar can be customised by specifing a theme in the config JSON used to build Auspice.
This theme is then available (via [styled-components](https://www.styled-components.com/)) to the components rendered in the sidebar.
It is also passed to the nav bar component (see below) as the `theme` prop.
......@@ -67,14 +67,14 @@ For instance, here is the customisation used by nextstrain.org:
# Components
One way to extend auspice is by replacing react components with your own custom components.
One way to extend Auspice is by replacing React components with your own custom components.
These custom components will receive props defined here, which can be used to update the rendering of the component using the normal react lifecycle methods.
Right now this is only available for the splash page and nav-bar components, whose interfaces are defined here.
Each component must be the default export of a javascript file which is specified in the (client) config JSON passed to auspice at build time (`auspice build` or `auspice develop`).
Each component must be the default export of a javascript file which is specified in the (client) config JSON passed to Auspice at build time (`auspice build` or `auspice develop`).
## Nav-bar component
## Nav-bar Component
**Build config:**
```json
......@@ -85,7 +85,7 @@ Each component must be the default export of a javascript file which is specifie
Where the javascript file contains a default export of a React component.
**React Props available:**
**React Props Available:**
| Prop | Type | Description |
| ----------- |--------- | ------ |
......@@ -97,7 +97,7 @@ Where the javascript file contains a default export of a React component.
## Splash component
Define a custom splash page for auspice. Please note that this is extremely expirimental and the interface is expected to change.
Define a custom splash page for Auspice. Please note that this is extremely expirimental and the interface is expected to change.
**Build config:**
```json
......@@ -114,7 +114,7 @@ Where the javascript file contains a default export of a React component.
| `isMobile` | Bool | |
| `available` | Object | available datasets and narratives |
| `browserDimensions` | Object | Browser width & height |
| `dispatch` | function | access to redux's dispatch mechanism |
| `dispatch` | function | access to redux's dispatch mechanism |
| `errorMessage` | function | to do |
| `changePage` | function | to do |
---
title: Customising auspice
title: Customising Auspice
---
Auspice allows you to customise the appearance and functionality of auspice [when the client is built](introduction/how-to-run.md#auspice-build).
This is how auspice running locally and nextstrain.org look different, despite both using "auspice".
Auspice allows you to customise the appearance and functionality of Auspice [when the client is built](introduction/how-to-run.md#auspice-build).
This is how Auspice running locally and nextstrain.org look different, despite both using "Auspice".
![mumps](assets/auspice-vs-nextstrain.png)
*Notice the difference? Default auspice (left) and nextstrain.org's customised version (right)*
*Notice the difference? Default Auspice (left) and nextstrain.org's customised version (right)*
This is achieved by providing a JSON at build time to auspice which defines the desired customisations via:
This is achieved by providing a JSON at build time to Auspice which defines the desired customisations via:
```bash
auspice build --extend <JSON>
```
[Here's](https://github.com/nextstrain/nextstrain.org/blob/master/auspice/client/config.json) the file used by nextstrain.org to change the appearance of auspice in the above image.
[Here's](https://github.com/nextstrain/nextstrain.org/blob/master/auspice/client/config.json) the file used by nextstrain.org to change the appearance of Auspice in the above image.
See the [client customisation API](customise-client/api.md) for the available options.
See the [client customisation API](customise-client/api.md) for the available options.
---
title: Requests made from the client
title: Requests Made from the Client
---
The auspice client will make a number of requests to various endpoints, which this document aims to provide an overview of.
The Auspice client will make a number of requests to various endpoints, which this document aims to provide an overview of.
Some of these are dependent on the [build-time customisations](customise-client/introduction.md) in use, and we plan to allow more flexibility here using this mechanism.
## Requests to the auspice server
For the purposes of this section we are assuming you are running locally on "localhost:4000", however the idea is the same if auspice is deployed to a server.
## Requests to the Auspice Server
For the purposes of this section we are assuming you are running locally on "localhost:4000", however the idea is the same if Auspice is deployed to a server.
### Auspice client JavaScript code (bundles)
### Auspice Client JavaScript Code (Bundles)
The (bundled) client code (which is generated by `auspice build`) is broken up into a number of "chunks" which are delivered to the client as needed.
These originate from the following block in the `index.html` file:
```html
......@@ -18,7 +18,7 @@ These originate from the following block in the `index.html` file:
```
### "Charon" GET requests
When a dataset, narrative or listing of available datasets is to be displayed in auspice, a selection of the following requests are made to localhost:4000.
When a dataset, narrative, or listing of available datasets is to be displayed in Auspice, a selection of the following requests are made to localhost:4000.
* `/charon/getAvailable` -- return a list of available datasets and narratives
* `/charon/getDataset` -- return the requested dataset
......@@ -26,27 +26,27 @@ When a dataset, narrative or listing of available datasets is to be displayed in
See [the server API documentation](server/api.md) for more details.
### Image requests
### Image Requests
The initial auspice page (i.e. the one which displays a listing of available datasets) requests some images for the footer.
The initial Auspice page (i.e. the one which displays a listing of available datasets) requests some images for the footer.
## External requests
## External Requests
### Fonts
Two initial requests for fonts are made, for [google-hosted lato fonts (CSS)](https://fonts.googleapis.com/css?family=Lato:100,200,300,400,500,700) and [font-awesome (CSS)](https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css">).
Two initial requests for fonts are made, for [Google-hosted Lato fonts (CSS)](https://fonts.googleapis.com/css?family=Lato:100,200,300,400,500,700) and [font-awesome (CSS)](https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css">).
These in turn make a number of subsequent requests for the individual font files etc.
### Leaflet
We use [leaflet](https://leafletjs.com/) to display the map tiles.
We use [Leaflet](https://leafletjs.com/) to display the map tiles.
There is one [initial CSS request](https://unpkg.com/leaflet@1.0.1/dist/leaflet.css) which is always made, regardless of whether a map is displayed.
If a map is displayed by auspice the individual tiles are requested from api.mapbox.com.
If a map is displayed by Auspice the individual tiles are requested from api.mapbox.com.
Panning and zooming of the map result in futher requests for tiles.
These are requested using our hardcoded access key, however this may change to a build-time-customisation in the future.
### Google Analytics (optional)
Auspice has the potential to include google analytics in a limited fashion.
### Google Analytics (Optional)
Auspice has the potential to include Google Analytics in a limited fashion.
See [the client customisation API documentation](customise-client/api.md#available-customisations) for how to set this.
Note that these requests are only made if you specify a Google Analytics key during build-time customisation of the client.
---
title: Run Auspice
title: How to Run Auspice
---
Auspice is run as a command line program -- `auspice` -- with various subcommands.
You can run each command with `--help` attached to see help from the command line.
* `auspice view --help` (this is the main command for interacting with auspice)
* `auspice view --help` (this is the main command for interacting with Auspice)
* `auspice build --help`
* `auspice develop --help`
* `auspice convert --help`
## Get an example dataset up & running
## How to Get an Example Dataset Up and Running
In order to get up & running you'll need to have some datasets to visualise.
For the purposes of getting auspice up & running you can download the current zika dataset via:
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:
```bash
mkdir datasets
......@@ -28,7 +28,7 @@ And then run `auspice` via:
auspice view --datasetDir datasets
```
This will allow you to run auspice locally (i.e. from your computer) and view the dataset which is behind [nextstrain.org/zika](https://nextstrain.org/zika).
This will allow you to run Auspice locally (i.e. from your computer) and view the dataset which is behind [nextstrain.org/zika](https://nextstrain.org/zika).
[See below](#obtaining-a-set-of-input-files) for how to download all of the data available on [nextstrain.org](https://nextstrain.org).
......@@ -36,7 +36,7 @@ To analyse your own data, please see the tutorials on the [nextstrain docs](http
## `auspice view`
This is the main command we'll run auspice with, as it makes auspice available in a web browser for you.
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:
| argument name | data supplied | description |
......@@ -44,21 +44,21 @@ There are two common arguments used:
|datasetDir | PATH | Directory where datasets (JSONs) are sourced. This is ignored if you define custom handlers. |
|narrativeDir | PATH | Directory where narratives (Markdown files) are sourced. This is ignored if you define custom handlers. |
For more complicated setups, where you define your own server handlers, see [suppling custom handlers to the auspice server](server/api.md#suppling-custom-handlers-to-the-auspice-server).
For more complicated setups, where you define your own server handlers, see [suppling custom handlers to the Auspice server](server/api.md#suppling-custom-handlers-to-the-auspice-server).
## `auspice build`
Build the client source code bundle.
Build the client source code bundle.
This is needed in three cases:
1. You have installed auspice from source, or updated the source code.
1. You have installed Auspice from source, or updated the source code.
1. You are editing the source code and need to rebuild the client
1. You wish to build a customised version of the auspice client.
See [Customising auspice](customise-client/introduction.md) for more info.
1. You wish to build a customised version of the Auspice client.
See [Customising Auspice](customise-client/introduction.md) for more info.
## `auspice develop`
Launch auspice in development mode. This runs a local server and uses
Launch Auspice in development mode. This runs a local server and uses
hot-reloading to allow automatic updating as you edit the code.
This is only useful if you are editing the client source code!
......@@ -66,43 +66,43 @@ This is only useful if you are editing the client source code!
## `auspice convert`
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 [programatically importable](server/api.md#convertfromv1).
Currently, it only converts "Auspice v1" JSONs into "Auspice v2" JSONs, using the same code that is [programatically importable](server/api.md#convertfromv1).
Right now, `auspice view` will automatically convert "v1" JSONs into "v2" JSONs, so there's no need to do this yourself.
## Input file formats
## Input File Formats
> 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.)
Auspice takes two different file types -- datasets (the tree, map etc) are defined as one or more JSON files, while narratives are specified as a markdown file.
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.
### dataset JSONs
### Dataset JSONs
For datasets, auspice (v2.x) can currently load either
* "auspice v1" JSONs (meta + tree JSONs) -- see the JSON schemas [here](https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v1-meta.json) and [here](https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v1-tree.json).
The zika dataset we download above is in this format.
* "auspice v2" JSONs. See the JSON schema [here](https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v2.json).
For datasets, Auspice (v2.x) can currently load either
* "Auspice v1" JSONs (metadata + tree JSONs) -- see the JSON schemas [here](https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v1-meta.json) and [here](https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v1-tree.json).
_The zika dataset we download above is in this format_
* "Auspice v2" JSONs. See the JSON schema [here](https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v2.json).
See the [Server API](server/api.md) for more details about the file formats an auspice server (e.g. `auspice view`) sends to the client.
See the [Server API](server/api.md) for more details about the file formats an Auspice server (e.g. `auspice view`) sends to the client.
Currently we mainly use [augur](https://github.com/nextstrain/augur) to create these datasets.
See [the nextstrain documentation](https://nextstrain.org/docs/bioinformatics/introduction-to-augur) for more details.
Currently we mainly use [Augur](https://github.com/nextstrain/augur) to create these datasets.
See [the Nextstrain documentation](https://nextstrain.org/docs/bioinformatics/introduction-to-augur) for more details.
> We are working on ways to make datasets in newick / nexus formats available. You can see an early prototype of this at [auspice-us.herokuapp.com](https://auspice-us.herokuapp.com/) where you can drop on newick (and CSV) files.
Using BEAST trees is possible, but you have to use augur to convert them first.
> We are working on ways to make datasets in Newick / Nexus formats available. You can see an early prototype of this at [auspice-us.herokuapp.com](https://auspice-us.herokuapp.com/) where you can drop on Newick (and CSV) files.
Using BEAST trees is possible, but you have to use Augur to convert them first.
### narratives
For narratives, please see [writing a narrative](narratives/how-to-write.md) for a description of the file format.
### Narratives
For narratives, please see [Writing a Narrative](narratives/how-to-write.md) for a description of the file format.
## Obtaining a set of input files
## Obtaining a Set of Input Files
If you'd like to download the datasets & narratives which we use on nextstrain.org then there are two scripts which allow you to do this.
If you'd like to download the datasets and narratives on [nextstrain.org](https://nextstrain.org) then there are two scripts which allow you to do this:
* You can download the dataset JSONs by running [this script](https://github.com/nextstrain/auspice/blob/master/scripts/get-data.sh) which will create a `./data` directory for you.
* You can download the narrative markdown files by running [this script](https://github.com/nextstrain/auspice/blob/master/scripts/get-narratives.sh) which will create a `./narratives` directory for you.
* You can download the narrative Markdown files by running [this script](https://github.com/nextstrain/auspice/blob/master/scripts/get-narratives.sh) which will create a `./narratives` directory for you.
You can then run `auspice view --datasetDir data --narrativeDir narratives` to visualise all of the nextstrain.org datasets locally.
\ No newline at end of file
You can then run `auspice view --datasetDir data --narrativeDir narratives` to visualise all of the [nextstrain.org](https://nextstrain.org) datasets locally.
\ No newline at end of file
......@@ -2,23 +2,23 @@
title: Install Auspice
---
## Prerequisites
Auspice is a JavaScript program, and requires [nodeJS](https://nodejs.org/) to be installed on your system.
For best results, please use nodeJS version 10.
## Prerequisites
Auspice is a JavaScript program, and requires [Node.js](https://nodejs.org/) to be installed on your system.
For best results, please use Node.js version 10.
We highly recommend using [conda](https://conda.io/docs/) to manage environments, i.e. use conda to create an environment with nodejs installed where you can use auspice.
It's possible to use other methods, but this documentation presupposes that you have conda installed.
We highly recommend using [Conda](https://conda.io/docs/) to manage environments, i.e. use Conda to create an environment with Node.js installed where you can use Auspice.
It's possible to use other methods, but this documentation presupposes that you have Conda installed.
## Create a conda environment
## Create a Conda Environment
```bash
conda create --name auspice nodejs=10
source activate auspice
```
> This parallels [the nextstrain installation docs](https://nextstrain.org/docs/getting-started/local-installation#install-augur--auspice-with-conda-recommended).
> This parallels [the Nextstrain installation docs](https://nextstrain.org/docs/getting-started/local-installation#install-augur--auspice-with-conda-recommended).
You're welcome to use those instead!
## Install auspice from npm
## Install Auspice from npm
```bash
......@@ -26,35 +26,40 @@ npm install --global auspice
```
Auspice should now be available as a command-line program -- check by running `auspice --help`.
If you look at the [release notes](releases/changelog.md) you can see the changes that have been made to auspice (see your version of auspice via `auspice --version`).
If you look at the [release notes](releases/changelog.md) you can see the changes that have been made to Auspice (see your version of Auspice via `auspice --version`).
To upgrade, you can run
```bash
npm update --global auspice
```
## Installing from source
## Installing from Source
This is useful for debugging, modifying the source code, or using an unpublished feature branch.
We're going to assume that you have used conda to install nodeJS as above.
We're going to assume that you have used Conda to install Node.js as above.
```bash
# activate the correct conda enviornment
conda activate auspice
# grab the GitHub auspice repo
git checkout https://github.com/nextstrain/auspice.git
cd auspice
# install dependencies
npm install
# make `auspice` available globally
npm install --global .
# build auspice
auspice build
# test it works
auspice --version
auspice --help
```
Updating auspice is as easy as pulling the new version from GitHub -- it shouldn't require any `npm` commands.
You will, however, have to re-build auspice whenever the client-related code has changed, via `auspice build`.
\ No newline at end of file
Updating Auspice should only require pulling the new version from GitHub -- it shouldn't require any `npm` commands.
You will, however, have to re-build Auspice whenever the client-related code has changed, via `Auspice build`.
\ No newline at end of file
......@@ -3,17 +3,17 @@ title: Overview
hide_title: true
---
# Auspice: an open-source interactive tool for visualising phylogenomic data
# Auspice: An Open-source Interactive Tool for Visualising Phylogenomic Data
![splash](assets/splash.png)
*Auspice being used to show the spread of influenza H7N9 virus across Asia.*
**Auspice is software to display beautiful interactive visualisations of phylogenomic data.**
**Auspice is software to display beautiful, interactive visualisations of phylogenomic data.**
Communicating scientific results while also allowing interrogation of the underlying data is an integral part of the scientific process.
Current scientific publishing practices hinder both the rapid dissemination of epidemiologically relevant results and the ability to easily interact with the data which was used to draw the inferences.
These shortcomings motivated the [nextstrain](https://nextstrain.org) project, for which auspice was initially devloped.
Current scientific publishing practices hinder both the rapid dissemination of epidemiologically relevant results and the ability to easily interact with the data used to draw inferences.
These shortcomings motivated the [Nextstrain](https://nextstrain.org) project, for which Auspice was initially devloped.
Auspice can be run on your computer or integrated into websites.
It allows easy customisation of aesthetics and functionality, and powers the visualisations on [nextstrain.org](https://nextstrain.org).
......@@ -21,7 +21,7 @@ It allows easy customisation of aesthetics and functionality, and powers the vis
## License and copyright
## License and Copyright
Copyright © 2014-2019 Trevor Bedford and Richard Neher.
Source code to Nextstrain is made available under the terms of the [GNU Affero General Public License](LICENSE.txt) (AGPL). Nextstrain is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
---
title: "Writing a narrative"
title: "Writing a Narrative"
---
This documentation will walk us through constructing a narrative from scratch, based off [this example (nextstrain.org)](https://nextstrain.org/narratives/intro-to-narratives).
This documentation will walk us through constructing a narrative from scratch, based on [this example (nextstrain.org)](https://nextstrain.org/narratives/intro-to-narratives).
If you run into any bugs, please [get in contact with us (email)](mailto:hello@nextstrain.org).
## Step 1: Get the underlying datasets
## Step 1: Get the Underlying Datasets
You can skip this step if you ave generated your own dataset, but for the purposes of this tutorial we need the mumps dataset.
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.
```bash
mkdir datasets
......@@ -17,7 +17,7 @@ curl http://data.nextstrain.org/mumps_na_tree.json --compressed -o datasets/mump
You should now be able to visualise the dataset (without any narrative functionality) via `auspice view --datasetDir datasets`
## Step 2: Start a simple narrative
## Step 2: Start a Simple Narrative
We're going to start by creating a narrative with only one page (the title page).
......@@ -26,7 +26,7 @@ mkdir narratives
touch narratives/example.md
```
Open up `narratives/example.md` and start by pasting in the following YAML frontmatter, which is used to define some basic set-up for the narrative as well as being used to create the first narrative page.
Open up `narratives/example.md` 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.
```yaml
---
......@@ -36,39 +36,39 @@ authorLinks: "url, twitter link, mailto etc"
affiliations: "your affiliation"
date: "August 2018"
dataset: "http://localhost:4000/mumps/na?d=tree"
abstract: "This narrative is going to test the potential of the auspice narrative functionality using the publicly available North American mumps dataset."
abstract: "This narrative is going to test the potential of the Auspice narrative functionality using the publicly available North American mumps dataset."
---
```
The really important bit here is the `dataset` line -- here we're referencing the dataset we downloaded above.
The really important bit here is the `dataset` line -- this references the dataset we downloaded above.
(A [current limitation](narratives/introduction.md##nown-bugs-limitations) of narratives is that they cannot change the dataset.)
## Step 3: View the narrative so far
## Step 3: View the Narrative so Far
We don't really have much, but we can still load it up in auspice and check it's working as expected -- that we see a narrative with only one page.
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.
```bash
auspice view --datasetDir datasets/ --narrativeDir narratives/
```
And you should see something like this at [localhost:4000/narratives/example](http://localhost:4000/narratives/example)
![narrative frontpage](assets/narrative-tutorial-p1.png)
![Narrative frontpage](assets/narrative-tutorial-p1.png)
## Step 4: Adding a paragraph
## Step 4: Adding a Paragraph
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 which define when we have a new narrative pararaphs.
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.
> If you're new to markdown, take a look [at this page](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to get started.
> If you're new to Markdown, take a look [at this page](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to get started.
The heading is itself a link, which defines the view of auspice at that time.
You may have noticed that as you interact with auspice -- for this example at [localhost:4000/mumps/na](http://localhost:4000/mumps/na) -- then the URL changes.
For instance, if I use the sidebar to toggle "off" the tree & entropy, just keeping the map then you'll see that the URL has changed to [localhost:4000/mumps/na?d=map](http://localhost:4000/mumps/na?d=map).
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.
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 [localhost:4000/mumps/na](http://localhost:4000/mumps/na) -- 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 [localhost:4000/mumps/na?d=map](http://localhost:4000/mumps/na?d=map).
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.
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:
Add the following text to the narrative Markdown file:
```md
# [Map View](http://localhost:4000/mumps/na?d=map)
......@@ -77,22 +77,22 @@ We can control which panels are displayed, for instance choosing to show only th
```
And now, we should have a second page available in the narrative like so:
Now, we should have a second page available in the narrative:
![narrative page2](assets/narrative-tutorial-p2.png)
## Step 5: Adding more paragraphs
## Step 5: Adding More Paragraphs
We're going to use the same iterative technique to add more pagragraphs:
1. Use auspice ([localhost:4000/mumps/na](http://localhost:4000/mumps/na)) to change the view as you desire
1. Use Auspice ([localhost:4000/mumps/na](http://localhost:4000/mumps/na)) to change the view as you desire
2. Copy this URL and create a h1 header in the markdown file
3. Write some text in the markdown to form the narrative paragraph
3. Write some text in the Markdown to form the narrative paragraph
4. Repeat until happy 😁
You can see the contents of the markdown file behind [the example (nextstrain.org)](https://nextstrain.org/narratives/intro-to-narratives) that we're basing this tutorial on [here](https://raw.githubusercontent.com/nextstrain/narratives/master/intro-to-narratives.md).
You can use this markdown file as inspiration for creating your own paragraphs, or just copy and paste the contents!
You can see the contents of the Markdown file behind [the example (nextstrain.org)](https://nextstrain.org/narratives/intro-to-narratives) that we're basing this tutorial on [here](https://raw.githubusercontent.com/nextstrain/narratives/master/intro-to-narratives.md).
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:
```md
......@@ -116,20 +116,20 @@ have a Methionine (`M`) at this position, while aqua nodes indicate Isoleucine (
```
## Step 6: Upload your example to nextstrain community to share with everyone
## Step 6: Upload Your Example to the Nextstrain C