If you're using Windows, it's highly recommended to set up a Linux environment (such as Ubuntu) through the Windows Subsystem for Linux (WSL). This is called a virtual machine. If you don't understand, that's okay- we're going to go over it in the workshop. If you need more details, here is a virtual machine explanation: Ubuntu.
Follow these steps to get started:
Step 1: Open Command Prompt and Run WSL Installation
wsl --install
Opening the Command Prompt in Windows: press the Windows Key, type cmd, and press Enter
Follow the instructions to install the WSL virtual machine.
You may be required to restart your computer during this process.
After restarting, a terminal should appear.
Set up a username and password for your new Ubuntu environment. NOTE: you will not be able to view your password as you type. If you think you entered something wrong, just hit enter through the confirm password prompt and the screen will prompt you to enter a new password again (followed by confirmation).
Once you have installed wsl, the command prompt may change color.
If you need more details, visit the official website: Install WSL
Step 2: Install Required Software Elements
Run the following commands to set up your session:
Add a complete library repository for Ubuntu
sudo add-apt-repository universe
sudo apt update
Install the libraries we will use for the workshop
Use the following commands to install git, bzip2, bwa, samtools, and blast:
Before installing, check which version of macOS you're running. Click the Apple menu () in the top-left corner and select About This Mac. Your macOS version determines which package manager you should use.
If you are running macOS Ventura (13) or newer, we recommend Homebrew. To install Homebrew on your Mac, run the following command in your terminal:
⚠️ Troubleshooting: SSL certificate error
If the install fails with an SSL error, install Python 3 from python.org, run the certificate update script included in the installer, and retry.
Once installed, Homebrew will encourage you to "add it to your path". Look for the ==> Next steps: section at the very end of the installation text. Highlight the three lines it provides, copy them, paste them back into the command line, and hit Enter:
==> Next steps:
Run these commands in your terminal to add Homebrew to your PATH:
echo >> /Users/actual_username/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv zsh)"' >> /Users/actual_username/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv zsh)"
Step 2: Program Installation (Homebrew)
You can now install the required software using these commands:
If you are running macOS Monterey (12) or older, Homebrew is unsupported and may fail. If it does, we recommend using MacPorts instead.
1. Install Xcode Command Line Tools
MacPorts requires Apple's command line tools to compile software. Run this in your terminal:
xcode-select --install
A pop-up window will appear asking to install the tools. Click "Install" and wait for it to finish.
2. Install MacPorts
Go to the MacPorts Installation Page and download the .pkg installer that matches your specific macOS version (e.g., Monterey, Big Sur, Catalina). Run the installer and follow the prompts.
After installing, completely close your terminal window and open a new one so your system recognizes the port command.
3. Update MacPorts
Run the following command to ensure MacPorts has the latest software lists (you will be prompted for your Mac's login password):
sudo port selfupdate
Step 2: Program Installation (MacPorts)
You can now install the required software. Because MacPorts installs system-level software, you must use sudo (which requires your password) for these commands:
sudo port install samtools
sudo port install bwa
Using Macports, the version of BLAST that installs is too old. We recommend installing it manually. To manually install BLAST, download the latest disk image (dmg) from the following link: NCBI BLAST+ Download. You may need to allow your device to open the folder, but once the installer is opened, follow the prompts.
Step 3: Test Your Installation!
Before we begin the workshop, it is highly recommended that you verify your programs installed correctly. You can do this by asking your terminal to print the help menu for each program.
Run the following three commands one at a time in your terminal:
blastn -help
samtools
bwa
What to expect:
For blastn -help, you should see a long list of USAGE instructions and optional arguments.
For samtools, you should see the Program Version (e.g., Version: 1.21) followed by a list of Commands like Indexing, Editing, and File operations.
For bwa, you should see the Program Version (e.g., Version: 0.7.18) followed by a list of Commands like index, mem, and aln.
You are all set. We will begin the Worked Example in the field starting on the Workflow page.
Description: These are the programs everyone will need to complete the example that workshop participants will walk through.
Program Information
Samtools
Description: Samtools is a suite of programs for interacting with high-throughput sequencing data. It is used for extracting unaligned reads and converting BAM files to FASTA.
Description: BLAST+ is a suite of tools to perform similarity searches against nucleotide and protein databases. It is widely used in bioinformatics for comparing sequence similarity.
Description: BWA (Burrows-Wheeler Aligner) is a software package for mapping low-divergent sequences against a large reference genome. It is commonly used in genome assembly and variant calling.
Description: These are the programs you may need if you wish to replicate the analysis performed in the field on the data we generate with the Nanopore run. The participants do not need Dorado for the Worked Example they will be performing on their computers.
First, you may need wget on Homebrew (for Macs). If wget is unavailable or fails to install, you can use curl -OL in place of wget in the commands below.
# Install wget (generic)
brew install wget
Dorado
Description: Dorado is a basecalling and alignment tool used for processing Oxford Nanopore sequencing data.
⚠️ Important note on downloading: Some systems may have trouble with the wget command. If wget [URL] fails to download the file, you can substitute it with curl -OL [URL] instead.
⚠️ Important note on versions: Make sure you are downloading the correct file for your operating system and processor architecture. Linux and Windows (WSL) use the linux-x64.tar.gz version. For Macs, newer Apple Silicon (M1/M2/M3) models use osx-arm64.zip, while older Intel Macs use osx-x64.tar.gz. (The commands below show the Apple Silicon version for Macs).
# For Linux (generic) & Windows (using WSL)
wget https://cdn.oxfordnanoportal.com/software/analysis/dorado-1.4.0-linux-x64.tar.gz
tar -xvzf dorado-1.4.0-linux-x64.tar.gz
cd dorado-1.4.0-linux-x64/bin/
export PATH=$PATH:$PWD