In obrzts/BLscore: Clustering Similar TCRs Likely Recognizing Same Epitope

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

BLscore

BLscore provides functions to identify clusters of convergent TCRs that are likely to recognize the same epitope. The clustering is based on pairwise comparisons of all TCRs by aligning their CDR1-3 and calculating the alignment scores using BLOSUM62 substitution matrix reflecting evolutionary amino acid interchangeability. The three alignment scores (CDR1, CDR2 and CDR3) are logistically transformed into a single score (BL-score, BLOSUM-logistic) ranging from 0 to 1, where 1 corresponds to the highest probability of specificity match and 0 to the lowest. Because the CDRs differ in their impact on TCR specificity, they are weighted differently in the logistic function. The weights and clustering thresholds were established using available data sets of TCRs with known specificity (VDJdb and IEDB).

Installation

You can install the development version of BLscore from GitHub with:

# install.packages("devtools")
devtools::install_github("obrzts/BLscore")

If you experience troubles with R connecting to GitHub, download zipped package from the website and run:

devtools::install_local("BLscore-master.zip")

Usage

BLscore's main function is clusterize_TCR() which takes a data.frame with TCR sequence data, calculate pairwise BL-scores, uses them to define clusters of similar TCRs and returns a data.frame with cluster ids.

The input data.frame must contain the following fields:

• junction_beta - amino acid sequence of CDR3 plus the two conserved anchor residues;
• v_beta, j_beta - V and J gene with or without allele; allele information is not used for the score calculation.

If paired chain clustering is desired junction_alpha, v_alpha and j_alpha must be provided too.

Here is an example:

library(BLscore)
head(example_TCR_df)

Note, that the default thresholds for clustering were defined for full junction sequences. Providing only CDR3 sequence without anchor residues may lead to less accurate cluster assignment. If you have only CDR3 sequences you can add anchor residues with add_cdr3_anchors() function:

# make example table without anchor residues
df <- example_TCR_df
df$cdr3_beta <- substr(df$junction_beta, 2, nchar(df$junction_beta) - 2)

# generate column with beta chain junction sequence
df <- add_cdr3_anchors(df, chains="B", species="human")
head(df)

Then run clustering:

clusters = clusterize_TCR(df, chains="AB", id_col = "id", tmp_folder=".", ncores=4)
head(clusters)

Citation

Ilka Wahl, Anna Obraztsova, Julia Puchan, Rebecca Hundsdorfer, Sumana Chakravarty, B. Kim Lee Sim, Stephen L. Hoffman, Peter G. Kremsner, Benjamin Mordmüller, Hedda Wardemann, "Clonal evolution and TCR specificity of the human TFH cell response to Plasmodium falciparum CSP", Science Immunology, 2022, Vol 7, Issue 72, DOI: 10.1126/sciimmunol.abm9644

obrzts/BLscore documentation built on Nov. 21, 2024, 4:28 a.m.