Commit 643cfd57 authored by james hadfield's avatar james hadfield
Browse files

[docs] add v2 release notes

parent b97f1945
---
title: "Version 2"
---
## Backstory
Auspice started as the [nextstrain.org](https://nextstrain.org) visualisation tool, in fact for a long time [nextstrain.org](https://nextrstrain.org) _was_ auspice.
Slowly, we turned auspice into a stand-alone tool and started expanding its capacity.
This resulted in many v1.x releases (we made it all the way to v1.39.0), and things had a habit of changing a little too frequently, with not enough focus on documentation and communication.
So in a way, this is the first proper auspice release!
There are a few big & visible changes, including using pie charts to represent discrete variables on a map, but a lot of the changes were done to make things easier behind the scenes.
There are also a bunch of really cool features such as the ability to define custom servers, change the aesthetics of the auspice client, dsiplay multiple trees and write narratives which were technically part of auspice v1 but poorly documented.
This documentation website is now up to date and should allow you to understand how to use auspice to its full potential ([contributions always welcome!](contributing/overview.md))
In general, we hope that this documentation and the help messages of the various `auspice` subcommands are vastly improved.
The major changes which auspice v2 brings are detailed below 👇
If you have any comments please [email us](mailto:hello@nextstrain.org) or say hi on [twitter](https://twitter.com/hamesjadfield).
## I don't want to upgrade - how can I continue to use auspice v1?
While I don't think there is any reason to _not_ upgrade, version 1 will always be available via npm:
```bash
npm install --global auspice@version1
```
## Pie charts to represent discrete variables on a map
We used to use colour blending to represent all the different traits present at a given location.
This worked pretty well for continous traits (e.g. the dates of isolates in each country), but performed poorly for discrete traits (e.g. the different flu clades present in each country).
We now use pie charts for discrete traits which gives a much nicer summary of the data:
![pie-charts](assets/v2-pie-charts.png)
*Notice the difference? Auspice v1 (left) & v2 (right)*
## New dataset JSON format
For about a year we've been seeing the limitations of the "v1" meta + tree JSONs (the dataset files behind auspice).
Additionally the format of the input JSONs to auspice changed a bit throughout the lifetime of auspice v1 - fine when it's an internal tool, but not so great when other people start to use it!
We've settled on a new single "v2" JSON, containing pretty similar information to the v1 JSONs but in a format which allows us to expand the functionality of auspice.
> Don't panic - `auspice view` and [nextstrain.org](https://nextstrain.org) will automatically convert the "v1" JSONs into the new format for you so all of the old datasets will continue to work with auspice v2.
| file | schema | auspice versions | description |
| ---- | ---- | ---- | ---- |
|"tree" JSON | [Link](https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v1-tree.json) | v1, v2 | Decorated phylogenetic tree |
|"meta" JSON | [Link](https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v1-meta.json) | v1, v2 | The "metadata" associated with a phylogenetic tree |
|"v2" JSON | [Link](https://github.com/nextstrain/augur/blob/v6/augur/data/schema-export-v2.json) | v2 | The single input format required for auspice v2 |
If you use augur to construct your JSONs, then the next version of augur (v6) will give you the option to produce "v1" or "v2" JSONs.
If you have specific queries, the JSON schemas (above) should help you out, but here is a list of the main changes (with links to PRs where relevent, if you're _really_ keen!):
#### Strings parsed unchanged
For historical reasons, we used to "prettify" certain strings in auspice - e.g. "usa" became "USA", "new_zealand" became "New Zealand".
We dug ourselves into a bit of a hole here, as you can imagine the list of exeptions keeps growing and growing.
Auspice v2 now generally parses strings as they appear in the JSON, allowing you full control over how things appear.
(For backwards compatability, we've kept the "prettifying" function in the v1-v2 conversion logic so v1 JSONs should look unchanged.)
#### Both meta & tree in a single JSON
The most visible change is probably the reduction of two JSONs (meta + tree) into a single JSON.
This single JSON has three required (and no optional) keys:
```json
{
"version": "schema version",
"meta": {},
"tree": {}
}
```
#### Gene / genome definitions are now in GFF format.
v1 auspice JSONs used 0-based starts for the gene positions and `1`/`-1` for which strand the gene was on.
We now use one-based start & end coordinates, following GFF format, and a "+" or "-" to denote the strand.
See [PR #770](https://github.com/nextstrain/auspice/pull/770).
These definitions are now under the `genome_annotations` property (formerly `annotations`).
#### Changes to how node data is stored
Each tree node (internal & terminal) can now contain the following properties
* `name` (required) -- formerly this was `strain`
* `node_attrs` -- attributes associated with the node (sequence, date, location) as opposed to changes from one node to another.
* Node attributes can now be objects and contain confidence information if available.
* A `hidden` node attribute can control auspice's display of the node
* Author information is now contained under the `author` key, and the `author_info` dictionary is no longer present in the JSON.
* `branch_attrs` -- attributes associated with the branch from the parent node to this node, such as branch lengths, mutations, support values
* `branch_attrs.mutations` -- both AA & nucleotide mutations are now defined in the same object.
* `children` (unchanged)
#### Colorings, geographic resolutions and defaults
The `colorings` property (formerly `color_options`) is now an array of objects, the properties of which are easier to understand.
This guarantees the ordering appears in auspice as you define it in the JSON.
The `geo_resolutions` property (formerly `geo`) is similarly an array of objects.
The `display_defaults` property (formerly `defaults`) now contains keys which are snake_case instead of camelCase.
#### Multiple Maintainers
The maintainer, displayed in the auspice footer, was previously limited to a single string value and corresponding URL.
We now allow multiple maintainers, each with their own (optional) URL.
#### Continous, Categorical, Ordinal & Boolean Color Scales
Traits with the "boolean" colour type which will use a pre-defined yellow & blue colour scale.
Currently "continous" and "categorical" scales both use the same colour scale.
Note that "discrete" types from v1 JSONs will be interpreted as "categorical".
## More information in tree info boxes
We've made more things available when you hover over the tree or click on a tree tip.
For instance, v1 would use the aa-nt toggle in the entropy panel to decide which mutations to display, and it was frustrating to have to scroll down to switch the toggle just to see what nucleotide mutations were on a branch!
We now show both.
![more-tree-info](assets/v2-tree-info.png)
*Auspice v1 (left) & v2 (right). v2 shows more information on both tree hover (upper panel) & when clicking on tips (lower panel).*
## Display of Second Trees
Auspice has had the ability to display two trees side-by-side for a while now (although it remains sorely undocumented!).
If you wanted to, say, compare influenza HA & NA trees, the URL used to look like "flu/seasonal/h3n2/ha:na/2y".
This turned out to be problematic when coming up with suitable candidates for potential second-trees, and also made it impossible to compare, for instance, "ha/2y" with "na/3y"
We now use a more verbose syntax to define the display of multiple trees, specifying the entire pathname for both datasets.
The above example is now "flu/seasonal/h3n2/ha/2y:flu/seasonal/h3n2/na/2y".
Any available datasets can be compared using this URL syntax, even if the result is rather nonsensical.
P.S. The list of available second trees, which is displayed in the sidebar, is now handed to auspice by the [getAvailable API request](server/api.md#charon-getavailable).
## Display better dates on the tree axis
Internally, we use decimal dates (e.g. 2012.3 is around the start of may) so that's what we displayed on the tree.
It turns out this is pretty hard to interpret when looking at small timespans!
We now (a) show dates on the tree's x-axis using months & days, depending on the timespan displayed, and (b) try to use more informative grid spacings.
These help with the interpretation of trees over smaller time scales.
See [PR #804](https://github.com/nextstrain/auspice/pull/804).
![time-labels](assets/v2-time-labels.png)
*Above: auspice v1's decimal labels were somewhat hard to interprete. Below: v2 displays calendar dates as appropriate, and uses more intelligent grid spacing.*
## Map "reset zoom" button zooms to include all demes
There's now a button at the top-right of the map which will trigger the map to reset the zoom.
See [PR #802](https://github.com/nextstrain/auspice/pull/802).
## Consistent colouring of missing data in the tree
If your analysis produces results in `-` (gaps), `X` (unknown residue) or `N` (unknown nucelotide) then we now colour these as grey, making it much easier to see when data is missing.
See [PR #799](https://github.com/nextstrain/auspice/pull/799).
![base-colours](assets/v2-base-colours.png)
*Same analysis, different colour schemes, different interpretation.*
## Removal of twitter & google analytics
These were a hangover from the early days when [nextstrain.org](https://nextrstrain.org) and auspice were the same thing.
We've now removed all calls to twitter, and made Google Analytics opt in.
See [requests made from the client](customise-client/requests.md) for details on exactly what requests are made and how to opt-in to Google Analytics if you desire.
## Importing (server) code from auspice
Auspice now makes a few helper commands available for those who are writing custom auspice servers.
See [these docs](server/api.md#importing-code-from-auspice) for more info.
## New auspice subcommand: `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).
Right now, `auspice view` will automatically convert "v1" JSONs into "v2" JSONs, so there's no need to do this yourself.
## Ability to show a "build" source URL in the sidebar
Auspice used to contain some hard-coded logic which was used by nextstrain to display a link to the GitHub repo behind community URLs.
We have now generalised this, and the [getAvailable API request](server/api.md#charon-getavailable) can define a `buildUrl` property for each dataset which auspice will display in the sidebar.
......@@ -20,10 +20,11 @@
"narratives/how-to-write"
],
"Release Notes": [
"releases/changelog"
"releases/changelog",
"releases/v2"
],
"Contributing": [
"contributing/documentation"
"contributing/overview"
]
}
}
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment