immunarch is an R package designed to analyse T-cell receptor (TCR) and B-cell receptor (BCR) repertoires, aimed at medical scientists and bioinformaticians. The mission of immunarch is to make immune sequencing data analysis as effortless as possible and help you focus on research instead of coding. Follow us on Twitter for news and updates.
In order to install immunarch execute the following R command:
install.packages("devtools") # skip this if you already installed devtools
devtools::install_url("https://github.com/immunomind/immunarch/raw/master/immunarch.tar.gz")That’s it, you can start using immunarch now! See the Quick Start section below to dive into immune repertoire data analysis. If you run in any trouble with installation, take a look at the Installation Troubleshooting section below.
Note that there are quite a lot of dependencies to install with the package because it installs all the widely-used packages for data analysis and visualisation. You got both the AIRR data analysis framework and Data Science package eco-system with only one command!
You can find the list of releases of immunarch here: https://github.com/immunomind/immunarch/releases
The gist of the typical TCR or BCR data analysis workflow can be reduced to the next few lines of code.
1) Load the package and the data
# 1.1) Load the package into R:
library(immunarch)
# 1.2a) To quickly test immunarch, load the test dataset:
data(immdata)
# 1.2b) To try immunarch on your own data, use the `repLoad` function on your data folder:
immdata = repLoad("path/to/your/folder/with/repertoires")2) Analyse repertoire similarity at the clonotype level
# 2.1) Find the number of shared clonotypes and visualise it:
ov = repOverlap(immdata$data)
vis(ov)
# 2.2) Cluster samples by their similarity:
ov.kmeans = repOverlapAnalysis(ov, .method = "mds+kmeans")
vis(ov.kmeans)3) Find repertoire differences in the Variable gene usage
# 3.1) Compute V gene usage and and highlight gene differences in groups with different clinical status:
gu = geneUsage(immdata$data)
vis(gu, .by="Status", .meta=immdata$meta)
# 3.2) Cluster samples by their V gene usage similarity:
gu.clust = geneUsageAnalysis(gu, .method = "js+hclust")
vis(gu.clust)4) Find differences in the diversity of repertoires
# 4.1) Compare diversity of repertoires and visualise samples, grouped by both clinical status and sequencing Lane:
div = repDiversity(immdata$data, .method = "chao1")
vis(div, .by=c("Status", "Lane"), .meta=immdata$meta)5) Manipulate plots to make them publication-ready
# 5.1) Manipulate the visualisation of diversity estimates to make the plot publication-ready:
div = repDiversity(immdata$data, .method = "chao1")
div.plot = vis(div, .by=c("Status", "Lane"), .meta=immdata$meta)
fixVis(div.plot)6) Advanced methods
For advanced methods such as clonotype tracking, kmer analysis and public repertoire analysis see tutorials on the immunarch website.
If you can not install devtools, check sections 1 and 2 below.
If you run in any other trouble, try the following steps:
Check your R version. Run version command in the console to get your R versions. If the R version is below 3.5.0 (for example, R version 3.1.0), try updating your R version to the latest one. Check this this link if you are on Ubuntu. Note: if you try to install a package after the update and it still fails with the following message:
ERROR: dependencies ‘httr’, ‘usethis’ are not available for package ‘devtools’
* removing ‘/home/ga/R/x86_64-pc-linux-gnu-library/3.5/devtools’
Warning in install.packages :
installation of package ‘devtools’ had non-zero exit statusit means that you need to re-install packages that were built under the previous R version. In the above example it would be packages httr and usethis. In order to re-install a package you need to execute the command install.packages("package_name"), where package_name is the name of the package to update. To find packages that need to be re-installed after updating R, you need to look for installation messages like this in the installation process:
ERROR: package ‘usethis’ was installed by an R version with different internals; it needs to be reinstalled for use with this R versionCheck if your packages are outdated and update them. In RStudio you can run the “Update” button on top of the package list in the “Package” window. In R console you can run the old.packages() command to view a list of outdated packages. The following messages indicate that an update is required:
Error: package ‘dtplyr’ 0.0.3 was found, but >= 1.0.0 is required by ‘immunarch’
Execution halted
ERROR: lazy loading failed for package ‘immunarch’byte-compile and prepare package for lazy loading
Error in loadNamespace(j <- i[[1L]], c(lib.loc, .libPaths()), versionCheck = vI[[j]]) :
namespace 'ggalluvial' 0.9.1 is being loaded, but >= 0.10.0 is required
Calls: <Anonymous> ... namespaceImportFrom -> asNamespace -> loadNamespace
Execution haltedFor Mac users. Make sure to install XCode from App Store first and command line developers tools second by executing the following command in Terminal: xcode-select –install
For Mac users. If you have issues like old packages can’t be updated, or error messages such as ld: warning: directory not found for option or ld: library not found for -lgfortran, this link will help you to fix the issue.
For Mac Mojave (1.14) users. If you run into the following error:
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include/c++/v1/math.h:301:15: fatal error: 'math.h' file not found
#include_next <math.h>
^~~~~~~~Open Terminal, execute the following command and try again to install immunarch:
sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /For Linux users. If you have issues with the igraph library or have Fortran errors such as:
** testing if installed package can be loaded from temporary location
Error: package or namespace load failed for 'igraph' in dyn.load(file, DLLpath = DLLpath, ...):
unable to load shared object '/usr/local/lib/R/site-library/00LOCK-igraph/00new/igraph/libs/igraph.so':
libgfortran.so.4: cannot open shared object file: No such file or directorySee this link for help.
For Linux users. If you have issues with the rgl package:
configure: error: missing required header GL/gl.h
ERROR: configuration failed for package ‘rgl’Install “mesa-common-dev” via OS terminal by executing the following command:
apt-get install mesa-common-devCheck this link for more information and other possible workarounds.
If you have error messages with rlang in them such as:
Error: .onLoad failed in loadNamespace() for 'vctrs', details:
call: env_bind_impl(.env, list3(...), "env_bind()", bind = TRUE)
error: object 'rlang_env_bind_list' not foundRemove the rlang package and install it again. This error is often happens after updating R to a newer version, while rlang not being properly updated.
If you have error messages like the following (note the (converted from warning) part):
** byte-compile and prepare package for lazy loading
Error: (converted from warning) package 'ggplot2' was built under R version 3.6.1
Execution halted
ERROR: lazy loading failed for package 'immunarch'Execute the following command in R and try again to install the package:
Sys.setenv(R_REMOTES_NO_ERRORS_FROM_WARNINGS="true")For Windows users. If you have issues with the package installation, or if you want to change the folder for R packages, feel free to check this forum post.
For Windows users. Make sure to install Rtools. Before installation close RStudio, install Rtools and re-open it afterwards. To check if Rtools installed correctly, run the devtools::find_rtools() command (after installing the devtools package). If you have an error, check this link for help.
If you can not install dependencies for immunarch, please try manual installation of all dependencies by executing the following command in R console:
install.packages(c("rematch", "prettyunits", "forcats", "cellranger", "progress", "zip", "backports", "ellipsis", "zeallot", "SparseM", "MatrixModels", "sp", "haven", "curl", "readxl", "openxlsx", "minqa", "nloptr", "RcppEigen", "utf8", "vctrs", "carData", "pbkrtest", "quantreg", "maptools", "rio", "lme4", "labeling", "munsell", "cli", "fansi", "pillar", "viridis", "car", "ellipse", "flashClust", "leaps", "scatterplot3d", "modeltools", "DEoptimR", "digest", "gtable", "lazyeval", "rlang", "scales", "tibble", "viridisLite", "withr", "assertthat", "glue", "magrittr", "pkgconfig", "R6", "tidyselect", "BH", "plogr", "purrr", "ggsci", "cowplot", "ggsignif", "polynom", "fastcluster", "plyr", "abind", "dendextend", "FactoMineR", "mclust", "flexmix", "prabclus", "diptest", "robustbase", "kernlab", "GlobalOptions", "shape", "colorspace", "stringi", "hms", "clipr", "crayon", "httpuv", "mime", "jsonlite", "xtable", "htmltools", "sourcetools", "later", "promises", "gridBase", "RColorBrewer", "yaml", "ggplot2", "dplyr", "dtplyr", "dbplyr", "data.table", "gridExtra", "ggpubr", "heatmap3", "ggrepel", "reshape2", "DBI", "factoextra", "fpc", "circlize", "tidyr", "Rtsne", "readr", "readxl", "shiny", "shinythemes", "treemap", "igraph", "airr", "ggseqlogo", "UpSetR", "stringr", "ggalluvial", "Rcpp"))If you can not install immunarch using install_url(), try the manual installation. First, you need to download the package file from our GitHub.
Note that you should not un-archive it!
After downloading the file, you need to run R command from the devtools package to install immunarch. Upon completion the dependencies will have been already downloaded and installed. Run the following command:
devtools::install_local("path/to/your/folder/with/immunarch.tar.gz", dependencies=T)If you encounter the following error while running the devtools::install_local function:
In normalizePath(path.expand(path), winslash, mustWork) :
path[1]="path/to/your/folder/with/immunarch.tar.gz":
In file.copy(x$path, bundle, recursive = TRUE) :
problem copying No such file or directoryCheck your path to the downloaded package archive file. It should not be “path/to/your/folder/with/immunarch.tar.gz”, but a path on your PC to the downloaded file, e.g., “C:/Users/UserName/Downloads/immunarch.tar.gz” or “/Users/UserName/Downloads/immunarch.tar.gz”.
If troubles still persist, message us on support@immunomind.io or create an issue in our GitHub with the code that represents the issue and the output you get in the console.