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:

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

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!

Installation troubleshooting

If you run in any trouble, try the following steps:

  1. Check your R version. Run version command in the console to get your R versions. If the R version is below 3.4.0 (for example, R version 3.1.0), try updating your R version to the latest one.

  2. 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.

  3. 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.

  4. If you are working under Linux and have issues with library or have Fortran errors, see this link

  5. If troubles still persist, message us on or create an issue in with the code that represents the issue and the output you get in the console.

Quick start

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 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

# Compute and visualise overlap statistics
ov = repOverlap(immdata$data)

# Cluster samples using K-means algorithm applied to the number of overlapped clonotypes
# and visualise the results
ov.kmeans = repOverlapAnalysis(ov, .method = "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")

# Compare diversity of repertoires and visualise samples, grouped by two parameters
div = repDiversity(immdata$data, .method = "chao1")
vis(div, .by=c("Status", "Treatment"), .meta=immdata$meta)

# Manipulate the visualisation of diversity estimates to make the plot publication-ready
div.plot = vis(div, .by=c("Status", "Treatment"), .meta=immdata$meta)

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:



List of tutorials available here.