Find where two outbreaks came from

Start

How to use this guide

Each step has two parts.

The story

Our “database”: samples from Pichigan and Dexas

Bovine tuberculosis (Mycobacterium bovis) was found in two states.

21 samples came from known places: 7 from Pichigan and 14 from Dexas. Each one has a county name.

In this training, these 21 samples are our database: samples we already know.

Made upThe DNA data is real and public. Everything else is made up for training: the country, the states, the counties and the outbreaks. Pichigan and Dexas look like real places, but they are not. Every sample name ends in _notReal.

The story

Then two outbreaks start. Where did they come from?

OUTBREAK1: 3 new samples from Bisconsin.

OUTBREAK2: 2 new samples from New Rexico.

We do not know where these 5 samples came from. They are our unknowns.

Your mission: compare the 5 unknowns with the 21 database samples. Which county is each outbreak closest to?

HowvSNP3 finds the small DNA differences (SNPs) between samples. Few differences = closely related.

In real lifeThis training's database has known samples from only two states, Pichigan and Dexas. A real database would hold many more: every dot on the map is a past outbreak, and its samples could be in the database too.

The story

Your 26 samples

All 26 are Mycobacterium bovis, the bacterium that causes bovine TB.

The story

The plan

Four parts: A, B, C and D. Part C has four stages. The times are for a normal laptop.

A. Install (first time only)

A1 · What you need

Check this list before you start.

A. Install (first time only)

A2 · Open the Terminal macOS

The Terminal app is already on every Mac.

Last login: Wed Oct  1 09:12:44 on console
you@your-Mac ~ % 

A. Install (first time only)

A2 · Open a terminal Linux

Most Linux computers open a terminal with one key combination.

you@your-computer:~$ 

A. Install (first time only)

A2 · Turn on Linux for Windows (WSL) Windows

Windows runs the tools inside Ubuntu, a version of Linux. You do this once.

Enter new UNIX username: 
ana
New password:
Installation successful!
ana@MY-PC:~$ 

A. Install (first time only)

A3 · Get git and Rosetta 2 macOS

git downloads the tools for you. On a Mac it comes with Apple's free command-line tools.

$ git --version
git version 2.39.5 (Apple Git-154)

A. Install (first time only)

A3 · Get git and curl LinuxWindows

git downloads the tools for you. curl downloads files.

$ git --version
git version 2.43.0

A. Install (first time only)

A4 · Download Miniforge

The same command works on every computer. It picks the right file for you.

$ curl -L -O "https://github.com/conda-forge/…/Miniforge3-$(uname)-$(uname -m).sh"
  % Total    % Received % Xferd  Average Speed   Time
100  118M  100  118M    0     0  93.6M      0  0:00:01
$ 

A. Install (first time only)

A5 · Run the Miniforge installer

Copy the command, paste it, press Enter.

installation finished.
Proceed with initialization? [yes|no]
[no] >>> yes
==> For changes to take effect, close and re-open your current shell. <==
Thank you for installing Miniforge3!

A. Install (first time only)

A6 · Close the terminal and open a new one

Do not skip this step. The new window knows about conda. The old one does not.

(base) $ conda --version
conda 26.7.2

A. Install (first time only)

A7 · Download the tools

This gets the installer and the dashboard. It also decides where your tools live.

$ git clone https://github.com/kapurlab/bioinformatic_diagnostic_tools.git
Cloning into 'bioinformatic_diagnostic_tools'...
Receiving objects: 100% (2488/2488), 5.69 MiB, done.
$ cd bioinformatic_diagnostic_tools
$ pwd
/Users/you/bioinformatic_diagnostic_tools

$ git clone https://github.com/kapurlab/bioinformatic_diagnostic_tools.git
Cloning into 'bioinformatic_diagnostic_tools'...
Receiving objects: 100% (2488/2488), 5.69 MiB, done.
$ cd bioinformatic_diagnostic_tools
$ pwd
/home/you/bioinformatic_diagnostic_tools

A. Install (first time only)

A8 · Install the tools

One command installs vSNP3 and the other tools of the suite, with everything they need.

  ok Install complete.
  Your tools are here:   /Users/you/bioinformatic_diagnostic_tools
  …
Set up reference databases now (Kraken2, BLAST, vSNP)? [y/N]: N
  checking your installs are ready to run…
vsnp_gui
  ✓ environment present
  ✓ python modules (4) import
  ✓ programs on PATH
  ✓ vSNP reference options
  …
amr_plus_gui
  ✗ AMRFinderPlus DB missing …
  …
kraken_id_parse_gui
  ✗ Kraken2 DB missing …
  ✗ BLAST ref_prok_rep_genomes missing …
  …
  !! 2 tool(s) need attention — run the suggested fix above, …
  opening the dashboard …

  ok Install complete.
  Your tools are here:   /home/you/bioinformatic_diagnostic_tools
  …
Set up reference databases now (Kraken2, BLAST, vSNP)? [y/N]: N
  checking your installs are ready to run…
vsnp_gui
  ✓ environment present
  ✓ python modules (4) import
  ✓ programs on PATH
  ✓ vSNP reference options
  …
amr_plus_gui
  ✗ AMRFinderPlus DB missing …
  …
kraken_id_parse_gui
  ✗ Kraken2 DB missing …
  ✗ BLAST ref_prok_rep_genomes missing …
  …
  !! 2 tool(s) need attention — run the suggested fix above, …
  opening the dashboard …

A. Install (first time only)

A9 · The dashboard opens

This is your home page for the tools.

▶ Do this

1. Wait. Your web browser opens by itself.
2. If no browser opens: find the line Open this in your web browser: in the terminal. Copy the address under it into your browser.
3. Leave the terminal window open. The tools stop when it closes.

Terminal

  Open this in your web browser:
      http://127.0.0.1:8080/
  Keep this window open while you work (Ctrl-C stops everything).

✔ You should see

The Bioinformatic Diagnostic Tools dashboard, with a card for each tool. vSNP3 (SNP analysis & phylogeny) is the first card, with a Launch button.

Needs setup?Two cards, AMRFinderPlus and Kraken ID-Parse, say needs setup: they need the databases you skipped in A8. Some cards also show a ⚠ note. This training does not use those tools, so you can ignore both.

Done!The install is finished. You never need to do Part A again on this computer.

B. Start here next time

B1 · Open the dashboard again

Two commands. Do this every time you want to use the tools.

▶ Do this

1. Open a terminal (step A2).
2. Go to the tools folder:
   cd ~/bioinformatic_diagnostic_toolsCopy
3. Start the dashboard:
   bin/bdtools dashboardCopy

✔ You should see

The terminal prints the dashboard's address and stays busy. Leave it open.

Terminal

$ bin/bdtools dashboard
  Bioinformatic Diagnostic Tools (bdtools)
  Open this in your web browser:
      http://127.0.0.1:8080/
  Keep this window open while you work (Ctrl-C stops everything).

Your browser opens the dashboard, the same page as in step A9. On Linux the address ends with ?t= and a key: if you copy it by hand, copy all of it.

Even easierMake a Desktop icon once: run bin/bdtools make-launcher. Then double-click Kapur Lab Dashboard on your Desktop to start the dashboard.

Even easierMake a menu icon once: run bin/bdtools make-launcher. Then open Kapur Lab Dashboard from your applications menu.

WindowsOpen Ubuntu first (Start → Ubuntu). The dashboard address works in your normal Windows browser.

B. Start here next time

B2 · The dashboard: check, update, restart, stop

Once the dashboard is open, its page does the rest. Keep this page.

I want to…	On the dashboard page	Or in the terminal
Check that the tools are ready	Look at the cards. A ready tool shows only its version. A tool with a problem says needs setup and lists the fix.	bin/bdtools doctor
See if there is a newer version	At the bottom: ✓ Up to date or ↑ Updates available. Click Re-check to look again.	bin/bdtools check-updates
Update	Click the numbered buttons at the bottom, in order. See B3.	git pull bin/bdtools update all
Restart the dashboard	Click ↻ Restart dashboard at the bottom.	bin/bdtools dashboard --restart
Stop everything	Click ⏻ Shut down at the bottom.	Ctrl + C

Terminal commandsType them inside the tools folder: first cd ~/bioinformatic_diagnostic_tools. The dashboard must be running for its buttons to work (B1).

Your filesYour projects are in the projects folder in your home folder. Shut down and updates do not delete them.

B. Start here next time

B3 · Update the tools

New versions fix problems. The dashboard tells you when there is one.

▶ Do this

On the dashboard, scroll to the bottom. ✓ Up to date means there is nothing to do.

1. If it says ↑ Updates available, click the button with the number 1 (here 1 Update bdtools). A box asks if you are sure: click OK.
2. Wait until the log says Update finished and ✅ Finished. Then click ↻ Restart dashboard and OK.
3. The box checks again. If a button is left (here 1 Install tool updates (1)), click it and OK. It rebuilds the tool: a few minutes.
4. When it says ✅ Finished, click ↻ Restart dashboard again. Then click Launch on the vSNP3 card.

✔ You should see

Each update ends with Update finished and ✅ Finished under its log. After the last restart, the box says ✓ Up to date and the vSNP3 card shows the new version number. An old vSNP3 tab now says vsnp_gui is not running — launch it from the dashboard: close it and click Launch.

Slow internet?An update downloads new files, and may rebuild a tool. It takes a few minutes, longer on slow internet. Do not close the terminal while it runs.

In the terminalThe same, typed in the tools folder: git pull, then bin/bdtools update all, then bin/bdtools dashboard --restart. Updates keep your projects.

C. Run the analysis

C1 · Open vSNP3

vSNP3 opens in its own tab. Keep the dashboard tab open too.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor › Step 1 › Step 2 › Live Logs

▶ Do this

On the dashboard, find the card SNP analysis & phylogeny.

1. Click Launch. (When vSNP3 is already running, the button says Open.)

✔ You should see

A new browser tab: vSNP GUI and its version number (here v0.4.127; yours may be newer). At the top: PROJECT None.

WaitIf the tab says vsnp_gui is starting … Reload in a few seconds, wait 5 seconds and reload the page.

SettingsYou do not need to change anything in Settings. Your own name shows in the paths instead of “trainee”.

C. Run the analysis

C2 · Create a project

A project is a folder that keeps one analysis together.

On the vSNP3 page: Settings › Projects & Inputs → Projects › Reference Editor › Step 1 › Step 2 › Live Logs

▶ Do this

Scroll down to Projects.

1. Click the box New project name (e.g. LSDV_India) and type Outbreak_training.
2. In the list -- reference (optional) --, choose Mycobacterium_AF2122.
3. Click Create.

✔ You should see

A new card: Outbreak_training, with a green tag Mycobacterium_AF2122 and FASTQ: 0 | Step1: 0 | VCF DB: 0.

Why this reference?A reference is a known, complete genome. Mycobacterium_AF2122 is the standard M. bovis genome. Our samples are M. bovis.

C. Run the analysis

C3 · Open the project

Click the project before you do anything else.

On the vSNP3 page: Settings › Projects & Inputs → Projects › Reference Editor › Step 1 › Step 2 › Live Logs

▶ Do this

1. Click the Outbreak_training card.

✔ You should see

The card gets a red outline. At the top of the page: PROJECT Outbreak_training. The Download button is now dark green.

ImportantA new project does not open by itself. Always click it first. If buttons are pale and do nothing, no project is open.

C. Run the analysis

C4 · Download the 26 samples

vSNP3 downloads the DNA reads for you.

On the vSNP3 page: Settings › Projects & Inputs → Inputs › Reference Editor › Step 1 › Step 2 › Live Logs

▶ Do this

First copy the 26 SRA numbers: ⧉ Copy all 26

1. In SRA Download, click the box SRR/SRX/SRS accessions (one per line) and paste.
2. Leave Optional subfolder empty. Click Download.

✔ You should see

Under the button: Downloading 26 accessions… and a timer.

Where from?vSNP3 downloads the reads from a free public library (NCBI SRA, through the European copy at ENA). It downloads about 5 GB, so on slow internet this step takes a long time (see C5).

C. Run the analysis

C5 · Wait for the download

Each sample has two files: R1 and R2 (the two ends of each DNA piece).

On the vSNP3 page: Settings › Projects & Inputs → Inputs › Reference Editor › Step 1 › Step 2 › Live Logs

▶ Do this

1. Wait. Do not close the tab or the terminal.
2. You can follow the progress in Live Logs at the bottom of the page.

✔ You should see

Download complete and Last download: 26 downloaded. On the right, Ready to run (26 samples) lists every sample as paired · R1+R2.

TimeAbout 10–30 minutes with good internet (5.1 GB). On slow internet it can take 1–2 hours. Our test took 16 minutes.

If some failedSometimes the download server refuses a file. Then the box says Failed — 1 and names the sample. Copy all 26 again, paste them, and click Download again. Samples you already have are skipped, so only the missing ones download.

C. Run the analysis

C6 · Step 1: grab the samples

Step 1 needs the reads in its own folder. One button does it.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor › Step 1 › Step 2 › Live Logs

▶ Do this

Scroll down to Step 1. Reference already says Mycobacterium_AF2122.

1. Do not tick any boxes. Click Grab ready-to-run samples.

✔ You should see

52 file(s) staged. The Samples list shows 26 samples, each Not Started.

Why 52?26 samples × 2 files (R1 and R2) = 52 files.

C. Run the analysis

C7 · Step 1: run

This is the slow part. You can take a break.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor › Step 1 › Step 2 › Live Logs

▶ Do this

1. Click Run (under Grab ready-to-run samples).

✔ You should see

The button says Running… with a timer, and a Stop button appears. Samples change from Not Started to Running to Complete. Three run at the same time.

TimeAbout 20–60 minutes on a laptop. Our test computer (a 64-core workstation) took 6 minutes.

What happensFor each sample, vSNP3 lines up millions of short reads on the reference genome and lists every place where the sample is different (a VCF file).

C. Run the analysis

C8 · Step 1: finished

When the last sample is done, vSNP3 collects the 26 results.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor › Step 1 › Step 2 › Live Logs

▶ Do this

1. Wait until all 26 samples say Complete.
2. Scroll the Samples list to check them all.

✔ You should see

All samples Complete. The button says Run again. At the bottom of the panel: vcf_database: 26 VCFs.

New project nameThe project now shows as Outbreak_training_Mycobacterium_AF2122. vSNP3 adds the reference name. This is normal.

C. Run the analysis

C9 · Check the quality

Before Step 2, check that every sample is good enough.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor › Step 1 → Step 1 Results › Step 2 › Live Logs

✔ You should see

Step 1 Results fills in by itself: Loaded 26 sample(s). 25 PASS and 1 REVIEW: SRR33585214, “mapping rate 89.8%”.

▶ Do this

1. Scroll the table to the right to see Avg Depth and Mapping %. Check them with the table below.
2. Do not tick Exclude. We keep all 26 samples.

Column	Good	Ours	Meaning
Avg Depth	20 or more	38 to 116	How many reads cover each letter of the genome, on average.
Mapping %	90% or more	90% to 100% (one 89.8%)	How many reads match the reference.
Genome Cov	near 100%	about 99.5%	How much of the genome has reads.

Why keep SRR33585214?Its mapping rate is just under 90%, so vSNP3 asks you to look. Its depth (38) is good, so the SNP calls are still reliable.

C. Run the analysis

C10 · A first clue: the Groups column

Use the SRR numbers and the sample table (page “Your 26 samples”) to see which group each state is in.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor › Step 1 → Step 1 Results › Step 2 › Live Logs

Look at the Groups column. vSNP3 already sorted every sample into a group, using a few defining SNPs:

• The Pichigan samples and the New Rexico samples are in Mbovis-04B6.
• The Dexas samples and the Bisconsin samples are in Mbovis-04C7.

ExampleIn the picture, SRR33629183 is a New Rexico sample (red, unknown). Its group is Mbovis-04B6, the same as the Pichigan samples SRR33561021 and SRR33665434.

So farThis tells us the state. Step 2 will tell us the county.

C. Run the analysis

C11 · Give the samples their names

Do this before Step 2. Then the tree shows the state and county, not only numbers.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor → Sample Metadata › Step 1 › Step 2 › Live Logs

▶ Do this

1. Scroll up to Reference Editor. Under Reference Type, choose Mycobacterium_AF2122.
2. On the right, find the card Sample Metadata. Click Bulk paste (tab-delimited).
3. Copy the names: ⧉ Copy the 26 names. Paste them in the box.
4. Click Add 26 rows.

✔ You should see

Saved — 26 added, 0 updated (26 total), a table of Original name → Display label, and vcf_database coverage: 26 / 26 samples have metadata · All samples covered.

WhyWithout names, the tree shows only SRR numbers. With names, it shows the year, state and county of each sample.

C. Run the analysis

C12 · Step 2: build the comparison set

Step 2 compares a set of VCF files. First you choose and collect the set.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor › Step 1 › Step 2 › Live Logs

▶ Do this

Scroll down to Step 2. Box 2 says No reference databases are configured: nothing to do there.

1. Check box 1: it is ticked and says vcf_database (26 of this project's 26 Step 1 samples collected). Leave it.
2. In box 3, click Build comparison set.

✔ You should see

Comparison set by source: vcf_database: 26 and This run compares 26 of the 26 VCFs in the set — ready to Run.

C. Run the analysis

C13 · Step 2: run

Step 2 builds a SNP table and a tree for each group.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor › Step 1 › Step 2 › Live Logs

▶ Do this

1. Click Run (under Step 2 Options). Do not change the options.

✔ You should see

Running…, then Last Build — Step 2 complete.

On the right, Step 2 Results shows the new comparison with 6 groups:

TimeAbout 1–3 minutes. Our test took 22 seconds.

C. Run the analysis

C14 · Step 2 Results

Each group has its own tree and SNP tables.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor › Step 1 › Step 2 → Step 2 Results › Live Logs

Group	Samples	What it is
Mbovis-All 26×230	26	All samples in one tree. We use this one.
Mbovis-04B6 9×82	9	Pichigan + New Rexico
Mbovis-04C7 17×74	17	Dexas + Bisconsin

26×230means 26 samples and 230 SNP positions. Mbovis-04, -04B and -04C are bigger family groups that contain the smaller ones.

C. Run the analysis

C15 · Open the tree

A tree shows which samples are most alike.

On the vSNP3 page: Settings › Projects & Inputs › Reference Editor › Step 1 › Step 2 → Step 2 Results › Live Logs

▶ Do this

1. Click the ▶ next to Mbovis-All. Its files open.
2. Click View tree.

✔ You should see

A new tab: Tree viewer, 27 leaves. Each name is one sample. The names have the year, state and county.

C. Run the analysis

C16 · Find the outbreak samples

The tree can colour the samples you search for.

Where: the Tree viewer tab (it opened in C15). The vSNP3 page stays open in its own tab.

▶ Do this

1. In Scale, choose SNPs. The ruler at the top now counts SNPs.
2. Click the box Find tip… and type OUTBREAK.

✔ You should see

The 5 outbreak samples turn red: 3 Bisconsin (top) and 2 New Rexico (bottom). It says 1 of 5.

C. Run the analysis

C17 · Read the tree

Look at the black name that joins each red group.

Where: the Tree viewer tab (it opened in C15). The vSNP3 page stays open in its own tab.

• Samples that join with short lines have few SNPs between them. They are closely related.
• The 3 Bisconsin samples join with SRR33914654 … DEXAS_countyF.
• The 2 New Rexico samples join with SRR33818626 … PICHIGAN_countyX.
• The top part of the tree is Dexas (+ Bisconsin). The bottom part is Pichigan (+ New Rexico).

C. Run the analysis

C18 · Count the SNPs: Bisconsin

A clade is a branch of the tree with everything on it.

Where: the Tree viewer tab (it opened in C15). The vSNP3 page stays open in its own tab.

▶ Do this

1. Click the small dot where DEXAS_countyF joins the 3 Bisconsin samples. The bar says Clade: 4 samples.
2. Click Open SNP table for clade. A table opens in a new tab.
3. Tick Hide identical positions.

✔ You should see

hiding 53 of 57 positions. Only 4 columns are left. Each coloured box is a difference.

Read itDEXAS_countyF and each Bisconsin sample differ at only 2 or 3 places out of 4.4 million letters.

C. Run the analysis

C19 · Count the SNPs: New Rexico

Do the same for the other outbreak.

Where: the Tree viewer tab (it opened in C15). The vSNP3 page stays open in its own tab.

▶ Do this

Go back to the Tree viewer tab.

1. Click the dot where PICHIGAN_countyX (SRR33818626) joins the 2 New Rexico samples. The bar says Clade: 3 samples.
2. Click Open SNP table for clade. In the new tab, tick Hide identical positions.

✔ You should see

hiding 53 of 56 positions. Only 3 columns are left.

Read itPICHIGAN_countyX and each New Rexico sample differ at only 2 places. N means “no data here”: it is not a difference.

C. Run the analysis

C20 · The answer

You found it. Here is what vSNP3 shows.

OUTBREAK1 · Bisconsin

is closest to

Dexas · countyF

2–3 SNPs from sample SRR33914654 (2022). The next closest, Dexas countyG, is 9–10 SNPs away.

OUTBREAK2 · New Rexico

is closest to

Pichigan · countyX

2 SNPs from sample SRR33818626 (2021). Every other Pichigan sample is 11 or more SNPs away.

How close is close?For TB, samples within about 5–12 SNPs may be part of the same chain of infection. The tree and the SNP table are two views of the same answer. Always look at both.

RememberThe places and outbreaks in this exercise are made up. The method is real.

D. Finish

D1 · Check yourself

Click a question to see the answer.

D. Finish

D2 · If something goes wrong

Most problems have a simple fix.

D. Finish

D3 · Stop for today

Your project and results stay on your computer.

▶ Do this

1. Go to the dashboard tab. Click ⏻ Shut down at the bottom.
2. A box asks Shut the dashboard completely down? Click OK.

✔ You should see

Dashboard shut down. You can close the tabs and the terminal.

Your work is savedEverything is in projects/Outbreak_training in your home folder. Next time, open the dashboard (B1) and click your project.

D. Finish

D4 · More training

Keep learning.