tcrGraph - Graph-based Analysis of T Cell Receptors

A package to facilitate building and analyzing networks of T cell receptors to help better understand clonality, antigen specificity, and other immunological questions.

NOTE: The clone calling method implemented in getClonesFromTcrGraph was extensively updated in December 2025, to be more in line with standard definitions of clonally expanded T cell populations. Specifically, clones can no longer contain cells with TCR chains that are not part of the clone, and the default limit on beta chains in a clone was reduced to 1 (from 2).

Installation

Open an R session, and execute the following code:

if (!require("devtools")) install.packages("devtools")
devtools::install_github("BenaroyaResearch/tcrGraph", build_vignettes = TRUE)

Requirements

The following R packages will be automatically installed if necessary: stringr, dplyr, magrittr, rlang, igraph, httr

Vignettes

This package includes an introductory vignette demonstrating basic use of the package functions. To view this vignette, execute the following R code:

vignette("tcrGraphIntro", "tcrGraph")

Supported Functions and Classes

• tcrGraph

  • An S3 class, with implementations of methods print, plot, and is.tcrGraph. Generally you should create a tcrGraph object using the function makeTcrGraph().

• makeTcrGraph(tcrDf, link = "full_nt_sequence")

  • Accepts a data frame of TCR information, with columns for libid, v_gene, j_gene, and the column indicated by the link argument. Returns a tcrGraph object.

• getClonesFromTcrGraph(tcrData, maxA = 2, maxB = 2, maxD = -1, maxG = -1, format = "compressed", link = "full_nt_sequence")

  • Accepts either a tcrGraph object or a data frame that can be used to construct a tcrGraph object. Generates summary information about the frequencies of the clones in the dataset. A 'clone' is defined as a maximal subgraph containing at most the number of alpha, beta, delta, and gamma chains set by maxA, maxB, maxD, and maxG.