Installation Guide

Source: vignettes/installation.Rmd

This guide covers installing MPAQT and all its dependencies. MPAQT has both R package dependencies and external system tools that must be installed separately.

Prerequisites

R Installation:

Install R (>= 4.0.0) from CRAN with compilation tools (make, zlib, curl).

pak is a modern R package manager that handles dependencies efficiently and supports installing from GitHub.

# Install pak if not already installed
install.packages("pak")

# Install MPAQT from GitHub
pak::pak("csglab/MPAQT")

The source repository is public. GitHub credentials are optional for installation and can help avoid API rate limits.

pak will automatically:

  • Resolve and install required dependencies from configured repositories
  • Report dependency and version conflicts

Alternative: devtools Installation

If you prefer using devtools:

# Install devtools if needed
install.packages("devtools")

# Install MPAQT from GitHub
devtools::install_github("csglab/MPAQT")

The source repository is public. GitHub credentials are optional for installation and can help avoid API rate limits.

Installing from Local Source

If you have the package source code locally:

# Using pak
pak::pak("local::/path/to/mpaqt")

# Or using devtools
devtools::install_local("/path/to/mpaqt")

R Package Dependencies

Required Packages (Automatically Installed)

These packages are installed automatically when you install MPAQT:

Package Purpose
data.table Fast data manipulation
Matrix Sparse matrix operations
lme4 Mixed-effects models
gpboost Gradient boosting with random effects
cli Terminal output formatting
rlang Error handling and metaprogramming
stringr String manipulation
purrr Functional programming

Optional Bioconductor Packages

These packages are needed for specific features:

For All Index Creation

Every mpaqt_index() pathway requires Biostrings for transcript sequences and rtracklayer for GTF annotation parsing:

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

BiocManager::install(c(
    "Biostrings",
    "rtracklayer"
))

Additional Packages for Transcriptome Extraction from a Genome

If you want to extract the transcriptome from a BSgenome object or package instead of supplying a transcriptome FASTA, also install:

BiocManager::install(c(
    "GenomicRanges",
    "BSgenome"
))

Install the matching organism-specific BSgenome package separately, for example BSgenome.Hsapiens.UCSC.hg38.

For Long-Read Processing (FLNC Pathway)

If you want to process raw FLNC FASTQ files through the minimap2/Bambu pipeline:

BiocManager::install(c(
    "bambu",
    "BiocFileCache",
    "SummarizedExperiment"
))

Note: If you’re using pre-computed Bambu counts (CSV files), you don’t need these packages.

System Tool Dependencies

MPAQT uses external bioinformatics tools for read processing.

Required Tools

These are required for short-read processing:

Tool Version Purpose
kallisto >= 0.50.1 Short-read pseudoalignment
bustools >= 0.43.1 BUS file processing

Optional Tools

These are only needed for specific long-read workflows:

Tool Purpose When Needed
minimap2 Long-read alignment FLNC FASTQ processing
samtools BAM file handling With minimap2

The easiest way to install system tools is using conda:

# Create a new environment (optional but recommended)
conda create -n mpaqt -c conda-forge -c bioconda python=3.10

# Activate the environment
conda activate mpaqt

# Install required tools
conda install -c conda-forge -c bioconda kallisto bustools

# Install optional tools (for long-read processing)
conda install -c conda-forge -c bioconda minimap2 samtools

Installing via Mamba (Faster)

If you have mamba installed:

mamba install -c conda-forge -c bioconda kallisto bustools minimap2 samtools

Manual Installation

If you prefer not to use conda:

kallisto: Download from pachterlab/kallisto

bustools: Download from BUStools/bustools

minimap2: Download from lh3/minimap2

samtools: Download from samtools/samtools

Ensure all tools are available in your PATH.

Pre-built Containers and Packages

Instead of installing manually, you can use a verified pre-built container or Conda package. Each artifact includes the dependencies for its stated variant.

The published artifacts listed below contain MPAQT 2.4.0.

Verified Published Variants

Variant Verified distribution Description Use When
stable Apptainer 2.4.0, Conda r-mpaqt 2.4.0 Core indexing dependencies (Biostrings, rtracklayer, kallisto, bustools) Standard short-read workflows
full Apptainer 2.4.0-full, Conda r-mpaqt-full 2.4.0 Includes minimap2, samtools, and Bioconductor packages Long-read FLNC processing and transcriptome extraction
dev Apptainer 2.4.0-dev, Conda r-mpaqt-dev 2.4.0 Includes development and documentation tools Development and testing

Only commands for artifacts whose current publication was verified are shown below.

Apptainer (for HPC)

First, configure the Sylabs Cloud remote (one-time setup):

# Add the Sylabs Cloud remote
apptainer remote add --no-login SylabsCloud cloud.sylabs.io

# Set it as default
apptainer remote use SylabsCloud

Then pull the image:

# Stable
apptainer pull mpaqt_2.4.0.sif \
  library://csglab/mpaqt/mpaqt:2.4.0
apptainer exec mpaqt_2.4.0.sif Rscript analysis.R

# Full
apptainer pull mpaqt_2.4.0-full.sif \
  library://csglab/mpaqt/mpaqt:2.4.0-full
apptainer exec mpaqt_2.4.0-full.sif Rscript analysis.R

# Development
apptainer pull mpaqt_2.4.0-dev.sif \
  library://csglab/mpaqt/mpaqt:2.4.0-dev

Conda 

# Stable
conda create -n mpaqt \
  -c csglab -c conda-forge -c bioconda -c defaults \
  r-mpaqt
conda activate mpaqt

The stable Conda package includes Biostrings, rtracklayer, kallisto, and bustools, which are required to create an index with mpaqt_index(). The defaults channel supplies the r-gpboost dependency.

For the full or development variants, replace r-mpaqt with r-mpaqt-full or r-mpaqt-dev, respectively.

Which Variant Should I Use?

  • stable: You only need short-read quantification, or you’re providing pre-computed long-read counts
  • full: You process raw FLNC FASTQ files or extract a transcriptome from a BSgenome reference
  • dev: You need development, testing, and documentation tools

Verifying Installation

Check R Package 

# Load the package
library(mpaqt)

# Check version
packageVersion("mpaqt")

Check System Tools

From R:

# Locate required and optional executables
Sys.which(c("kallisto", "bustools", "minimap2", "samtools"))

An empty path means that the executable is not available on PATH. Use the commands below to inspect installed versions.

From the command line:

kallisto version
bustools version
minimap2 --version
samtools --version

Test Basic Functionality 

# This should work if all required dependencies are installed
library(mpaqt)

# Check that key functions are available
?mpaqt_index
?mpaqt_quant

Troubleshooting

“Package ‘X’ is not available”

If pak/devtools fails to find a package, try installing it separately:

# For CRAN packages
install.packages("package_name")

# For Bioconductor packages
BiocManager::install("package_name")

“kallisto not found” / “bustools not found”

Ensure the tools are installed and in your PATH:

# Check if tools are found
which kallisto
which bustools

# If using conda, ensure environment is activated
conda activate mpaqt

Bioconductor Version Conflicts

If you encounter version conflicts with Bioconductor packages:

# Install or update packages for the Bioconductor release compatible with R
BiocManager::install()

# Then reinstall MPAQT
pak::pak("csglab/MPAQT")

The source repository is public. GitHub credentials are optional for installation and can help avoid API rate limits.

gpboost Installation Issues

gpboost can sometimes be tricky to install. If you encounter issues:

# Try installing from CRAN first
install.packages("gpboost")

# If that fails, you might need system dependencies
# On Ubuntu/Debian:
# sudo apt-get install cmake libboost-all-dev

# On macOS with Homebrew:
# brew install cmake boost

Memory Issues During Installation

If installation runs out of memory:

# Reduce parallel installation jobs to lower memory use
options(Ncpus = 1)

# Or install packages one at a time
install.packages("data.table")
install.packages("Matrix")
# etc.

Summary: What You Need

Minimal Setup (Short-Read Only) 

# R packages
install.packages("pak")
pak::pak("csglab/MPAQT")

The source repository is public. GitHub credentials are optional for installation and can help avoid API rate limits.

Install kallisto (>= 0.50.1) and bustools (>= 0.43.1).

Full Setup (With Long-Read Processing) 

# R packages
pak::pak("csglab/MPAQT")
BiocManager::install(c("Biostrings", "rtracklayer", "bambu", "BSgenome"))

The source repository is public. GitHub credentials are optional for installation and can help avoid API rate limits.

Also install minimap2 and samtools.

Verification Checklist

Run this complete checklist to verify your MPAQT installation:

# 1. Load MPAQT and check version
library(mpaqt)
cat("MPAQT version:", as.character(packageVersion("mpaqt")), "\n")

# 2. Check required and optional system tools
tools <- c("kallisto", "bustools", "minimap2", "samtools")
tool_paths <- Sys.which(tools)
print(data.frame(
  tool = tools,
  available = nzchar(tool_paths),
  path = unname(tool_paths),
  row.names = NULL
))

# 3. Check optional Bioconductor packages
cat("\nOptional packages:\n")
cat("Biostrings:", requireNamespace("Biostrings", quietly = TRUE), "\n")
cat("rtracklayer:", requireNamespace("rtracklayer", quietly = TRUE), "\n")
cat("bambu:", requireNamespace("bambu", quietly = TRUE), "\n")

Illustrative output for a source installation with only required tools:

MPAQT version: 2.4.0

     tool available               path
 kallisto      TRUE /path/to/kallisto
 bustools      TRUE /path/to/bustools
 minimap2     FALSE
 samtools     FALSE

Optional packages:
Biostrings: FALSE
rtracklayer: FALSE
bambu: FALSE

Next Steps

After installation: