Skip to contents

Compute pairwise TCRdist distance matrix

Source: R/wrappers_distance.R
tcrdist_matrix.Rd

Computes the full N x N symmetric matrix of paired-chain TCRdist distances for a collection of TCRs. Each off-diagonal entry [i, j] equals the sum of V-alpha, CDR3-alpha, V-beta, and CDR3-beta component distances between TCR i and TCR j. Computation is dispatched to a C++ implementation for performance.

Usage

tcrdist_matrix(
  tcrs,
  organism,
  components = "all",
  weight_cdr3 = WEIGHT_CDR3_REGION,
  gap_penalty_cdr3 = GAP_PENALTY_CDR3_REGION
)

Arguments

tcrs

A data.frame with columns for one or both TCR chains. For paired alpha-beta input, requires va, cdr3a, vb, cdr3b. For single-chain input, only the columns for one chain are needed (e.g., vb and cdr3b for beta-only). The missing chain is filled with dummy values internally, and components is automatically set to "alpha" or "beta".

organism

Character string. Organism key understood by load_gene_database, e.g. "human" or "mouse".

components

Character. Which distance components to include. Presets: "all" (default), "cdr3" (CDR3 only), "v_region" (CDR1+CDR2+CDR2.5 only), "alpha" (alpha chain), "beta" (beta chain). Or a character vector of individual terms: "va", "cdr3a", "vb", "cdr3b". For single-chain input, defaults to the present chain.

weight_cdr3

Integer. Weight applied to CDR3 distances. Defaults to WEIGHT_CDR3_REGION (3L).

gap_penalty_cdr3

Integer. Gap penalty for CDR3 alignments. Defaults to GAP_PENALTY_CDR3_REGION (12L).

Value

A symmetric numeric matrix of dimensions N x N where N is nrow(tcrs). Row and column names are the row indices of tcrs as character strings.

Details

The diagonal is zero (distance of a TCR to itself). The matrix is symmetric by construction.

See also

tcrdist_sparse, tcrdist_rect, tcrdist_knn, TCRrep

Examples

# \donttest{
tcrs <- data.frame(
  va    = c("TRAV1-1*01", "TRAV1-1*01"),
  cdr3a = c("CAVRDSSYKLIF", "CAVRDSSYKLIF"),
  vb    = c("TRBV19*01", "TRBV19*01"),
  cdr3b = c("CASSIRSSYEQYF", "CASSIRSYEQYF"),
  stringsAsFactors = FALSE
)
mat <- tcrdist_matrix(tcrs, "human")

# CDR3-only distance
mat_cdr3 <- tcrdist_matrix(tcrs, "human", components = "cdr3")

# Beta-only (single-chain) input
beta_only <- tcrs[, c("vb", "cdr3b")]
mat_beta <- tcrdist_matrix(beta_only, "human")
# }