Nextstrain logo

Tutorial: Using Nextstrain for SARS-CoV-2

Analysis

1. Setup and installation
2. Preparing your data
3. Orientation: analysis workflow
4. Orientation: files
5. Running & troubleshooting
6. Customizing your analysis
7. Customizing your visualization

Visualization & interpretation

8. Options: visualizing and sharing
9. Interpreting your results
10. Writing a narrative

Stuck? Ask us on the discussion board. We're happy to help!

This project is maintained by nextstrain

Visualizing and sharing results

Nextstrain.org uses Auspice to visualize JSON files that are created by Augur. While this is the most visible example, there are many other ways to use Auspice to visualize your results.

We'll walk through each of these in detail, roughly in order from the simplest and most private to the slightly more complex and publicly shareable.

If none of these options meet your needs, please get in touch!


First: a note on sensitive or private metadata

Below, we describe the privacy considerations for each of the available options.

One approach to handling sensitive metadata is to simply keep it entirely separate. With any of these options, you can also choose to drag-and-drop a separate TSV file onto the Auspice visualization.

Doing so will enable you to color by any of the values in this extra metadata file, but none of that data ever leaves your local computer.

How to view visualize private metadata

  1. Create a TSV file with a strain or name column that matches all the samples in your dataset
  2. Add your sensitive metadata to the remaining columns
  3. On your computer, drag and drop the file onto the browser window where Auspice is visualizing your JSON

For more help formatting this metadata file, including how to do so using Excel, see this page


Option 1: Drag-and-drop web-based visualization

How to view

  1. Navigate to https://auspice.us
  2. Drag the output JSON file from ./auspice/<buildname>.json onto the page
  3. [Optional] drag and drop a TSV with additional or private metadata onto the page (see above)

How to share

Share the JSON file and instructions directly.

Privacy and security

When your browser connects to auspice.us, it downloads from the server a version of the Auspice code which runs solely on your computer, within your browser. Then, when you drag a file onto the page, that code processes the data in your browser and displays it to you without ever sending it back to the auspice.us server. All the heavy bioinformatics computations were already performed and stored in the file you provide, which is what lets everything work quickly just on your computer.

Option 2: Nextstrain community pages

How to get started

Quickstart:

  1. Put your JSON in a github repository like so: myGithubOrganization/myRepository/auspice/<myBuildName>.json
  2. Navigate to https://nextstrain.org/community/myGithubOrganization/myRepository/myBuildName
  3. [Optional] Drag and drop a TSV with additional or private metadata onto the page (see above)

Check out our full guide to community pages here.

Privacy and security

Community builds are visible to anyone with the URL.

Option 3: Local viewing on your computer with Auspice

How to view

  1. Follow the instructions here to install Auspice on your computer.
  2. Make sure the JSON you'd like to visualize is in ./auspice/<mybuildname>.json; alternatively, pass the --datasetDir flag to specify another directory.
  3. Run auspice view and select the build of interest.
  4. [Optional] drag and drop a TSV with additional or private metadata onto the page (see above)

How to share

Share the JSON file and instructions directly.

Privacy and security

When running locally, both the server and the client run on your computer; no internet connection is requried. No data ever leaves your local machine.

Option 4: Sharing with Nextstrain Groups

How to get started

Nextstrain Groups are a new feature; if you'd like to use this option, please get in touch and we'll help you get started right away!

Privacy and security

With Nextstrain Groups, you can choose whether each dataset is publicly viewable or private to only other users in your group. Data is hosted in an AWS S3 bucket under your control, and is not shared with the Nextstrain team or anyone else.

Option 5: Deploying your own Auspice server

How to get started

See our guide here

Privacy and security

Independently hosted Auspice servers can be configured with any security protocols necessary.

Previous Section: Orientation: Customizing your visualization

Next Section: Interpreting your results