Share via Nextstrain Groups

Hint

This how-to guide assumes familiarity with the Nextstrain Groups feature and the Nextstrain dataset files produced by running a pathogen workflow. We recommend reading about those first if you’re not familiar with them.

Log in with the Nextstrain CLI

Before you can upload data to your Nextstrain Group, you need to log into nextstrain.org with the Nextstrain CLI’s nextstrain login command so it knows how to access your group’s data.

nextstrain login

Confirm that you have access to your group by running nextstrain whoami.

nextstrain whoami

You should see your group name in the output.

You can also try listing your group’s datasets and narratives with nextstrain remote list. Replace ${GROUPNAME} below with your group name.

nextstrain remote list nextstrain.org/groups/${GROUPNAME}

This will likely return nothing for now since groups start without any datasets or narratives. However, the lack of an error is useful to see.

Upload a Nextstrain dataset

Warning

Do not upload any files containing personally identifiable information (PII). This restriction applies for public and private groups.

Upload one or more Nextstrain datasets for your group using the nextstrain remote upload command. An example using a dataset produced by our ncov workflow. The pattern of your dataset and sidecar filenames and desired display URL to upload may be different.

nextstrain remote upload \
  nextstrain.org/groups/${GROUPNAME}/ncov/${YOUR_BUILD_NAME} \
    auspice/ncov_${YOUR_BUILD_NAME}.json \
    auspice/ncov_${YOUR_BUILD_NAME}_tip-frequencies.json \
    auspice/ncov_${YOUR_BUILD_NAME}_root-sequence.json

After the upload completes, it’ll appear in the group listing when you run:

nextstrain remote list nextstrain.org/groups/${GROUPNAME}

You can also navigate to your groups page on the web to see the dataset listed there.

If you have multiple datasets to upload, you can do so with one command if their filenames match the URLs you want.

nextstrain remote upload nextstrain.org/groups/${GROUPNAME} auspice/*.json

Remove a dataset

Use the nextstrain remote delete command to remove a dataset or narrative you’ve uploaded.

nextstrain remote delete nextstrain.org/groups/${GROUPNAME}/ncov/${YOUR_BUILD_NAME}

Example

Below is an example of what the steps above look like for a user trs and group test:

$ nextstrain login
Logging into Nextstrain.org…

Username: trs
Password:

Credentials saved to /home/tom/.nextstrain/secrets.

Logged into nextstrain.org as trs.
Log out with `nextstrain logout`.

$ nextstrain whoami
username: trs
email: tsibley@…
groups:
  - test/editors

$ nextstrain remote list nextstrain.org/groups/test

$ nextstrain remote upload \
    nextstrain.org/groups/test/ncov/example \
      auspice/ncov_example.json \
      auspice/ncov_example_tip-frequencies.json \
      auspice/ncov_example_root-sequence.json
Uploading auspice/ncov_example.json as https://nextstrain.org/groups/test/ncov/example
Uploading auspice/ncov_example_root-sequence.json as https://nextstrain.org/groups/test/ncov/example (root-sequence)
Uploading auspice/ncov_example_tip-frequencies.json as https://nextstrain.org/groups/test/ncov/example (tip-frequencies)

$ nextstrain remote list nextstrain.org/groups/test
https://nextstrain.org/groups/test/ncov/example

$ nextstrain remote delete nextstrain.org/groups/test/ncov/example
Deleting nextstrain.org/groups/test/ncov/example

You’ll of course have to login as yourself, and be sure to replace test with your group’s name when you try it!

Learn more

Learn more about the above commands and parameters in the following reference material:

• nextstrain remote

• nextstrain remote list

• nextstrain remote upload

• nextstrain remote download

• nextstrain remote delete

• nextstrain.org remote