Skip to content
Permalink
Browse files

Merge pull request #312 from nextstrain/version-docs

Version Change Docs & Help
  • Loading branch information...
emmahodcroft committed Aug 5, 2019
2 parents 0d5c84d + df7f38b commit c333cc244adbabdc8f3b22606e9ff20014e26beb
Showing with 523 additions and 1 deletion.
  1. +43 −0 docs/auspice.md
  2. +38 −0 docs/breaking.md
  3. +1 −1 docs/conf.py
  4. +422 −0 docs/exportv.md
  5. +1 −0 docs/index.rst
  6. +18 −0 docs/upgrading.rst
@@ -0,0 +1,43 @@
# How Augur Export and Auspice Versions Connect

From mid-2019, we're changing the format of the output file produced by `augur export` to allow us more flexibility going forward. This lines up with a big update to `auspice`, which also opens up exciting new possibilities.

We also recognise that we may need to adjust things again in the future. By setting up versions now, we'll be able to continue to expand `augur` and `auspice` while minimizing disruption to users.

You can get more information on how to move to using `export v2` in `augur` 6.0 in our [handy guide](exportv.md).

## Why Does Compatibility Matter?

To get great visualizations, the final step of the `augur` pipeline, `augur export` produces output as (a) JSON file(s)*. This/these file(s) are then read by `auspice` to produce trees, graphs, and maps.
*_This compatibility only refers to the JSON file(s) produced by `augur export`, not those produced by other `augur` steps._
Different `augur` versions will produce different JSON output formats, which in turn will work with different `auspice` versions. We aim to support backwards compatibility as much as possible, and of course, if you're you're using the latest `augur`, JSON, and `auspice` versions, everything will work smoothly!
Whenever possible, we recommend updating your run to work with the latest `augur` and outputing the most recent JSON format to view with the latest `auspice` - it future-proofs your work and ensures you'll benefit from all the latest features and improvements.
But, we know that for a variety of reasons, you can't always do this straight away. To help keep your research flowing, here are some tables of how different versions of `augur`, export JSONs, and `auspice` are compatible.
## Compatibility Tables
### Augur
| Augur Version | Produces JSON | Works with Auspice |
| ------------- |---------------| --------------------|
| 5.x | v1 (via `export`) | 1.x or 2.0 |
| 6.0 | v1 (via `export v1`) <br> v2 (via `export v2`) | 1.x or 2.0 |
### `export` JSON versions
| JSON Version | Produced by Aupice Version | Works with Auspice |
| -------------|---------------| --------------------|
| v1 | 5.x (via `export`) <br> 6.0 (via `export v1`)| 1.x or 2.0 |
| v2 | 6.0 (via `export v2`) | 2.0 |
### Auspice
| Auspice Version | Takes JSON | Produced by Auspice Version |
| -------------|---------------| --------------------|
| 1.x | v1 | 5.x (via `export`) <br> 6.0 (via `export v1`) |
| 2.0 | v1 <br> v2 | 5.x (via `export`) <br> 6.0 (via `export v1`) <br> 6.0 (via `export v2`) |
@@ -0,0 +1,38 @@
# Breaking Changes to `augur`

This is a list of known 'breaking changes' to `augur`. These are changes that require users to modify existing scripts or calls to `augur` functions because the old usage is no longer supported. 'Depreciated' changes, which work for the moment but will no longer be supported in future, are also included.

_Note this list only includes changes to `augur` code and may not cover breaking changes introduced due to changes in dependancy packages. We try to support these too, so please [open an issue](https://github.com/nextstrain/augur/issues/new) if you think you've found something we didn't catch._

This list will **only** be helpful if you are _sure_ the command used to work and only stopped working after you upgraded your `augur` installation. If your `augur` installation is from earlier than 2019, or if this list doesn't solve your problem, run `--help` for the command you're using and use that information to try re-writing your call.

Click on the `augur` function that used to work, and we'll try to get you up and running ASAP!

* [ancestral](#ancestral)
* [export](#export)

## ancestral

### `--output` argument

* **Possible error/warning messages:**<br>
> > "WARNING: the `--output` flag will be deprecated in the next major augur release. Use `--output-node-data` instead."
> > augur: error: unrecognized arguments: `--output`
* **Solution:**<br>
To specify the JSON file to write ancestral mutations/sequences to, use the argument `--output-node-data` instead of `--output`.<br><br>

* **Explanation:**<br>
`ancestral` now supports outputting a Fasta file of reconstructed ancestral sequences (for Fasta-input runs - this was already supported in VCF-format for VCF-input runs). Users can ask for this output and specify a file name using `--output-sequences`. Since there are now two types of output from `ancestral`, the arguments have become more descriptive.<br><br>


## export

### Version error

* **Possible error/warning messages:**<br>
> > augur export: error: the following arguments are required: Augur export now needs you to define the JSON version you want, e.g. `augur export v2`.
* **Solution:**<br>
We've upgraded `augur export`. Find out how to adjust your `augur export` call to work with the latest version [using our handy guide](exportv.md).<br><br>
@@ -53,7 +53,7 @@ def prose_list(items):
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['recommonmark', 'sphinx.ext.autodoc', 'sphinxarg.ext', 'sphinx.ext.napoleon']
extensions = ['recommonmark', 'sphinx_markdown_tables', 'sphinx.ext.autodoc', 'sphinxarg.ext', 'sphinx.ext.napoleon']

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

0 comments on commit c333cc2

Please sign in to comment.
You can’t perform that action at this time.