annotate_clonality: Annotate clonality - per-receptor labels for overabundance

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")
)

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".

Arguments

idata: An immundata::ImmunData object.
bins: A named numeric vector of thresholds (e.g., c(Hyperexpanded = 1e-2, Large = 1e-3, ...)). Names become bin labels and must be non-empty. Internally sorted in descending order.
autojoin: Logical. If TRUE, join repertoire metadata by the schema repertoire id. Change the default behaviour by calling options(immunarch.autojoin = FALSE).
format: String. One of "long" ("long" tibble with imd_repertoire_id, facet columns, and value; useful for visualizations) or "wide" (wide/unmelted table of features, with each row corresponding to a specific repertoire / pair of repertoires; useful for Machine Learning).

Examples

Run this code

if (FALSE) {
idata <- get_test_idata() |> agg_repertoires("Therapy")
idata_rank <- annotate_clonality_rank(idata)
idata_prop <- annotate_clonality_prop(idata)
}