Package 'immunarch'

Description

Get a column's name using the input alias

Usage

.quant_column_choice(x)

Arguments

Value

A string with the column name.

Developer Examples

immunarch:::.quant_column_choice("count") immunarch:::.quant_column_choice("freq")

Description

Tables with amino acid properties

Description

Amino acid / codon table

Usage

AA_TABLE

Format

An object of class table of length 65.

Description

Add a new class attribute

Usage

add_class(.obj, .class)

Arguments

Value

Input object with additional class .class.

Developer Examples

tmp <- "abc" class(tmp) tmp <- immunarch:::add_class(tmp, "new_class") class(tmp)

Description

A family of functions to quantify receptor overabundance per repertoire. Helps in deciphering the structure and partition the repertoire.

Available functions

Supported methods are the following.

airr_clonality_line - build ranked abundance lines: for each repertoire, take the top limit receptors by count and attach repertoire metadata. Useful for per-repertoire rank-abundance plots.

airr_clonality_rank - aggregate clonal space by rank bins. Receptors are ordered by proportion within each repertoire; each receptor is assigned to the smallest threshold in bins that contains its rank.

airr_clonality_prop - aggregate clonal space by proportion bins. Each receptor is assigned to a named bin according to its proportion (e.g., Hyperexpanded >= 1e-2, Large >= 1e-3, ...). Thresholds are matched in descending order; unmatched receptors fall into "Ultra-rare".

Usage

airr_clonality_line(
  idata,
  limit = 1e+05,
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

airr_clonality_rank(
  idata,
  bins = c(10, 30, 100, 300, 1000, 10000, 1e+05),
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

airr_clonality_prop(
  idata,
  bins = c(Hyperexpanded = 0.01, Large = 0.001, Medium = 1e-04, Small = 1e-05, Rare =
    1e-06),
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

Arguments

Value

airr_clonality_line

A tibble with columns:

• repertoire_id - repertoire identifier

• index - rank within repertoire (1 = most abundant)

• count - receptor count used for ranking

• plus any repertoire metadata columns carried from idata$repertoires

airr_clonality_rank

A tibble with

• repertoire_id

• clonal_rank_bin - the rank threshold (e.g., 10, 100, ...)

• occupied_prop - sum of proportion within the bin

• plus repertoire metadata columns from idata$repertoires

airr_clonality_prop

A tibble with

• repertoire_id

• clonal_prop_bin - factor-like label from names(bins) or "Ultra-rare"

• occupied_prop - sum of proportion within the bin

• plus repertoire metadata columns from idata$repertoires

See Also

• Per-repertoire summaries: annotate_clonality

• Data container: immundata::ImmunData

Examples

# Limit the number of threads used by the underlying DB for this session.
# Change this only if you know what you're doing (e.g., multi-user machines, shared CI/servers).
db_exec("SET threads TO 1")

# Load data
## Not run: 
immdata <- get_test_idata() |> agg_repertoires("Therapy")

## End(Not run)

#
# airr_clonality_line
#
## Not run: 
top_line <- airr_clonality_line(immdata, limit = 1000)

## End(Not run)

#
# airr_clonality_rank
#
## Not run: 
rank_stat <- airr_clonality_rank(immdata, bins = c(10, 100))

## End(Not run)

#
# airr_clonality_prop
#
## Not run: 
prop_stat <- airr_clonality_prop(immdata)

## End(Not run)

Description

A family of functions that extract core descriptive statistics from an ImmunData object.

Available functions

Supported methods are the following.

airr_desc_chains — count V(D)J chains per repertoire (optionally split by locus). Quickly gauges capture depth per repertoire and, when split by locus, reveals TRA/TRB/IGH balance. Use it for QC, library-size checks, and to spot locus-specific dropouts or over-representation.

airr_desc_lengths — count the number of sequence lengths per repertoire. Summarizes the CDR3 length distribution, a sensitive QC fingerprint of repertoire prep and selection. Helpful for detecting primer/UMI biases, comparing cohorts, and deriving length-based features for models.

airr_desc_genes - count V(D)J gene segments per repertoire, optionally split by locus and using either receptor counts or barcode/UMI counts as the measure. Profiles V/D/J gene usage to characterize repertoire composition and germline biases, with optional locus split. Useful for cohort comparisons, flagging clonal expansions, and producing ML-ready features for repertoire-level ML tasks.

Usage

airr_desc_chains(
  idata,
  locus_col = NA,
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

airr_desc_lengths(
  idata,
  seq_col = "cdr3_aa",
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

airr_desc_genes(
  idata,
  gene_col = "v_call",
  level = c("receptor", "barcode"),
  by = c(NA, "locus"),
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

Arguments

Value

airr_desc_chains Returns a tibble with columns:

• repertoire_id – repertoire identifier

• locus – TRA, TRB, IGH, ... (present only if locus_col is supplied)

• n_chains – number of chains

airr_desc_lengths Returns a tibble with columns:

• repertoire_id – repertoire identifier

• seq_len – lengths of sequences

• n – number of receptors

airr_desc_genes A tibble with columns:

• repertoire_id - repertoire identifier

• (optional) locus - TRA, TRB, IGH, ... (present only when by = "locus" and the locus column exists)

• ⁠<gene_col>⁠ - the gene segment value (e.g., V gene)

• n - the measure:

  • if level = "receptor": number of receptors carrying the gene segment

  • if level = "barcode": sum of counts across receptors for the segment

See Also

immundata::ImmunData

Examples

# Limit the number of threads used by the underlying DB for this session.
# Change this only if you know what you're doing (e.g., multi-user machines, shared CI/servers).
db_exec("SET threads TO 2")

# Load data
## Not run: 
immdata <- get_test_idata() |> agg_repertoires("Therapy")

## End(Not run)

#
# airr_desc_chains
#

## Not run: 
airr_desc_chains(immdata)

## End(Not run)

#
# airr_desc_lengths
#

## Not run: 
airr_desc_lengths(immdata)

## End(Not run)

#
# airr_desc_genes
#

## Not run: 
# V gene usage by receptor count
airr_desc_genes(immdata, gene_col = "v_call", level = "receptor")

# V gene usage by summed cell/UMI counts (if a count column is present)
airr_desc_genes(immdata, gene_col = "v_call", level = "barcode")

# Split by locus (TRA/TRB/... if locus column exists)
airr_desc_genes(immdata, gene_col = "v_call", level = "receptor", by = "locus")

## End(Not run)

Description

A family of functions to quantify receptor diversity per repertoire. A characteristic of a whole repertoire.

Available functions

Supported methods are the following.

airr_diversity_dxx - coverage diversity: minimal number of top receptors needed to reach ⁠perc%⁠ of clonal space (by proportion). Great for spotting dominance/overexpansion and for quick, interpretable dashboards (e.g., D50 = receptors to cover half of the repertoire).

airr_diversity_chao1 - Chao1 estimator is a nonparameteric asymptotic estimator of species richness (number of species in a population). One of the most used methods for estimating immune repertoire diversity.

airr_diversity_shannon - Shannon entropy (base 2) per repertoire computed from proportion. Ideal when you want a single evenness-aware diversity score; pair with Pielou/Hill for samples with very different richness.

airr_diversity_pielou - Pielou's evenness H / log2(S) with richness S. Best when you need a size-normalized evenness score that's comparable across repertoires with different receptor counts.

airr_diversity_index - convenience alias for Hill number with q = 1 (exp(Shannon) using natural log). A solid default single metric that's relatively robust to rare-count noise and easy to compare across samples.

airr_diversity_hill - Hill numbers ("true diversity") for orders ⁠q \eqn{\in}{in} {0, 1, 2, ...}⁠: q=0 richness, q=1 exp(Shannon), q>1 emphasizes abundant receptors. Perfect when you want a diversity profile that tunes sensitivity to rare vs. abundant clonotypes.

Usage

airr_diversity_dxx(
  idata,
  perc = 50,
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

airr_diversity_chao1(
  idata,
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

airr_diversity_shannon(
  idata,
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

airr_diversity_pielou(
  idata,
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

airr_diversity_index(
  idata,
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

airr_diversity_hill(
  idata,
  q = 0:5,
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

Arguments

Value

airr_diversity_dxx

A tibble with:

• imd_repertoire_id

• perc

• dxx - minimal count of top receptors to reach ⁠perc%⁠

• plus repertoire metadata from idata$repertoires

airr_diversity_chao1

A tibble with:

• imd_repertoire_id

• Estimator - number of species

• SD - standard deviation for the estimator value

• Conf.95.lo - CI 0.025

• Conf.95.hi - CI 0.975

• plus repertoire metadata from idata$repertoires

airr_diversity_shannon

A tibble with:

• imd_repertoire_id

• shannon - entropy in bits

airr_diversity_pielou

A tibble with:

• imd_repertoire_id

• shannon

• n_receptors

• pielou - evenness in ⁠[0, 1]⁠ (NA if S <= 1)

airr_diversity_index

A tibble with:

• imd_repertoire_id

• q = 1

• hill_number

• plus repertoire metadata from idata$repertoires

airr_diversity_hill

A tibble with:

• imd_repertoire_id

• q - Hill order

• hill_number - true diversity of order q

• plus repertoire metadata from idata$repertoires

See Also

immundata::ImmunData

Examples

# Limit the number of threads used by the underlying DB for this session.
# Change this only if you know what you're doing (e.g., multi-user machines, shared CI/servers).
db_exec("SET threads TO 1")
# Load data
## Not run: 
immdata <- get_test_idata() |> agg_repertoires("Therapy")

## End(Not run)

#
# airr_diversity_dxx
#
## Not run: 
d50 <- airr_diversity_dxx(immdata, perc = 50)
d_multi <- airr_diversity_dxx(immdata, perc = c(20, 50, 80))

## End(Not run)

#
# airr_diversity_chao1
#
## Not run: 
chao <- airr_diversity_chao1(immdata)

## End(Not run)

#
# airr_diversity_shannon
#
## Not run: 
sh <- airr_diversity_shannon(immdata)

## End(Not run)

#
# airr_diversity_pielou
#
## Not run: 
pj <- airr_diversity_pielou(immdata)

## End(Not run)

#
# airr_diversity_index
#
## Not run: 
idx <- airr_diversity_index(immdata)

## End(Not run)

#
# airr_diversity_hill
#
## Not run: 
hill <- airr_diversity_hill(immdata, q = c(0, 1, 2))

## End(Not run)

Description

A small family of helpers that add clonality labels to each receptor in an immundata::ImmunData object.

Available functions

• annotate_clonality_rank() - label by rank bins within each repertoire.

• annotate_clonality_prop() - label by proportion bins (named thresholds).

annotate_clonality_rank() - for each repertoire, receptors are ordered by within-repertoire abundance (proportion) and assigned a rank bin label.

annotate_clonality_prop() - label each receptor by proportion bin using named thresholds (matched in descending order; else "Ultra-rare").

Usage

annotate_clonality_rank(
  idata,
  bins = c(10, 30, 100, 300, 1000, 10000, 1e+05),
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

annotate_clonality_prop(
  idata,
  bins = c(Hyperexpanded = 0.01, Large = 0.001, Medium = 1e-04, Small = 1e-05, Rare =
    1e-06),
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

Arguments

Value

An immundata::ImmunData whose ⁠$annotations⁠ gains:

• clonal_rank_bin - integer-like label with the applied rank threshold (outside all thresholds -> NA).

An immundata::ImmunData whose ⁠$annotations⁠ gains:

• clonal_prop_bin - label from names(bins) or "Ultra-rare".

See Also

• Per-repertoire summaries: airr_clonality

• Data container: immundata::ImmunData

Examples

## Not run: 
idata <- get_test_idata() |> agg_repertoires("Therapy")
idata_rank <- annotate_clonality_rank(idata)
idata_prop <- annotate_clonality_prop(idata)

## End(Not run)

Description

Apply the given function to every pair in the given datalist. Function either symmetrical (i.e. fun(x,y) == fun(y,x)) or assymmetrical (i.e. fun(x,y) != fun(y,x)).

Usage

apply_symm(.datalist, .fun, ..., .diag = NA, .verbose = TRUE)

apply_asymm(.datalist, .fun, ..., .diag = NA, .verbose = TRUE)

Arguments

Value

Matrix with values M(i,j) = fun(datalist(i), datalist(j))

Examples

data(immdata)
apply_symm(immdata$data, function(x, y) {
  nrow(x) + nrow(y)
})

Description

A dataset with BCR data for testing and examplatory purposes.

Usage

bcrdata

Format

A list of two elements. The first element ("data") is a list of 1 element named "full_clones" that contains immune repertoire data frame. The second element ("meta") is empty metadata table.

data

List of immune repertoire data frames.

meta

Metadata

...

Description

Nucleotide to amino acid sequence translation

Usage

bunch_translate(.seq, .two.way = TRUE, .ignore.n = FALSE)

Arguments

Value

Character vector of translated input sequences.

Examples

data(immdata)
head(bunch_translate(immdata$data[[1]]$CDR3.nt))

Description

Check if the given .data is a distribution and normalise it if necessary with an optional Laplace correction.

Usage

check_distribution(
  .data,
  .do.norm = NA,
  .laplace = 1,
  .na.val = 0,
  .warn.zero = FALSE,
  .warn.sum = TRUE
)

Arguments

Value

Numeric vector.

Developer Examples

immunarch:::check_distribution(c(1, 2, 3)) immunarch:::check_distribution(c(1, 2, 3), TRUE) immunarch:::check_distribution(c(1, 2, 3), FALSE)

Description

Filter out clonotypes with non-coding, coding, in-frame or out-of-frame CDR3 sequences:

coding() - remove all non-coding sequences (i.e., remove all sequences with stop codons and frame shifts);

noncoding() - remove all coding sequences (i.e., leave sequences with stop codons and frame shifts only);

inframes() - remove all out-of-frame sequences (i.e., remove all sequences with frame shifts);

outofframes() - remove all in-frame sequences (i.e., leave sequences with frame shifts only).

Note: the function will remove all clonotypes sequences with NAs in the CDR3 amino acid column.

Usage

coding(.data)

noncoding(.data)

inframes(.data)

outofframes(.data)

Arguments

Value

Filtered data frame.

Examples

data(immdata)
immdata_cod <- coding(immdata$data)
immdata_cod1 <- coding(immdata$data[[1]])

Description

Annotate clonotypes by matching them to known condition-associated immune receptors in a database. Before using this function, you must download or load the relevant database files. For more information, see the online tutorial.

Usage

dbAnnotate(.data, .db, .data.col, .db.col)

Arguments

Value

Data frame with input sequences and counts or proportions for each of the input repertoire.

Examples

data(immdata)

#' # Example file path
file_path <- paste0(system.file(package = "immunarch"), "/extdata/db/vdjdb.example.txt")

# Load the database with human-only TRB-only receptors for all known antigens
db <- dbLoad(file_path, "vdjdb", "HomoSapiens", "TRB")

res <- dbAnnotate(immdata$data, db, "CDR3.aa", "cdr3")
res

Description

The function automatically detects the database format and loads it into R. Additionally, the function provides a general query interface to databases that allows filtering by species, chain types (i.e., locus) and pathology (i.e., antigen species).

Currently we support three popular databases:

VDJDB - https://github.com/antigenomics/vdjdb-db

McPAS-TCR - https://friedmanlab.weizmann.ac.il/McPAS-TCR/

TBAdb from PIRD - https://db.cngb.org/pird/

Usage

dbLoad(.path, .db, .species = NA, .chain = NA, .pathology = NA)

Arguments

Value

Data frame with the input database records.

Examples

# Example file path
file_path <- paste0(system.file(package = "immunarch"), "/extdata/db/vdjdb.example.txt")

# Load the database with human-only TRB-only receptors for all known antigens
db <- dbLoad(file_path, "vdjdb", "HomoSapiens", "TRB")
db

Description

Compute information-based estimates and distances.

Usage

entropy(.data, .base = 2, .norm = FALSE, .do.norm = NA, .laplace = 1e-12)

kl_div(.alpha, .beta, .base = 2, .do.norm = NA, .laplace = 1e-12)

js_div(.alpha, .beta, .base = 2, .do.norm = NA, .laplace = 1e-12, .norm.entropy = FALSE)

cross_entropy(.alpha, .beta, .base = 2, .do.norm = NA,
              .laplace = 1e-12, .norm.entropy = FALSE)

Arguments

Value

A numeric value.

Examples

P <- abs(rnorm(10))
Q <- abs(rnorm(10))
entropy(P)
kl_div(P, Q)
js_div(P, Q)
cross_entropy(P, Q)

Description

The fixVis is a built-in software tool for the manipulation of plots, such as adjusting title text font and size, axes, and more. It is a powerful tool designed to produce publication-ready plots with minimal amount of coding.

Usage

fixVis(.plot = NA)

Arguments

Value

No return value because it is an application.

Examples

if (interactive()) {
  # Compute gene usage, visualise it and tweak via fixVis
  data(immdata) # load test data
  gu <- geneUsage(immdata$data)
  p <- vis(gu)
  fixVis(p)
}

Description

Gene segments table

Description

WIP

Usage

gene_stats()

Value

gene_stats returns all segment gene statistics

Examples

gene_stats()
get_genes("hs.trbv", "segment")

Description

An utility function to analyse the immune receptor gene usage (IGHD, IGHJ, IDHV, IGIJ, IGKJ, IGKV, IGLJ, IGLV, TRAJ, TRAV, TRBD, etc.) and statistics. For gene details run gene_stats().

Usage

geneUsage(
  .data,
  .gene = c("hs.trbv", "HomoSapiens.TRBJ", "macmul.IGHV"),
  .quant = c(NA, "count"),
  .ambig = c("inc", "exc", "maj"),
  .type = c("segment", "allele", "family"),
  .norm = FALSE
)

Arguments

Value

A data frame with rows corresponding to gene segments and columns corresponding to the input samples.

Examples

data(immdata)
gu <- geneUsage(immdata$data)
vis(gu)

Description

The geneUsageAnalysis() function deploys several data analysis methods, including PCA, multidimensional scaling, Jensen-Shannon divergence, k-means, hierarchical clustering, DBscan, and different correlation coefficients.

Usage

geneUsageAnalysis(
  .data,
  .method = c("js+hclust", "pca+kmeans", "anova", "js+pca+kmeans"),
  .base = 2,
  .norm.entropy = FALSE,
  .cor = c("pearson", "kendall", "spearman"),
  .do.norm = TRUE,
  .laplace = 1e-12,
  .verbose = TRUE,
  .k = 2,
  .eps = 0.01,
  .perp = 1,
  .theta = 0.1
)

Arguments

Value

Depends on the last element in the .method string. See immunr_tsne for more info.

Examples

data(immdata)
gu <- geneUsage(immdata$data, .norm = TRUE)
geneUsageAnalysis(gu, "js+hclust", .verbose = FALSE) %>% vis()

Description

Retrieves an update message for immunarch.

Usage

get_immunarch_news(datepoint = "latest")

Arguments

Details

If datepoint is set to "latest", the function returns the most recent update. Otherwise, specify the update date key (e.g., "Apr 2025") to retrieve that particular update. If no matching update is found, a warning is issued along with available update keys.

Value

A character string with the update details or a warning if the key is not found.

See Also

list_immunarch_news()

Description

Usage

getKmers(.data, .k, .col = c("aa", "nt"), .coding = TRUE)

Arguments

Value

Data frame with two columns (k-mers and their counts).

Examples

data(immdata)
kmers <- getKmers(immdata$data[[1]], 5)
kmers %>% vis()

Description

Get a character vector of samples' groups from the input metadata file

Usage

group_from_metadata(.by, .metadata, .sep = "; ")

Arguments

Value

Character vector with group names.

Developer Examples

immunarch:::group_from_metadata("Status", data.frame(Status = c("A", "A", "B", "B", "C")))

Description

A function to check if an input object has a specific class name.

Usage

has_class(.data, .class)

Arguments

Value

Logical value.

Developer Examples

tmp <- "abc" immunarch:::has_class(tmp, "new_class") tmp <- immunarch:::add_class(tmp, "new_class") immunarch:::has_class(tmp, "new_class")

Description

A dataset with single chain TCR data for testing and examplatory purposes.

Usage

immdata

Format

A list of two elements. The first element ("data") is a list with data frames with clonotype tables. The second element ("meta") is a metadata table.

data

List of immune repertoire data frames.

meta

Metadata

...

Description

Get a list of package updates

Usage

immunarch_v1_updates

Format

An object of class list of length 1.

Description

• "Clones" - number of barcodes (events, UMIs) or reads;

• "Proportion" - proportion of barcodes (events, UMIs) or reads;

• "CDR3.nt" - CDR3 nucleotide sequence;

• "CDR3.aa" - CDR3 amino acid sequence;

• "V.name" - names of aligned Variable gene segments;

• "D.name" - names of aligned Diversity gene segments or NA;

• "J.name" - names of aligned Joining gene segments;

• "V.end" - last positions of aligned V gene segments (1-based);

• "D.start" - positions of D'5 end of aligned D gene segments (1-based);

• "D.end" - positions of D'3 end of aligned D gene segments (1-based);

• "J.start" - first positions of aligned J gene segments (1-based);

• "VJ.ins" - number of inserted nucleotides (N-nucleotides) at V-J junction (-1 for receptors with VDJ recombination);

• "VD.ins" - number of inserted nucleotides (N-nucleotides) at V-D junction (-1 for receptors with VJ recombination);

• "DJ.ins" - number of inserted nucleotides (N-nucleotides) at D-J junction (-1 for receptors with VJ recombination);

• "Sequence" - full nucleotide sequence.

Description

Clusters the data with one of the following methods:

• immunr_hclust clusters the data using the hierarchical clustering from hcut;

• immunr_kmeans clusters the data using the K-means algorithm from kmeans;

• immunr_dbscan clusters the data using the DBSCAN algorithm from dbscan.

Usage

immunr_hclust(.data, .k = 2, .k.max = nrow(.data) - 1, .method = "complete", .dist = TRUE)

immunr_kmeans(.data, .k = 2, .k.max = as.integer(sqrt(nrow(.data))) + 1,
.method = c("silhouette", "gap_stat"))

immunr_dbscan(.data, .eps, .dist = TRUE)

Arguments

Value

immunr_hclust - list with two elements. The first element is an output from factoextra::hcut. The second element is an output from factoextra::fviz_nbclust

immunr_kmeans - list with three elements. The first element is an output from kmeans. The second element is an output from factoextra::fviz_nbclust. The third element is the input dataset .data.

immunr_dbscan - list with two elements. The first element is an output from fpc::dbscan. The second element is the input dataset .data.

Examples

data(immdata)
gu <- geneUsage(immdata$data, .norm = TRUE)
immunr_hclust(t(as.matrix(gu[, -1])), .dist = FALSE)

gu[is.na(gu)] <- 0
immunr_kmeans(t(as.matrix(gu[, -1])))

Description

Collects a set of principal variables, reducing the number of not important variables to analyse. Dimensionality reduction makes data analysis algorithms work faster and sometimes more accurate, since it also reduces noise in the data. Currently available methods are:

• immunr_pca performs PCA (Principal Component Analysis) using prcomp;

• immunr_mds performs MDS (Multi-Dimensional Scaling) using isoMODS from MASS package.

• immunr_tsne performs tSNE (t-Distributed Stochastic Neighbour Embedding) using Rtsne Rtsne package.

Usage

immunr_pca(.data, .scale = default_scale_fun, .raw = TRUE, .orig = FALSE, .dist = FALSE)

immunr_mds(.data, .scale = default_scale_fun, .raw = TRUE, .orig = FALSE, .dist = TRUE)

immunr_tsne(.data, .perp = 1, .dist = TRUE, ...)

Arguments

Value

immunr_pca - an output from prcomp.

immunr_mds - an output from isoMDS.

immunr_tsne - an output from Rtsne.

See Also

vis.immunr_pca for visualisations.

Examples

data(immdata)
gu <- geneUsage(immdata$data)
gu[is.na(gu)] <- 0
gu <- t(as.matrix(gu[, -1]))
immunr_pca(gu)
immunr_mds(dist(gu))
immunr_tsne(dist(gu))

Description

For reference please look up https://www.pnas.org/content/111/16/5980 (Fig. 4).

Usage

inc_overlap(
  .data,
  .fun,
  .step = 1000,
  .n.steps = 10,
  .downsample = FALSE,
  .bootstrap = NA,
  .verbose.inc = TRUE,
  ...
)

Arguments

Value

List with overlap matrices.

Examples

## Not run: 
data(immdata)
ov <- repOverlap(immdata$data, "inc+overlap", .step = 100, .verbose.inc = FALSE, .verbose = FALSE)
vis(ov)

## End(Not run)

Description

Returns the list of available update keys for immunarch v1.

Usage

list_immunarch_news()

Value

A character vector containing all the date keys for the available updates.

See Also

get_immunarch_news()

Description

Copy the upper matrix triangle to the lower one

Usage

matrixdiagcopy(.mat)

Arguments

Value

Matrix with its upper tri part copied to the lower tri part.

Developer Examples

mat <- matrix(0, 3, 3) mat mat(1, 3) <- 1 mat <- immunarch:::matrixdiagcopy(mat) mat

Description

Usage

public_matrix(.data)

Arguments

Value

Matrix with per-sample clonotype counts / proportions only.

Examples

data(immdata)
immdata$data <- lapply(immdata$data, head, 2000)
pr <- pubRep(immdata$data, .verbose = FALSE)
pr.mat <- public_matrix(pr)
dim(pr.mat)
head(pr.mat)

Description

Usage

pubRep(
  .data,
  .col = "aa+v",
  .quant = c("count", "prop"),
  .coding = TRUE,
  .min.samples = 1,
  .max.samples = NA,
  .verbose = TRUE
)

Arguments

Value

Data table with columns for:

• Clonotypes (e.g., CDR3 sequence, or two columns for CDR3 sequence and V gene)

• Incidence of clonotypes

• Per-sample proportions or counts

Examples

# Subset the data to make the example faster to run
immdata$data <- lapply(immdata$data, head, 2000)
pr <- pubRep(immdata$data, .verbose = FALSE)
vis(pr, "clonotypes", 1, 2)

Description

Usage

pubRepApply(.pr1, .pr2, .fun = function(x) log10(x[1])/log10(x[2]))

Arguments

Value

Work in progress.

Examples

data(immdata)
immdata$data <- lapply(immdata$data, head, 2000)
pr <- pubRep(immdata$data, .verbose = FALSE)
pr1 <- pubRepFilter(pr, immdata$meta, .by = c(Status = "MS"))
pr2 <- pubRepFilter(pr, immdata$meta, .by = c(Status = "C"))
prapp <- pubRepApply(pr1, pr2)
head(prapp)

Description

Filter our clonotypes with low incidence in a specific group.

Usage

pubRepFilter(.pr, .meta, .by, .min.samples = 1)

Arguments

Value

Data frame with filtered clonotypes.

Examples

data(immdata)
immdata$data <- lapply(immdata$data, head, 2000)
pr <- pubRep(immdata$data, .verbose = FALSE)
pr1 <- pubRepFilter(pr, immdata$meta, .by = c(Status = "MS"))
head(pr1)

Description

Usage

pubRepStatistics(.data, .by = NA, .meta = NA)

Arguments

Value

Data frame with incidence statistics per sample.

Examples

data(immdata)
immdata$data <- lapply(immdata$data, head, 2000)
pr <- pubRep(immdata$data, .verbose = FALSE)
pubRepStatistics(pr) %>% vis()

Description

This function aligns all sequences (incliding germline) that belong to one clonal lineage and one cluster. After clustering and building the clonal lineage and germline, the next step is to analyze the degree of mutation and maturity of each clonal lineage. This allows for finding high mature cells and cells with a large number of offspring. The phylogenetic analysis will find mutations that increase the affinity of BCR. Making alignment of the sequence is the first step towards sequence analysis including BCR.

Usage

repAlignLineage(.data, .min_lineage_sequences, .prepare_threads, .align_threads, .nofail)

Arguments

Value

Dataframe or list of dataframes (if input is a list with multiple samples). The dataframe has these columns:

• Cluster: cluster name

• Germline: germline sequence

• Alignment: DNAbin object with alignment

• Sequences: nested dataframe containing all sequences for this combination of cluster and germline; it has columns

  • Sequence, CDR1.nt, CDR2.nt, CDR3.nt, FR1.nt, FR2.nt, FR3.nt, FR4.nt, V.allele, J.allele, V.aa, J.aa: all values taken from the input dataframe

  • Clone.ID: taken from the input dataframe, or created (filled with row numbers) if missing

  • Clones: taken from the input dataframe, or created (filled with '1' values) if missing

Examples

data(bcrdata)
bcr_data <- bcrdata$data

bcr_data %>%
  seqCluster(seqDist(bcr_data), .fixed_threshold = 3) %>%
  repGermline(.threads = 1) %>%
  repAlignLineage(.min_lineage_sequences = 2, .align_threads = 2, .nofail = TRUE)

Description

This function uses the PHYLIP package to make phylogenetic analysis. For making trees it uses maximum parsimony methods.

Usage

repClonalFamily(.data, .vis_groups, .threads, .nofail)

Arguments

Value

Dataframe or list of dataframes (if input is a list with multiple samples). The dataframe has these columns:

• Cluster: cluster name

• Germline.Input: germline sequence, like it was in the input; not aligned

• Germline.Output: germline sequence, parsed from PHYLIP dnapars function output; it contains difference of germline from the common ancestor; "." characters mean matching letters

• Common.Ancestor: common ancestor sequence, parsed from PHYLIP dnapars function output

• Trunk.Length: mean trunk length, representing the distance between the most recent common ancestor and germline sequence as a measure of the maturity of a lineage

• Tree: output tree in "phylo" format, loaded from by PHYLIP dnapars function output

• TreeStats: nested dataframe containing data about tree nodes, needed for visualization

• Sequences: nested dataframe containing all sequences for this combination of cluster and germline; it contains regions from original sequences, saved for repSomaticHypermutation() calculation, and also data needed for visualizations

Examples

data(bcrdata)
bcr_data <- bcrdata$data

bcr_data %>%
  seqCluster(seqDist(bcr_data), .fixed_threshold = 3) %>%
  repGermline(.threads = 1) %>%
  repAlignLineage(.min_lineage_sequences = 2, .align_threads = 2, .nofail = TRUE) %>%
  repClonalFamily(.threads = 1, .nofail = TRUE)

Description

repClonality function encompasses several methods to measure clonal proportions in a given repertoire.

Usage

repClonality(
  .data,
  .method = c("clonal.prop", "homeo", "top", "rare"),
  .perc = 10,
  .clone.types = c(Rare = 1e-05, Small = 1e-04, Medium = 0.001, Large = 0.01,
    Hyperexpanded = 1),
  .head = c(10, 100, 1000, 3000, 10000, 30000, 1e+05),
  .bound = c(1, 3, 10, 30, 100)
)

Arguments

Details

Clonal proportion assessment is a different approach to estimate repertoire diversity. When visualised, it allows for thorough examination of immune repertoire structure and composition.

In its core this type of analysis is similar to the relative species abundance concept in ecology. Relative abundance is the percent composition of an organism of a particular kind relative to the total number of organisms in the area.

A stacked barplot of relative clonotype abundances can be therefore viewed as a non-parametric approach to comparing their underlying distributions.

Value

If input data is a single immune repertoire, then the function returns a numeric vector with clonality statistics.

Otherwise, it returns a numeric matrix with clonality statistics for all input repertoires.

See Also

repDiversity

Examples

# Load the data
data(immdata)

imm_pr <- repClonality(immdata$data, .method = "clonal.prop")
vis(imm_pr)

imm_top <- repClonality(immdata$data, .method = "top", .head = c(10, 100, 1000, 3000, 10000))
vis(imm_top)

imm_rare <- repClonality(immdata$data, .method = "rare")
vis(imm_rare)

imm_hom <- repClonality(immdata$data, .method = "homeo")
vis(imm_hom)

Description

This is a utility function to estimate the diversity of species or objects in the given distribution.

Note: functions will check if .data is a distribution of a random variable (sum == 1) or not. To force normalisation and / or to prevent this, set .do.norm to TRUE (do normalisation) or FALSE (don't do normalisation), respectively.

Usage

repDiversity(
  .data,
  .method = "chao1",
  .col = "aa",
  .max.q = 6,
  .min.q = 1,
  .q = 5,
  .step = NA,
  .quantile = c(0.025, 0.975),
  .extrapolation = NA,
  .perc = 50,
  .norm = TRUE,
  .verbose = TRUE,
  .do.norm = NA,
  .laplace = 0
)

Arguments

Details

• True diversity, or the effective number of types, refers to the number of equally-abundant types needed for the average proportional abundance of the types to equal that observed in the dataset of interest where all types may not be equally abundant.

• Inverse Simpson index is the effective number of types that is obtained when the weighted arithmetic mean is used to quantify average proportional abundance of types in the dataset of interest.

• The Gini coefficient measures the inequality among values of a frequency distribution (for example levels of income). A Gini coefficient of zero expresses perfect equality, where all values are the same (for example, where everyone has the same income). A Gini coefficient of one (or 100 percents ) expresses maximal inequality among values (for example where only one person has all the income).

• The Gini-Simpson index is the probability of interspecific encounter, i.e., probability that two entities represent different types.

• Chao1 estimator is a nonparameteric asymptotic estimator of species richness (number of species in a population).

• Rarefaction is a technique to assess species richness from the results of sampling through extrapolation.

• Hill numbers are a mathematically unified family of diversity indices (differing among themselves only by an exponent q).

• d50 is a recently developed immune diversity estimate. It calculates the minimum number of distinct clonotypes amounting to greater than or equal to 50 percent of a total of sequencing reads obtained following amplification and sequencing

• dXX is a similar to d50 index where XX corresponds to desirable percent of total sequencing reads.

Value

div, gini, gini.simp, inv.simp, raref return numeric vector of length 1 with value.

chao1 returns 4 values: estimated number of species, standart deviation of this number and two 95% confidence intervals for the species number.

hill returns a vector of specified length .max.q - .min.q

For most methods, if input data is a single immune repertoire, then the function returns a numeric vector with diversity statistics.

Otherwise, it returns a numeric matrix with diversity statistics for all input repertoires.

For Chao1 the function returns a matrix with diversity estimations.

For rarefaction the function returns either a matrix with diversity estimatinos on different step of the simulaiton process or a list with such matrices.

See Also

repOverlap, entropy, repClonality Rarefaction wiki https://en.wikipedia.org/wiki/Rarefaction_(ecology) Hill numbers paper https://www.uvm.edu/~ngotelli/manuscriptpdfs/ChaoHill.pdf Diversity wiki https://en.wikipedia.org/wiki/Measurement_of_biodiversity

Examples

data(immdata)

# Make data smaller for testing purposes
immdata$data <- top(immdata$data, 4000)

# chao1
repDiversity(.data = immdata$data, .method = "chao1") %>% vis()

# Hill numbers
repDiversity(
  .data = immdata$data, .method = "hill", .max.q = 6,
  .min.q = 1, .do.norm = NA, .laplace = 0
) %>% vis()

# diversity
repDiversity(.data = immdata$data, .method = "div", .q = 5, .do.norm = NA, .laplace = 0) %>%
  vis()

# Gini-Simpson
repDiversity(.data = immdata$data, .method = "gini.simp", .q = 5, .do.norm = NA, .laplace = 0) %>%
  vis()

# inverse Simpson
repDiversity(.data = immdata$data, .method = "inv.simp", .do.norm = NA, .laplace = 0) %>% vis()

# Gini coefficient
repDiversity(.data = immdata$data, .method = "gini", .do.norm = NA, .laplace = 0)

# d50
repDiversity(.data = immdata$data, .method = "d50") %>% vis()

Description

The repExplore function calculates the basic statistics of repertoire: the number of unique immune receptor clonotypes, their relative abundances, and sequence length distribution across the input dataset.

Usage

repExplore(
  .data,
  .method = c("volume", "count", "len", "clones"),
  .col = c("nt", "aa"),
  .coding = TRUE
)

Arguments

Value

If input data is a single immune repertoire, then the function returns a numeric vector with exploratory analysis statistics.

Otherwise, it returns a numeric matrix with exploratory analysis statistics for all input repertoires.

See Also

vis.immunr_exp_vol

Examples

data(immdata)

# Calculate statistics and generate a visual output with vis()
repExplore(immdata$data, .method = "volume") %>% vis()

repExplore(immdata$data, .method = "count") %>% vis()

repExplore(immdata$data, .method = "len") %>% vis()

Description

Usage

repFilter(
  .data,
  .method = "by.clonotype",
  .query = list(CDR3.aa = exclude("partial", "out_of_frame")),
  .match = "exact"
)

Arguments

Description

This function creates germlines for clonal lineages. B cell clonal lineage represents a set of B cells that presumably have a common origin (arising from the same VDJ rearrangement event) and a common ancestor. Each clonal lineage has its own germline sequence that represents the ancestral sequence for each BCR in clonal lineage. In other words, germline sequence is a sequence of B-cells immediately after VDJ recombination, before B-cell maturation and hypermutation process. Germline sequence is useful for assessing the degree of mutation and maturity of the repertoire.

Usage

repGermline(.data, .species, .min_nuc_outside_cdr3, .threads)

Arguments

Value

Data with added columns:

• Sequence (FR1+CDR1+FR2+CDR2+FR3+CDR3+FR4 in nucleotides; the column will be replaced if exists)

• V.allele, J.allele (chosen alleles of V and J genes),

• V.aa, J.aa (V and J sequences from original clonotype, outside CDR3, converted to amino acids)

• Germline.sequence (combined germline nucleotide sequence)

Examples

data(bcrdata)

bcrdata$data %>%
  top(5) %>%
  repGermline()

Description

The repLoad function loads repertoire files into R workspace in the immunarch format where you can immediately use them for the analysis. repLoad automatically detects the right format for your files, so all you need is simply provide the path to your files.

See "Details" for more information on supported formats. See "Examples" for diving right into it.

Usage

repLoad(.path, .mode = "paired", .coding = TRUE, ...)

Arguments

Details

The metadata has to be a tab delimited file with first column named "Sample". It can have any number of additional columns with arbitrary names. The first column should contain base names of files without extensions in your folder. Example:

Currently, Immunarch support the following formats:

• "immunoseq" - ImmunoSEQ of any version. http://www.adaptivebiotech.com/immunoseq

• "mitcr" - MiTCR. https://github.com/milaboratory/mitcr

• "mixcr" - MiXCR (the "all" files) of any version. https://github.com/milaboratory/mixcr

• "migec" - MiGEC. http://migec.readthedocs.io/en/latest/

• "migmap" - For parsing IgBLAST results postprocessed with MigMap. https://github.com/mikessh/migmap

• "tcr" - tcR, our previous package. https://imminfo.github.io/tcr/

• "vdjtools" - VDJtools of any version. http://vdjtools-doc.readthedocs.io/en/latest/

• "imgt" - IMGT HighV-QUEST. http://www.imgt.org/HighV-QUEST/

• "airr" - adaptive immune receptor repertoire (AIRR) data format. http://docs.airr-community.org/en/latest/datarep/overview.html

• "10x" - 10XGenomics clonotype annotations tables. https://support.10xgenomics.com/single-cell-vdj/software/pipelines/latest/output/annotation

• "archer" - ArcherDX clonotype tables. https://archerdx.com/

Value

A list with two named elements:

• "data" is a list of input samples;

• "meta" is a data frame with sample metadata.

See Also

immunr_data_format for immunarch data format; repSave for file saving; repOverlap, geneUsage and repDiversity for starting with immune repertoires basic statistics.

Examples

# To load the data from a single file (note that you don't need to specify the data format):
file_path <- paste0(system.file(package = "immunarch"), "/extdata/io/Sample1.tsv.gz")
immdata <- repLoad(file_path)

# Suppose you have a following structure in your folder:
# >_ ls
# immunoseq1.txt
# immunoseq2.txt
# immunoseq3.txt
# metadata.txt

# To load the whole folder with every file in it type:
file_path <- paste0(system.file(package = "immunarch"), "/extdata/io/")
immdata <- repLoad(file_path)
print(names(immdata))

# We recommend creating a metadata file named "metadata.txt" in the folder.

# In that case, when you load your data you will see:
# > immdata <- repLoad("path/to/your/folder/")
# > names(immdata)
# [1] "data" "meta"

# If you do not have "metadata.txt", you will see the same output,
# but your metadata will be almost empty:
# > immdata <- repLoad("path/to/your/folder/")
# > names(immdata)
# [1] "data" "meta"

Description

The repOverlap function is designed to analyse the overlap between two or more repertoires. It contains a number of methods to compare immune receptor sequences that are shared between individuals.

Usage

repOverlap(
  .data,
  .method = c("public", "overlap", "jaccard", "tversky", "cosine", "morisita",
    "inc+public", "inc+morisita"),
  .col = "aa",
  .a = 0.5,
  .b = 0.5,
  .verbose = TRUE,
  .step = 1000,
  .n.steps = 10,
  .downsample = FALSE,
  .bootstrap = NA,
  .verbose.inc = NA,
  .force.matrix = FALSE
)

Arguments

Details

"public" and "shared" are synonyms that exist for the convenience of researchers.

The "overlap" coefficient is a similarity measure that measures the overlap between two finite sets.

The "jaccard" index is conceptually a percentage of how many objects two sets have in common out of how many objects they have total.

The "tversky" index is an asymmetric similarity measure on sets that compares a variant to a prototype.

The "cosine" index is a measure of similarity between two non-zero vectors of an inner product space that measures the cosine of the angle between them.

The "morisita" index measures how many times it is more likely to randomly select two sampled points from the same quadrat (the dataset is covered by a regular grid of changing size) then it would be in the case of a random distribution generated from a Poisson process. Duplicate objects are merged with their counts are summed up.

Value

In most cases the return value is a matrix with overlap values for each pair of repertoires.

If only two repertoires were provided, return value is single numeric value.

If one of the incremental method is chosen, return list of overlap matrix.

See Also

inc_overlap, vis

Examples

data(immdata)

# Make data smaller for testing purposes
immdata$data <- top(immdata$data, 4000)

ov <- repOverlap(immdata$data, .verbose = FALSE)
vis(ov)

ov <- repOverlap(immdata$data, "jaccard", .verbose = FALSE)
vis(ov, "heatmap2")

Description

The repOverlapAnalysis() function contains advanced data analysis methods. You can use several clustering and dimensionality reduction techniques in order to investigate further the difference between repertoires provided.

To cluster a subset of similar data with repOverlapAnalysis() you can perform hierarchical clustering, k-means or dbscan ('hclust', 'kmeans', 'dbscan' respectively).

To reduce dimensions, for example, to select features for subsequent analysis, you can execute the multidimensional scaling or t-sne algorithms ('mds' and 'tsne' respectively).

Usage

repOverlapAnalysis(
  .data,
  .method = ("hclust"),
  .scale = default_scale_fun,
  .raw = TRUE,
  .perp = 1,
  .theta = 0.1,
  .eps = 0.01,
  .k = 2
)

Arguments

Value

Depends on the last element in the .method string. See immunr_tsne for more info.

Examples

data(immdata)
ov <- repOverlap(immdata$data)
repOverlapAnalysis(ov, "mds+hclust") %>% vis()

Description

Sample (downsample) repertoires using different approches.

Usage

repSample(
  .data,
  .method = c("downsample", "resample", "sample"),
  .n = NA,
  .prob = TRUE
)

Arguments

Details

If .method is "downsample" then repSample chooses .n clones (not clonotypes!) from the input repertoires without any probabilistic simulation, but exactly computing each choosed clones. Such approach is is more consistent and biologically pleasant than an output from the function if .method is "resample".

If .method is "resample" then repSample uses multinomial distribution to compute the number of occurences for each cloneset. then it removes zero-number clonotypes and return the resulting data frame. Probabilities for rmultinom for each cloneset is a percentage of this cloneset in the "Proportion" column. It's a some sort of simulation of how clonotypes are chosen from the organisms.

if .method is "sample" then repSample chooses .n clonotypes (not clones!) randomly. Depending on the .prob argument, the function chooses clonotypes either according to their size (if .prob is TRUE, by default), or each clonotype has an equal chance to be choosed (if .prob is FALSE). Note that sampling is done without replacing.

Value

Subsampled immune repertoire or a list of subsampled immune repertoires.

See Also

rmultinom, clonal_proportion

Examples

data(immdata)
# Downsampling to 1000 clones (not clonotypes!)
tmp <- repSample(immdata$data[[1]], .n = 1000)
sum(tmp$Clones)

# Downsampling to 1000 clonotypes
tmp <- repSample(immdata$data[[1]], "sample", .n = 1000)
nrow(tmp)

# Downsampling to the smallest repertoire by clones (not clonotypes!)
tmp <- repSample(immdata$data[c(1, 2)])
sum(tmp[[1]]$Clones)
sum(tmp[[2]]$Clones)

# Downsampling to the smallest repertoire by clonotypes
tmp <- repSample(immdata$data[c(1, 2)], "sample")
nrow(tmp[[1]]$Clones)
nrow(tmp[[2]]$Clones)

Description

The repSave function is deigned to save your data to the disk in desirable format. Currently supports "immunarch" and "vdjtools" file formats.

Usage

repSave(.data, .path, .format = c("immunarch", "vdjtools"), .compress = TRUE)

Arguments

Details

It is not necessary to create directories beforehand. If the provided directory does not exist it will be created automatically.

Value

No return value.

Examples

## Not run: 
data(immdata)
# Reduce data to save time on examples
immdata$data <- map(immdata$data, ~ .x %>% head(10))
dirpath <- tempdir()
# Save the list of repertoires
repSave(immdata, dirpath)
# Load it and check if it is the same
new_immdata <- repLoad(dirpath)
# sum(immdata$data[[1]] != new_immdata$data[[1]], na.rm = TRUE)
# sum(immdata$data[[2]] != new_immdata$data[[2]], na.rm = TRUE)
# sum(immdata$meta != new_immdata$meta, na.rm = TRUE)

## End(Not run)

Description

A family of functions to quantify public or shared receptors between repertoire.

Available functions

Supported methods are the following.

repsim_intersection - number of shared receptors between each pair of repertoires (intersection size). Handy for quick overlap heatmaps, QC of replicate similarity, or spotting donor-shared "public" clonotypes.

repsim_jaccard - Jaccard similarity of receptor sets between repertoires ($A \cap B$ / $A \cup B$). Best when comparing cohorts with different sizes to get a scale-invariant overlap score.

Usage

repsim_intersection(
  idata,
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

repsim_jaccard(
  idata,
  autojoin = getOption("immundata.autojoin", TRUE),
  format = c("long", "wide")
)

Arguments

Value

repsim_intersection

A symmetric numeric matrix where rows/columns are repertoire_id and each cell is the count of shared unique receptors. The diagonal contains per-repertoire richness (total unique receptors). Row/column names are repertoire IDs.

repsim_jaccard

A symmetric numeric matrix where rows/columns are repertoire_id and each cell is the Jaccard similarity in ⁠[0, 1]⁠. The diagonal is 1. Row/column names are repertoire IDs.

See Also

immundata::ImmunData

Examples

# Limit the number of threads used by the underlying DB for this session.
# Change this only if you know what you're doing (e.g., multi-user machines, shared CI/servers).
db_exec("SET threads TO 1")
# Load data
## Not run: 
immdata <- get_test_idata() |> agg_repertoires("Therapy")

## End(Not run)

#
# repsim_intersection
#
## Not run: 
m_pub <- repsim_intersection(immdata)

## End(Not run)

#
# repsim_jaccard
#
## Not run: 
m_jac <- repsim_jaccard(immdata)

## End(Not run)

Description

This function aligns V and J genes from the germline in each cluster with corresponding genes in each clonotype, saves the alignments for purpose of visualization, and calculates number of mutations for each clonotype.

Usage

repSomaticHypermutation(.data, .threads, .nofail)

Arguments

Value

Dataframe or list of dataframes (if input is a list with multiple samples). The dataframe has all the columns from repClonalFamily() output dataframe, with Sequence column unnested: the resulting dataframe has one line per clonotype. Clone.ID column contains original IDs for clonotypes, and can be used as dataframe key. New columns are added:

• Germline.Alignment.V: contains V gene alignment of current clonotype with the germline

• Germline.Alignment.J: contains J gene alignment of current clonotype with the germline

• Substitutions: contains number of substitutions in the alignment (summary for V and J)

• Insertions: contains number of insertions in the clonotype relative to germline (summary for V and J)

• Deletions: contains number of deletions in the clonotype relative to germline (summary for V and J)

• Mutations: contains total number of mutations in the alignment (summary for V and J)

Examples

data(bcrdata)
bcr_data <- bcrdata$data

bcr_data %>%
  seqCluster(seqDist(bcr_data), .fixed_threshold = 3) %>%
  repGermline(.threads = 1) %>%
  repAlignLineage(.min_lineage_sequences = 2, .align_threads = 2, .nofail = TRUE) %>%
  repClonalFamily(.threads = 1, .nofail = TRUE) %>%
  repSomaticHypermutation(.threads = 1, .nofail = TRUE)

Description

Subsets the input immune repertoire by barcodes. Creates a vector of barcodes to subset or a vector cluster IDs and corresponding barcodes to get a list of immune repertoires corresponding to cluster IDs. Columns with clonotype counts and proportions are changed accordingly to the filtered barcodes.

Usage

select_barcodes(.data, .barcodes, .force.list = FALSE)

Arguments

Value

An immune repertoire (if ".barcodes" is a barcode vector) or a list of immune repertoires (if ".barcodes" is named vector or an output from Seurat::Idents()). Each element is an immune repertoire with clonotype barcodes corresponding to the input barcodes. The output list names are cluster names in the ".barcode" argument (Seurat::Idents() case only).

See Also

select_clusters

Examples

## Not run: 
data(immdata)
# Create a fake single-cell data
df <- immdata$data[[1]]
df$Barcode <- "AAAAACCCCC"
df$Barcode[51:nrow(df)] <- "GGGGGCCCCC"
barcodes <- "AAAAACCCCC"
df <- select_barcodes(df, barcodes)
nrow(df)

## End(Not run)

Description

Given the vector of barcodes from Seurat, splits the input repertoires to separate subsets following the barcodes' assigned IDs. Useful in case you want to split immune repertoires by patients or clusters.

Usage

select_clusters(.data, .clusters, .field = "Cluster")

Arguments

Value

A list with two elements "data" and "meta" with updated immune repertoire tables and metadata.

See Also

select_barcodes

Examples

## Not run: 
library(Seurat)
Idents(pbmc_small)
new_cluster_ids <- c("A", "B", "C")
new_cluster_ids <- levels(pbmc_small)
new_cluster_ids
pbmc_small <- RenameIdents(pbmc_small, new_cluster_ids)

## End(Not run)

Description

Graph clustering based on distances between sequences

Usage

seqCluster(.data, .dist, .perc_similarity, .nt_similarity, .fixed_threshold)

Arguments

Value

Immdata data format object. Same as .data, but with extra 'Cluster' column with clusters assigned.

Examples

## Not run: 
data(immdata)
# In this example, we will use only 2 samples with 500 clonotypes in each for time saving
input_data <- lapply(immdata$data[1:2], head, 500)
dist_result <- seqDist(input_data)
cluster_result <- seqCluster(input_data, dist_result, .fixed_threshold = 1)

## End(Not run)

Description

Computing sequential distances between clonotypes from two repertoires:

Usage

seqDist(.data, .col = 'CDR3.nt', .method = 'hamming',
 .group_by = c("V.name", "J.name"), .group_by_seqLength = TRUE, .trim_genes = TRUE, ...)

Arguments

Value

Named list of list with dist objects for given repertoires for each combination of .group_by variable(s) and/or sequence length of .col.

Examples

## Not run: 
data(immdata)
# Reducing data to save time on examples
immdata$data <- map(immdata$data, ~ .x %>% head(10))
# Computing hamming distance for the first two repertoires in `'immdata'`
seqDist(immdata$data[1:2])

# Here we define a custom distance function
# that will count the difference in number of characters in sequences.

f <- function(x, y) {
  res <- matrix(nrow = length(x), ncol = length(y))
  for (i in 1:length(x)) {
    res[i, ] <- abs(nchar(x[i]) - nchar(y))
  }
  dimnames(res) <- list(x, y)
  return(as.dist(res))
}

seqDist(immdata$data[1:2], .method = f, .group_by_seqLength = FALSE)

## End(Not run)

Description

Set and update progress bars

Usage

set_pb(.max)

add_pb(.pb, .value = 1)

Arguments

Value

An updated progress bar.

Developer Examples

pb <- immunarch:::set_pb(100) immunarch:::add_pb(pb, 25) immunarch:::add_pb(pb, 25) immunarch:::add_pb(pb, 25) immunarch:::add_pb(pb, 25) close(pb)

Description

Usage

spectratype(.data, .quant = c("id", "count"), .col = "nt")

Arguments

Value

Data frame with distributions of clonotypes per CDR3 length.

Examples

# Load the data
data(immdata)
sp <- spectratype(immdata$data[[1]], .col = "aa+v")
vis(sp)

Description

Usage

split_to_kmers(.data, .k)

kmer_profile(.data, .method = c("freq", "prob", "wei", "self"), .remove.stop = TRUE)

Arguments

Value

split_to_kmers - Data frame with two columns (k-mers and their counts).

kmer_profile - a matrix with per-position amino acid statistics.

Examples

data(immdata)
kmers <- getKmers(immdata$data[[1]], 5)
kmer_profile(kmers) %>% vis()

Description

Return a column's name

Usage

switch_type(type)

process_col_argument(.col)

Arguments

Value

A column's name.

Developer Examples

immunarch:::switch_type("nuc") immunarch:::switch_type("v")

Description

Get the N most abundant clonotypes

Usage

top(.data, .n = 10)

Arguments

Value

Data frame with the .n most abundant clonotypes only.

Examples

data(immdata)
top(immdata$data)
top(immdata$data[[1]])

Description

Tracks the temporal dynamics of clonotypes in repertoires. For example, tracking across multiple time points after vaccination.

Note: duplicated clonotypes are merged and their counts are summed up.

Usage

trackClonotypes(.data, .which = list(1, 15), .col = "aa", .norm = TRUE)

Arguments

Value

Data frame with input sequences and counts or proportions for each of the input repertoire.

Examples

# Load an example data that comes with immunarch
data(immdata)

# Make the data smaller in order to speed up the examples
immdata$data <- immdata$data[c(1, 2, 3, 7, 8, 9)]
immdata$meta <- immdata$meta[c(1, 2, 3, 7, 8, 9), ]

# Option 1
# Choose the first 10 amino acid clonotype sequences
# from the first repertoire to track
tc <- trackClonotypes(immdata$data, list(1, 10), .col = "aa")
# Choose the first 20 nucleotide clonotype sequences
# and their V genes from the "MS1" repertoire to track
tc <- trackClonotypes(immdata$data, list("MS1", 20), .col = "nt+v")

# Option 2
# Choose clonotypes with amino acid sequences "CASRGLITDTQYF" or "CSASRGSPNEQYF"
tc <- trackClonotypes(immdata$data, c("CASRGLITDTQYF", "CSASRGSPNEQYF"), .col = "aa")

# Option 3
# Choose the first 10 clonotypes from the first repertoire
# with amino acid sequences and V segments
target <- immdata$data[[1]] %>%
  select(CDR3.aa, V.name) %>%
  head(10)
tc <- trackClonotypes(immdata$data, target)

# Visualise the output regardless of the chosen option
# Therea are three way to visualise it, regulated by the .plot argument
vis(tc, .plot = "smooth")
vis(tc, .plot = "area")
vis(tc, .plot = "line")

# Visualising timepoints
# First, we create an additional column in the metadata with randomly choosen timepoints:
immdata$meta$Timepoint <- sample(1:length(immdata$data))
immdata$meta
# Next, we create a vector with samples in the right order,
# according to the "Timepoint" column (from smallest to greatest):
sample_order <- order(immdata$meta$Timepoint)
# Sanity check: timepoints are following the right order:
immdata$meta$Timepoint[sample_order]
# Samples, sorted by the timepoints:
immdata$meta$Sample[sample_order]
# And finally, we visualise the data:
vis(tc, .order = sample_order)

Description

vis() is a lightweight, quick-look plotting helper. It's designed to help you visualise results fast with sensible defaults. It automatically detects the input type and chooses an appropriate visualisation (e.g., output from airr_stats_genes() is recognised as gene usage values and plotted without extra arguments).

vis() is not intended for publication-quality figures. For serious, highly customised, or publication-ready plots, I recommend building your graphics directly with ggplot2.

Usage

vis(.data, ...)

Arguments

Details

List of available visualisations for different kinds of data - will be available soon.

Value

A ggplot2 object.

See Also

fixVis for precise manipulation of plots.

Examples

## Not run: 
immdata <- get_test_idata() |> agg_repertoires("Therapy")
airr_stats_genes(immdata, gene_col = "v_call") |> vis()
airr_public_jaccard(immdata) |> vis()
airr_diversity_pielou(immdata) |> vis()
airr_diversity_chao1(immdata) |> vis()

## End(Not run)

Description

Usage

vis_bar(
  .data,
  .by = NA,
  .meta = NA,
  .errorbars = c(0.025, 0.975),
  .errorbars.off = FALSE,
  .stack = FALSE,
  .points = TRUE,
  .test = TRUE,
  .signif.label.size = 3.5,
  .errorbar.width = 0.2,
  .defgroupby = "Sample",
  .grouping.var = "Group",
  .labs = c("X", "Y"),
  .title = "Barplot (.title argument)",
  .subtitle = "Subtitle (.subtitle argument)",
  .legend = NA,
  .leg.title = "Legend (.leg.title argument)",
  .legend.pos = "right",
  .rotate_x = 90
)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
vis_bar(data.frame(Sample = c("A", "B", "C"), Value = c(1, 2, 3)))

## End(Not run)

Description

Visualisation of distributions using ggplot2-based boxplots.

Usage

vis_box(
  .data,
  .by = NA,
  .meta = NA,
  .melt = TRUE,
  .points = TRUE,
  .test = TRUE,
  .signif.label.size = 3.5,
  .defgroupby = "Sample",
  .grouping.var = "Group",
  .labs = c("X", "Y"),
  .title = "Boxplot (.title argument)",
  .subtitle = "Subtitle (.subtitle argument)",
  .legend = NA,
  .leg.title = "Legend (.leg.title argument)",
  .legend.pos = "right"
)

Arguments

Value

A ggplot2 object.

See Also

vis.immunr_gene_usage, geneUsage

Examples

## Not run: 
vis_box(data.frame(Sample = sample(c("A", "B", "C"), 100, TRUE), Value = rnorm(100)), .melt = FALSE)

## End(Not run)

Description

Visualise matrices with the circlize::chordDiagram function from the circlize package.

Usage

vis_circos(.data, .title = NULL, ...)

Arguments

Value

A circlize object.

See Also

vis, repOverlap.

Examples

## Not run: 
data(immdata)
ov <- repOverlap(immdata$data)
vis(ov, .plot = "circos")

## End(Not run)

Description

Fast and easy visualisations of matrices or data frames with functions based on the ggplot2 package.

Usage

vis_heatmap(
  .data,
  .text = TRUE,
  .scientific = FALSE,
  .signif.digits = 2,
  .text.size = 4,
  .axis.text.size = NULL,
  .labs = c("Sample", "Sample"),
  .title = "Overlap",
  .leg.title = "Overlap values",
  .legend = TRUE,
  .na.value = NA,
  .transpose = FALSE,
  ...
)

Arguments

Value

A ggplot2 object.

See Also

vis, repOverlap.

Examples

## Not run: 
data(immdata)
ov <- repOverlap(immdata$data)
vis_heatmap(ov)
gu <- geneUsage(immdata$data, "hs.trbj")
vis_heatmap(gu)

## End(Not run)

Description

Visualise matrices with the functions based on the pheatmap package with minimum amount of arguments.

Usage

vis_heatmap2(
  .data,
  .meta = NA,
  .by = NA,
  .title = NA,
  .color = colorRampPalette(c("#67001f", "#d6604d", "#f7f7f7", "#4393c3",
    "#053061"))(1024),
  ...
)

Arguments

Value

A pheatmap object.

See Also

vis, repOverlap

Examples

## Not run: 
data(immdata)
ov <- repOverlap(immdata$data)
vis_heatmap2(ov)

## End(Not run)

Description

Visualisation of distributions using ggplot2-based histograms.

Usage

vis_hist(
  .data,
  .by = NA,
  .meta = NA,
  .title = "Gene usage",
  .ncol = NA,
  .points = TRUE,
  .test = TRUE,
  .coord.flip = FALSE,
  .grid = FALSE,
  .labs = c("Gene", NA),
  .melt = TRUE,
  .legend = NA,
  .add.layer = NULL,
  ...
)

Arguments

Details

If data is grouped, then statistical tests for comparing means of groups will be performed, unless .test = FALSE is supplied. In case there are only two groups, the Wilcoxon rank sum test (https://en.wikipedia.org/wiki/Wilcoxon_signed-rank_test) is performed (R function wilcox.test() with an argument exact = FALSE) for testing if there is a difference in mean rank values between two groups. In case there more than two groups, the Kruskal-Wallis test (https://en.wikipedia.org/wiki/Kruskal%E2%80%93Wallis_one-way_analysis_of_variance) is performed (R function kruskal.test()), that is equivalent to ANOVA for ranks and it tests whether samples from different groups originated from the same distribution. A significant Kruskal-Wallis test indicates that at least one sample stochastically dominates one other sample. Adjusted for multiple comparisons P-values are plotted on the top of groups. P-value adjusting is done using the Holm method (https://en.wikipedia.org/wiki/Holm%E2%80%93Bonferroni_method) (also known as Holm-Bonferroni correction). You can execute the command ?p.adjust in the R console to see more.

Value

A ggplot2 object.

See Also

vis.immunr_gene_usage, geneUsage

Examples

## Not run: 
data(immdata)
imm_gu <- geneUsage(immdata$data[[1]])
vis(imm_gu,
  .plot = "hist", .add.layer =
    theme(axis.text.x = element_text(angle = 75, vjust = 1))
)
imm_gu <- geneUsage(immdata$data[1:4])
vis(imm_gu,
  .plot = "hist", .grid = TRUE, .add.layer =
    theme(axis.text.x = element_text(angle = 75, vjust = 1))
)

## End(Not run)

Description

#'

Usage

vis_immunr_kmer_profile_main(.data, .plot, ...)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
data(immdata)
getKmers(immdata$data[[1]], 5) %>%
  kmer_profile() %>%
  vis("seqlogo")

## End(Not run)

Description

Visualise correlation of public clonotype frequencies in pairs of repertoires.

Usage

vis_public_clonotypes(
  .data,
  .x.rep = NA,
  .y.rep = NA,
  .title = NA,
  .ncol = 3,
  .point.size.modif = 1,
  .cut.axes = TRUE,
  .density = TRUE,
  .lm = TRUE,
  .radj.size = 3.5
)

Arguments

Value

A ggplot2 object.

See Also

pubRep, vis.immunr_public_repertoire

Examples

## Not run: 
data(immdata)
pr <- pubRep(immdata$data, .verbose = FALSE)
vis(pr, "clonotypes", 1, 2)

## End(Not run)

Description

Visualise public clonotype frequencies.

Usage

vis_public_frequencies(
  .data,
  .by = NA,
  .meta = NA,
  .type = c("boxplot", "none", "mean")
)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
data(immdata)
immdata$data <- lapply(immdata$data, head, 500)
pr <- pubRep(immdata$data, .verbose = FALSE)
vis(pr, "freq", .type = "boxplot")
vis(pr, "freq", .type = "none")
vis(pr, "freq", .type = "mean")
vis(pr, "freq", .by = "Status", .meta = immdata$meta)

## End(Not run)

Description

Plot sequence logo plots for visualising of amino acid motif sequences / profiles.

vis_textlogo plots sequences in a text format - each letter has the same height. Useful when there are no big differences between occurences of amino acids in the motif.

vis_seqlogo is a traditional sequence logo plots. Useful when there are one or two amino acids with clear differences in their occurrences.

Usage

vis_textlogo(.data, .replace.zero.with.na = TRUE, .width = 0.1, ...)

vis_seqlogo(.data, .scheme = "chemistry", ...)

Arguments

Value

A ggplot2 object.

See Also

getKmers, kmer_profile

Examples

## Not run: 
data(immdata)
kmers <- getKmers(immdata$data[[1]], 5)
ppm <- kmer_profile(kmers, "prob")
vis(ppm, .plot = "text")
vis(ppm, .plot = "seq")

d <- kmer_profile(c("CASLL", "CASSQ", "CASGL"))
vis_textlogo(d)
vis_seqlogo(d)

## End(Not run)

Description

Usage

## S3 method for class 'clonal_family'
vis(.data, ...)

Arguments

Value

A ggraph object.

Examples

## Not run: 
data(bcrdata)
bcr_data <- bcrdata$data

clonal_family <- bcr_data %>%
  seqCluster(seqDist(bcr_data), .fixed_threshold = 3) %>%
  repGermline(.threads = 1) %>%
  repAlignLineage(.min_lineage_sequences = 2, .align_threads = 2, .nofail = TRUE) %>%
  repClonalFamily(.threads = 1, .nofail = TRUE) %>%
  vis()

## End(Not run)