Follow CRAN Downloads_all Downloads_week Issues CI DOI Visitors Downloads_all Downloads_week

immunarch — Fast and Seamless Exploration of Single-cell and Bulk T-cell/Antibody Immune Repertoires in R

Why immunarch?

Lightning-fast Start

install.packages("immunarch")           # Install the package
library(immunarch); data(immdata)       # Load the package and the test dataset
repOverlap(immdata$data) %>% vis()      # Compute and visualise the most important statistics:
geneUsage(immdata$data[[1]]) %>% vis()  #     public clonotypes, gene usage, sample diversity
repDiversity(immdata$data) %>% vis(.by = "Status", .meta = immdata$meta)      # Group samples

From Berkeley with devotion

immunarch is brought to you by ImmunoMind — a UC Berkeley SkyDeck startup. ImmunoMind improves the design of adoptive T-cell therapies such as CAR-T by precisely identifying T-cell subpopulations and their immune profile. ImmunoMind’s tools are trusted by researchers from top pharma companies and universities, including 10X Genomics, Pfizer, Regeneron, UCSF, MIT, Stanford, John Hopkins School of Medicine and Vanderbilt University.


Table of Contents


immunarch is an R package designed to analyse T-cell receptor (TCR) and B-cell receptor (BCR) repertoires, mainly tailored to 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.


Create a ticket with a bug or question on GitHub Issues to get help from the community and enrich it with your experience. If you need to send us sensitive data, feel free to contact us via


Latest release on CRAN

In order to install immunarch execute the following command:


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 during installation, take a look at the Installation Troubleshooting section.

Note: 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 the full Data Science package ecosystem with only one command, making immunarch the entry-point for single-cell & immune repertoire Data Science.

Latest release on GitHub

If the above command doesn’t work for any reason, try installing immunarch directly from its repository:

install.packages(c("devtools", "pkgload")) # skip this if you already installed these packages

Latest pre-release on GitHub

Since releasing on CRAN is limited to one release per one or two months, you can install the latest pre-release version with all the bleeding edge and optimised features directly from the code repository. In order to install the latest pre-release version, you need to execute the following commands:

install.packages(c("devtools", "pkgload")) # skip this if you already installed these packages
devtools::install_github("immunomind/immunarch", ref="dev")

You can find the list of releases of immunarch here:

Key Features

  1. Data agnostic. Fast and easy manipulation of immune repertoire data:

  2. Beginner-friendly. Immune repertoire analysis made simple:

  3. Seamless publication-ready plots with a built-in tool for visualisation manipulation:

Quick start

The gist of the typical TCR or BCR data analysis workflow can be reduced to the next few lines of code.

Use immunarch data

1) Load the package and the data

library(immunarch)  # Load the package into R
data(immdata)  # Load the test dataset

2) Calculate and visualise basic statistics

repExplore(immdata$data, "lens") %>% vis()  # Visualise the length distribution of CDR3
repClonality(immdata$data, "homeo") %>% vis()  # Visualise the relative abundance of clonotypes

3) Explore and compare T-cell and B-cell repertoires

repOverlap(immdata$data) %>% vis()  # Build the heatmap of public clonotypes shared between repertoires
geneUsage(immdata$data[[1]]) %>% vis()  # Visualise the V-gene distribution for the first repertoire
repDiversity(immdata$data) %>% vis(.by = "Status", .meta = immdata$meta)  # Visualise the Chao1 diversity of repertoires, grouped by the patient status

Use your own data

library(immunarch)  # Load the package into R
immdata <- repLoad("path/to/your/data")  # Replace it with the path to your data. Immunarch automatically detects the file format.

Advanced methods

For advanced methods such as clonotype annotation, clonotype tracking, k-mer analysis and public repertoire analysis see “Tutorials”.

Bugs and Issues

The mission of immunarch is to make bulk and single-cell immune repertoires analysis painless. All bug reports, documentation improvements, enhancements and ideas are appreciated. Just let us know via GitHub (preferably) or (in case of private data).

Bug reports must:

  1. Include a short, self-contained R snippet reproducing the problem.
  2. Add a minimal data sample for us to reproduce the problem. In case of sensitive data you can send it to instead of GitHub issues.
  3. Explain why the current behavior is wrong/not desired and what you expect instead.
  4. If the issue is about visualisations, please attach a picture to the issue. In other case we wouldn’t be able to reproduce the bug and fix it.

Help the community

Aspiring to help the community build the ecosystem of scRNAseq & AIRR analysis tools? Found a bug? A typo? Would like to improve documentation, add a method or optimise an algorithm?

We are always open to contributions. There are two ways to contribute:

  1. Create an issue here and describe what would you like to improve or discuss.

  2. Create an issue or find one here, fork the repository and make a pull request with the bugfix or improvement.


ImmunoMind Team. (2019). immunarch: An R Package for Painless Bioinformatics Analysis of T-Cell and B-Cell Immune Repertoires. Zenodo.


  author       = {{ImmunoMind Team}},
  title        = {{immunarch: An R Package for Painless Bioinformatics Analysis 
                    of T-Cell and B-Cell Immune Repertoires}},
  month        = aug,
  year         = 2019,
  doi          = {10.5281/zenodo.3367200},
  url          = {}

For EndNote citation import the immunarch-citation.xml file.

Preprint on BioArxiv is coming soon.


The package is freely distributed under the Apache-2.0 license. You can read more about it here.

For commercial or server use, please contact ImmunoMind via about solutions for biomarker data science of single-cell immune repertoires.

Commercial Support