README.md 3.62 KB
Newer Older
james hadfield's avatar
james hadfield committed
1
2
3
[![Build Status](https://travis-ci.com/nextstrain/auspice.svg?branch=master)](https://travis-ci.com/nextstrain/auspice)
[![NPM version](https://img.shields.io/npm/v/auspice.svg?style=flat)](https://www.npmjs.com/package/auspice)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
James Hadfield's avatar
James Hadfield committed
4

5

6
7
8
9
10
Nextstrain is an open-source project to harness the scientific and public health potential of pathogen genome data.
We provide a continually-updated view of publicly available data with powerful analytics and visualizations showing pathogen evolution and epidemic spread.
Our goal is to aid epidemiological understanding and improve outbreak response.

Resulting data and inferences are available live at the website [nextstrain.org](https://nextstrain.org).
11

12
# Auspice
13

14
*Definition: Observation by an augur, ie a prophetic sign.*
Colin Megill's avatar
Colin Megill committed
15

16
Auspice is an open-source interactive web app for visualizing phylogenomic data.
james hadfield's avatar
james hadfield committed
17
18
19
20
21
It may be used in tandem with nextstrain's bioinformatics toolkit [augur](https://github.com/nextstrain/augur) or on its own.
Auspice may be used to explore datasets locally or run as a as a server to share results. 

## Documentation

22
**Please see [nextstrain.github.io/auspice](https://nextstrain.github.io/auspice) for auspice documentation.**
23

Trevor Bedford's avatar
Trevor Bedford committed
24

james hadfield's avatar
james hadfield committed
25
## Installation
Trevor Bedford's avatar
Trevor Bedford committed
26

27
```bash
james hadfield's avatar
james hadfield committed
28
29
30
npm install --global auspice
```

31
See [here](https://nextstrain.github.io/auspice/introduction/install) for full instructions, including how to install from source.
james hadfield's avatar
james hadfield committed
32
33
34
35
36
37


## Quickstart

In order to get up & running you'll need to have some datasets to visualise.
Please see the [nextstrain docs](https://nextstrain.org/docs/) for tutorials on how to do this.
38
For the purposes of getting started, you can download the current zika dataset via:
james hadfield's avatar
james hadfield committed
39

Trevor Bedford's avatar
Trevor Bedford committed
40
```
james hadfield's avatar
james hadfield committed
41
mkdir datasets
42
curl http://data.nextstrain.org/zika.json --compressed -o datasets/zika.json
james hadfield's avatar
james hadfield committed
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
```

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


Run `auspice --help` or visit [nextstrain.github.io/auspice](https://nextstrain.github.io/auspice) for more information.

## Development, comments, issues and bugs

Auspice is developed via GitHub and issues are very welcome. Alternatively, [email us](mailto:hello@nextstrain.org) with any questions or comments you may have. 
If you are interested in submitting a pull request please use [eslint](https://eslint.org/) as much as possible -- thanks! 
Trevor Bedford's avatar
Trevor Bedford committed
58

james hadfield's avatar
james hadfield committed
59
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).
zach charlop-powers's avatar
zach charlop-powers committed
60

james hadfield's avatar
james hadfield committed
61
Please see [docs-src/README](./docs-src/README.md) for how the auspice documentation site is built.
62

63
> Note that currently the documentation must be rebuilt & pushed to GitHub _after_ a new version is released in order for the changelog to correctly appear at [nextstrain.github.io/auspice/releases/changelog](https://nextstrain.github.io/auspice/releases/changelog).
64
65
66


## License and copyright
67
Copyright 2014-2019 Trevor Bedford and Richard Neher.
68

Trevor Bedford's avatar
Trevor Bedford committed
69
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.