hierarchicalClones - Hierarchical clustering method for clonal partitioning
hierarchicalClones provides a hierarchical agglomerative clustering
approach to infer clonal relationships in high-throughput Adaptive Immune Receptor
Repertoire sequencing (AIRR-seq) data. This approach clusters B or T cell receptor
sequences based on junction region sequence similarity within partitions that share the
same V gene, J gene, and junction length, allowing for ambiguous V or J gene annotations.
hierarchicalClones( db, threshold, method = c("nt", "aa"), linkage = c("single", "average", "complete"), normalize = c("len", "none"), junction = "junction", v_call = "v_call", j_call = "j_call", clone = "clone_id", cell_id = NULL, locus = "locus", only_heavy = TRUE, split_light = TRUE, first = FALSE, cdr3 = FALSE, mod3 = FALSE, max_n = 0, nproc = 1, verbose = FALSE, log = NULL, summarize_clones = TRUE )
- data.frame containing sequence data.
- a numeric scalar where the tree should be cut (the distance threshold for clonal grouping).
- one of the
"nt"for nucleotide based clustering or
"aa"for amino acid based clustering.
- available linkage are
- method of normalization. The default is
"len", which divides the distance by the length of the sequence group. If
"none"then no normalization if performed.
- character name of the column containing junction sequences. Also used to determine sequence length for grouping.
- character name of the column containing the V-segment allele calls.
- character name of the column containing the J-segment allele calls.
- the output column name containing the clonal cluster identifiers.
- 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
only_heavyarguments. If set to
NULLthen the bulk sequencing data is assumed.
- name of the column containing locus information.
Only applicable to single-cell data.
- use only the IGH (BCR) or TRB/TRD (TCR) sequences
for grouping. Only applicable to single-cell data.
- split clones by light chains. Ignored if
- specifies how to handle multiple V(D)J assignments for initial grouping.
TRUEonly the first call of the gene assignments is used. If
FALSEthe union of ambiguous gene assignments is used to group all sequences with any overlapping gene calls.
TRUEremoves 3 nucleotides from both ends of
"junction"prior to clustering (converts IMGT junction to CDR3 region). If
TRUEthis will also remove records with a junction length less than 7 nucleotides.
TRUEremoves records with a
junctionlength that is not divisible by 3 in nucleotide space.
- The maximum number of
Ncharacters to permit in the junction sequence before excluding the record from clonal assignment. Note, with
linkage="single"non-informative positions can create artifactual links between unrelated sequences. Use with caution. Default is set to be zero. Set it as
"NULL"for no action.
- number of cores to distribute the function over.
TRUEprints out a summary of each step cloning process. if
FALSE(default) process cloning silently.
- output path and filename to save the
verboselog. The input file directory is used if path is not specified. The default is
NULLfor no action.
TRUEperforms a series of analysis to assess the clonal landscape and returns a ScoperClones object. If
FALSEthen a modified input
summarize_clones=TRUE (default) 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
data.frame is returned with clone identifiers in the
To invoke single-cell mode the
cell_id argument must be specified and the
column must be correct. Otherwise, clustering will be performed with bulk sequencing assumptions,
using all input sequences regardless of the values in the
Values in the
locus column must be one of
c("IGH", "IGI", "IGK", "IGL") for BCR
c("TRA", "TRB", "TRD", "TRG") for TCR sequences. Otherwise, the operation will exit and
return and error message.
Under single-cell mode with paired-chain sequences, there is a choice of whether
grouping should be done by (a) using IGH (BCR) or TRB/TRD (TCR) sequences only or
(b) using IGH plus IGK/IGL (BCR) or TRB/TRD plus TRA/TRG (TCR) sequences.
This is governed by the
only_heavy argument. There is also choice as to whether
inferred clones should be split by the light/short chain (IGK, IGL, TRA, TRG) following
heavy/long chain clustering, which is governed by the
In single-cell mode, clonal clustering will not be performed on data were 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
# Find clonal groups results <- hierarchicalClones(ExampleDb, threshold=0.15) # Retrieve modified input data with clonal clustering identifiers df <- as.data.frame(results) # Plot clonal summaries plot(results, binwidth=0.02)