An R package for T cell receptor and Immunoglobulin repertoires advanced data analysis

T cell receptor, Immunoglobulin, TCR repertoire, Ig repertoire, TCR analysis, Ig analysis, immunoinformatics, computational immunology

Paper in BMC Bioinformatics

tcR at CRAN Package info at CRAN

Immunoinformatics Page Our other projects and tools.


tcR is a platform designed for TCR repertoire data analysis in R after preprocessing data with CDR3 extraction and gene alignment software tools such as MiTCR, ImmunoSEQ and MiGEC. With the power and flexibility of R language and procedures supported by tcR users can perform advanced statistical analysis of TCR repertoires. Features of the package:

Manual: tcR package vignette


The package is available through CRAN and through devtools::install_github.

CRAN version:

Stable development version (the `master` branch):

Unstable development version (the `develop` branch):

Install the latest release version from CRAN with:


Install the latest stable development version (strongly recommended) with:

# install.packages("devtools")
devtools::install_github("imminfo/tcr", build_vignettes = FALSE)

Note: Windows users need to install Rtools in order to build packages.

Install the latest unstable development version (only for contributors and advanced users) with:

# install.packages("devtools")
devtools::install_github("imminfo/tcr", build_vignettes = FALSE, ref = "develop")

Quick Start

The package provides two RMarkdown documents with exploratory analysis of a single or a groups of repertoires and crossanalysis of a group of repertoires.. User just need to change paths in this documents to their MiTCR data and have the knitr package installed.

Exploratory analysis (example for two repertoires) stored at "tcR-package-path/inst/" and included statistics and visualisation of number of clones, clonotypes, in- and out-of-frames, unique amino acid CDR3 sequences, V- and J-usage, most frequent k-mers, rarefaction analysis.

Analysis of a group of repertoires (example for four repertoires) stored at "tcR-package-path/inst/" and included statistics and visualisation of number of shared clones and clonotypes, V-usage for individuals and groups, J-usage for individuals, Jensen-Shannon divergence among V-usages of repertoires and top-cross.


First, load the list with cloneset data frames with TCR beta chain data of 2 twin pairs:


Get numbers of clonotypes, in-frame and out-of-frame sequences, unique amino acid CDR3 sequences and other basic statistics:


Compute V beta usage of the first human subject:

geneUsage(twb[[1]], HUMAN_TRBV)

Compute V usage of all subjects and visualise it using a histogram:

vis.gene.usage(twb, HUMAN_TRBV, .dodge = T)

Compute joint V-J beta usage of the second human subject:

geneUsage(twb[[2]], list(HUMAN_TRBV, HUMAN_TRBJ))

Compute a pairwise normalised number of shared clonotypes and plot a heatmap of them: <- repOverlap(twb, "exact")

Estimate the diversity of each sample using Chao1 and Gini-Simpson indices:

twb.chao1 <- repDiversity(twb, "chao1") <- repDiversity(twb, "gini.simp")

Perform a rarefaction analysis and plot the resulting rarefaction curve on a log x-axis:

twb.rar <- rarefaction(twb, .col = "Read.count")
vis.rarefaction(twb, .log = T)

For more examples see the vignette


Authors and Contributors

The package was developed by members of Laboratory of Functional and Comparative Genomics, Moscow, Russia and Laboratory of Genomics of Adaptive Immunity, Moscow, Russia. Main developer is Vadim Nazarov @vadimnazarov. Contributors: Marina Orlova @Marge-m.


For any question contact @vadimnazarov or raise an issue at Issues.