Installing programs and packages

Part 1 of the bulk RNA-Seq workflow

Every program, package and library the RNA-Seq workflow depends on, installed in one sitting.

The first time you perform RNA-Seq you need to install a slew of programs, packages and files. This page collects all of it in one place — every BiocManager::install() call in one block, rather than hunting them down one at a time — so you can prepare your workspace in a single sitting and then not think about it again.

ImportantTwo things that will save you an afternoon

No spaces in your username or file paths. Spaces in a PATH cause errors in several of the tools below, and the error messages rarely say so. If your account name contains a space, create a new user account before you start.

Install everything before you begin the analysis. Stopping midway through a pipeline to install a missing package is how mistakes get made.

This page covers:

  1. Setting up Linux/Unix on Mac or Windows
  2. Installing conda and Python
  3. Setting up bioconda
  4. Installing R and RStudio
  5. Installing FastQC
  6. Installing Trim Galore
  7. Installing kallisto
  8. Installing every required R package, including tximport and DESeq2

0. Set up your shell

macOS — you are already on a Unix system. Open a terminal with Command + Space, type Terminal, and press Enter.

Windows — you need WSL (Windows Subsystem for Linux) with a Linux distribution; Ubuntu is the easiest choice. On Windows 10 and later:

  1. Click the Windows icon and search for PowerShell
  2. Right-click it and choose Run as Administrator
  3. Run:
wsl --install
  1. Follow the prompts, restart when asked, then set a username and password for your Linux environment

From then on, typing bash or wsl at the command line drops you into Linux.

The Ubuntu install can take 45 minutes to an hour. Start it and go do something else.

A handful of bash commands worth knowing

Command What it does
pwd print the working directory
ls list files and folders in the current directory
cd path/to/folder change directory
cd .. go up one directory
cd ~ go to your home directory
./ shorthand for the current directory
head filename show the first lines of a file
nano filename open a file in the nano text editor

1. Install conda

conda manages both Python and the bioinformatics tools this workflow uses, and keeps each project’s dependencies separate from every other project’s.

TipWhich conda to install

Miniforge is the recommendation for academic work. It is a minimal conda installer that defaults to the conda-forge channel, it installs quickly, and — unlike the full Anaconda Distribution — its default channels carry no commercial-use licensing conditions. Anaconda’s terms have changed more than once, and larger institutions have been caught out by them.

Anaconda still works and bundles Jupyter and the Spyder IDE, which some people prefer. If you install it, check your institution’s licensing position first.

Windows users: install the Linux version of conda, from inside WSL — not the Windows installer. The tools below are Linux binaries and need a Linux conda.

Confirm Python arrived with it:

python --version

2. Set up bioconda

Open your Linux shell (Windows: type wsl), then configure the channels. Run these in order — --add prepends, so this leaves conda-forge at the top of the priority list, which is what bioconda expects:

conda config --add channels defaults
conda config --add channels bioconda
conda config --add channels conda-forge
conda config --set channel_priority strict

Then update everything:

conda update --all

The official instructions live on the bioconda site if you need them.

3. Install R and RStudio

Install R first, from CRAN, then RStudio Desktop.

Bioconductor pairs each of its releases with a specific version of R, so install a current R before you install the Bioconductor packages in step 7. If your R is more than a couple of years old, update it now rather than debugging version conflicts later.

On Windows, if packages refuse to install into the right library, right-click the RStudio icon and choose Run as administrator.

To update R on Windows from inside R:

install.packages("installr")
library(installr)
updateR()

On macOS, download the current installer from CRAN and reopen RStudio.

4. Install Java, then FastQC

FastQC needs Java. Check whether you have it:

java -version

If not, install Java, then check again.

The simplest way to get FastQC is through conda, in the environment you will work in:

conda create --name RNA
conda activate RNA
conda install -c bioconda fastqc

You can also download FastQC directly and run it as a desktop application, which gives you a graphical interface — double-click run_fastqc.bat on Windows, or the FastQC application icon on macOS.

NoteStay inside your conda environment

Once you have run conda activate RNA, install tools with conda install, not with sudo apt install. apt installs system-wide, outside the environment, and mixing the two is how you end up with two versions of the same tool and no idea which one is running.

conda env list shows your environments; the * marks the active one.

5. Install Trim Galore

Trim Galore depends on cutadapt, and optionally on FastQC so it can generate a report after trimming. Install all three at once:

conda install -c bioconda cutadapt fastqc trim-galore

Note the package name is trim-galore, with a hyphen.

Check they installed:

cutadapt --version
fastqc -v
trim_galore --version

If conda cannot find trim-galore, confirm your channels are configured as in step 2, then run conda update --all and try again. As a last resort you can install it from the release tarball:

curl -fsSL https://github.com/FelixKrueger/TrimGalore/archive/refs/tags/0.6.10.tar.gz -o trim_galore.tar.gz
tar xvzf trim_galore.tar.gz

Check the Trim Galore releases page for the current version number before you copy that command.

6. Install kallisto

conda install -c bioconda kallisto
kallisto

Running kallisto with no arguments prints its version and command list, which confirms the install.

7. Install the R packages

That completes the command-line side. The rest happens in R.

Open RStudio and run:

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

# CRAN packages
install.packages(c("devtools", "tidyverse"))

# Bioconductor packages
BiocManager::install(c(
  "tximport",
  "rhdf5",
  "GenomicFeatures",
  "DESeq2",
  "AnnotationDbi",
  "apeglm",
  "org.Mm.eg.db"    # mouse; use org.Hs.eg.db for human
))

Check that everything loads before you rely on it:

lapply(c("tximport", "rhdf5", "GenomicFeatures", "DESeq2",
         "AnnotationDbi", "org.Mm.eg.db"),
       require, character.only = TRUE)

Any FALSE in the output is a package that did not install. Read the error it printed earlier — it is almost always a missing system library, and the message names it.

8. Record your environment

Two commands, run now, that make your analysis reproducible later:

conda env export --name RNA > environment.yml
writeLines(capture.output(sessionInfo()), "sessionInfo.txt")

Commit both files alongside your analysis. When someone cannot reproduce your results — or when you cannot, two years later — these are what settle it.

If a package you needed is missing from this page, email aaron.mitchell.dick@duke.edu and it will be added.

You are now ready to run part 2 and part 3.