immunarch
is an R package designed to analyse TCR and BCR (immunoglobulin) repertoires, which constitute a large amount of data. 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 or Telegram for news and updates.
Fast and easy manipulation of immune repertoire data:
The package automatically detects the format of your files—no more guessing what format is that file, just pass them to the package;
Supports all popular TCR and BCR analysis and post-analysis formats: ImmunoSEQ, IMGT, MiTCR, MiXCR, MiGEC, MigMap, VDJtools, tcR, AIRR, 10XGenomics, ArcherDX. More coming in the future;
Works on any data source you are comfortable with: R data frames, data tables from data.table, databases like MonetDB, Apache Spark data frames via sparklyr;
Tutorial is available here.
Immune repertoire analysis made simple:
Most methods are incorporated in a couple of main functions with clear naming—no more remembering tens and tens of functions with obscure names. For details see link;
Repertoire overlap analysis (common indices including overlap coefficient, Jaccard index and Morisita’s overlap index). Tutorial is available here;
Gene usage estimation (correlation, Jensen-Shannon Divergence, clustering). Tutorial is available here;
Diversity evaluation (ecological diversity index, Gini index, inverse Simpson index, rarefaction analysis). Tutorial is available here;
Tracking of clonotypes;
Coming in the next releases: CDR3 amino acid physical and chemical properties assessment, Kmer distribution measures and statistics, mutation networks.
Publication-ready plots with a built-in tool for visualisation manipulation:
immunarch
is an R package designed to analyse TCR and BCR (immunoglobulin) repertoires, which constitute a large amount of data. The mission of immunarch
is to make immune sequencing data analysis as effortless as possible—and help you focus on research instead of coding.
You can find the list of releases of immunarch here: https://github.com/immunomind/immunarch/releases
In order to install immunarch, you need to download it first. If you want to download the latest version, you need to download the package file, available here https://github.com/immunomind/immunarch/releases/download/latest/immunarch.tar.gz
Note that you should not un-archive it!
After downloading the file, you need to install a number of packages with R commands listed below, and run the newly installed devtools
package to install immunarch
locally. Upon completion the dependencies will have been already downloaded and installed.
install.packages("devtools", dependencies = T)
devtools::install_local("path/to/your/folder/with/immunarch.tar.gz", dependencies=T)
That’s it, you can start using immunarch
now!
If you can not install dependencies, 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", "shiny", "shinythemes", "treemap", "igraph", "airr", "ggseqlogo", "UpSetR", "stringr", "ggalluvial", "Rcpp"))
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 if your packages are outdated and update them. In RStudio you can run the “Update” button on top of the package list. In R console you can run the old.packages()
command to view a list of outdated packages.
If you are on Mac and 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.
/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 /
If you are working under Linux and have issues with igraph library or have Fortran errors, see this link
If you encounter the following error while running the devtools::install_local
function:
1: 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 directory
Check 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 you are working under Windows and have issues with the package installation, or if you want to change the folder for R packages, feel free to check this forum post.
If troubles still persist, message us on support@immunomind.io or create an issue in https://github.com/immunomind/immunarch/issues with the code that represents the issue and the output you get in the console.
Importing data into R is fairly simple. The gist of the typical TCR or BCR explorational data analysis workflow can be reduced to the next few lines of code:
# Load the package
library(immunarch)
# Load the data to the package
immdata = repLoad("path/to/your/folder/with/repertoires")
# If you folder contains metadata.txt file, immdata will have two elements:
# - immdata$data with a list of parsed repertoires
# - immdata$meta with the metadata file
# If you don't have your data, you can load repertoire data
# that comes with immunarch. Uncomment (i.e., remove the "#" symbol)
# in the next line to load the data
# data(immdata)
# Compute and visualise overlap statistics
ov = repOverlap(immdata$data)
vis(ov)
# Cluster samples using K-means algorithm applied to the number of overlapped clonotypes
# and visualise the results
ov.kmeans = repOverlapAnalysis(ov, .method = "mds")
vis(ov.kmeans)
# Compute and visualise gene usage with samples, grouped by their disease status
gu = geneUsage(immdata$data)
vis(gu, .by="Status", .meta=immdata$meta)
# Compute Jensen-Shannon divergence among gene distributions of samples,
# cluster samples using the hierarchical clustering and visualise the results
gu.clust = geneUsageAnalysis(gu, .method = "js+hclust")
vis(gu.clust)
# Compare diversity of repertoires and visualise samples, grouped by two parameters
div = repDiversity(immdata$data, .method = "chao1")
vis(div, .by=c("Status", "Lane"), .meta=immdata$meta)
# Manipulate the visualisation of diversity estimates to make the plot publication-ready
div.plot = vis(div, .by=c("Status", "Lane"), .meta=immdata$meta)
fixVis(div.plot)
If you want to test the package without parsing any data, you can load a small test dataset provided along with the package. Load the data with the following command:
ImmunoMind Team. (2019). immunarch: An R Package for Painless Analysis of Large-Scale Immune Repertoire Data. Zenodo. http://doi.org/10.5281/zenodo.3367200
BibTex:
@misc{immunomind_team_2019_3367200,
author = {{ImmunoMind Team}},
title = {{immunarch: An R Package for Painless Analysis of
Large-Scale Immune Repertoire Data}},
month = aug,
year = 2019,
doi = {10.5281/zenodo.3367200},
url = {https://doi.org/10.5281/zenodo.3367200}
}
Alternatively, you can import the XML file: immunarch-citation.xml
The package is freely distributed under the Apache v2 license. You can read more about it here.
Additionally, we provide an annual subscription that includes next services:
Contact us at support@immunomind.io for more information.