identicalClones

identicalClones - Sequence identity method for clonal partitioning

Description¶

identicalClones provides a simple sequence identity based partitioning approach for inferring clonal relationships in high-throughput Adaptive Immune Receptor Repertoire sequencing (AIRR-seq) data. This approach partitions B or T cell receptor sequences into clonal groups based on junction region sequence identity within partitions that share the same V gene, J gene, and junction length, allowing for ambiguous V or J gene annotations.

Usage¶

identicalClones(
db,
method = c("nt", "aa"),
junction = "junction",
v_call = "v_call",
j_call = "j_call",
clone = "clone_id",
fields = NULL,
cell_id = NULL,
locus = "locus",
only_heavy = TRUE,
split_light = FALSE,
first = FALSE,
cdr3 = FALSE,
mod3 = FALSE,
max_n = 0,
nproc = 1,
verbose = FALSE,
log = NULL,
summarize_clones = FALSE,
junction_type = c("auto", "nt", "aa")
)

Arguments¶

db: data.frame containing sequence data.
method: one of the "nt" for nucleotide based clustering or "aa" for amino acid based clustering.
junction: character name of the column containing junction sequences. Also used to determine sequence length for grouping.
v_call: name of the column containing the V-segment allele calls.
j_call: name of the column containing the J-segment allele calls.
clone: output column name containing the clonal cluster identifiers.
fields: character vector of additional columns to use for grouping. Sequences with disjoint values in the specified fields will be classified as separate clones.
cell_id: name of the column containing cell identifiers or barcodes. If specified, grouping will be performed in single-cell mode with the behavior governed by the locus and only_heavy arguments. If set to NULL then the bulk sequencing data is assumed.
locus: name of the column containing locus information. Only applicable to single-cell data. Ignored if cell_id=NULL.
only_heavy: This is deprecated. Only heavy chains will be used in clustering. Use only the IGH (BCR) or TRB/TRD (TCR) sequences for grouping. Only applicable to single-cell data. Ignored if cell_id=NULL.
split_light: This is deprecated. If you desire to split clones by light chains use dowser::resolveLightChains.
first: specifies how to handle multiple V(D)J assignments for initial grouping. If TRUE only the first call of the gene assignments is used. If FALSE the union of ambiguous gene assignments is used to group all sequences with any overlapping gene calls.
cdr3: if TRUE removes 3 nucleotides or 1 amino acid residue from both ends of "junction" prior to clustering (converts IMGT junction to CDR3 region). For nucleotide junctions this removes 3 nucleotides from each end and requires a junction length greater than 6 nucleotides; for amino acid junctions this removes 1 residue from each end and requires a junction length greater than 2 residues. Records that are too short are removed.
mod3: if TRUE removes records with a junction length that is not divisible by 3 in nucleotide space. Ignored (with a warning) if the junction column contains amino acid sequences.
max_n: The maximum number of non-ATCG characters permitted in the junction nucleotide sequence, or the maximum number of non-standard amino acid characters permitted in the junction amino acid sequence, before excluding the record from clonal assignment. With the default value of 0, nucleotide sequences containing any non-ATCG characters (including IUPAC codes), or amino acid sequences containing any non-standard amino acid characters, are removed before clustering. Set to NULL to disable filtering.
nproc: number of cores to distribute the function over.
verbose: if TRUE prints out a summary of each step cloning process. if FALSE (default) process cloning silently.
log: output path and filename to save the verbose log. The input file directory is used if path is not specified. The default is NULL for no action.
summarize_clones: if TRUE performs a series of analysis to assess the clonal landscape and returns a ScoperClones object. If FALSE (default) then a modified input db is returned. In single-cell mode, vjl_groups summarizes heavy/long-chain partitions used for clustering. When grouping by fields, summarize_clones should be FALSE.
junction_type: one of "auto" (default), "nt", or "aa". Only used when method="aa" ("aa" is an error for other methods). Declares whether the junction column holds nucleotide or amino acid sequences. With "auto", amino acid content is inferred from the presence of amino-acid-only letters (E, F, I, L, P, Q, …); short amino acid sequences made only of letters shared with the nucleotide alphabet (e.g. "CARDST") cannot be told apart from nucleotides and will be mishandled. Set "aa" or "nt" to skip autodetection.

Value¶

If summarize_clones=FALSE (default) a modified data.frame is returned with clone identifiers in the specified clone column. If summarize_clones=TRUE a ScoperClones object is returned that includes the clonal assignment summary information and a modified input db in the db slot that contains clonal identifiers in the specified clone column.

Single-cell data¶

To invoke single-cell mode the cell_id argument must be specified and the locus column must be correct. Otherwise, clustering will be performed with bulk sequencing assumptions, using all input sequences regardless of the values in the locus column.

Values in the locus column must be one of c("IGH", "IGI", "IGK", "IGL") for BCR or c("TRA", "TRB", "TRD", "TRG") for TCR sequences. Otherwise, the operation will exit and return an error message.

In single-cell mode, clonal clustering is performed using heavy/long chains only (IGH for BCR or TRB/TRD for TCR). The only_heavy=FALSE and split_light=TRUE options are deprecated and ignored with warnings. Consequently, vjl_groups summarizes heavy/long-chain V/J/junction-length partitions and does not define groups from light/short chains.

In single-cell mode, clonal clustering will not be performed on data where cells are assigned multiple heavy/long chain sequences (IGH, TRB, TRD). If observed, the operation will exit and return an error message. Cells that lack a heavy/long chain sequence (i.e., cells with light/short chains only) will be assigned a clone_id of NA.

Examples¶

# Find clonal groups
results <- identicalClones(ExampleDb, summarize_clones=TRUE)

Running defineClonesScoper in bulk mode and only keep heavy chains


# Retrieve modified input data with clonal clustering identifiers
df <- as.data.frame(results)

# Plot clonal summaries
plot(results, binwidth=0.02)