annotate_clonality: Annotate clonality - per-receptor labels for overabundance

In immunarch: Multi-Modal Immune Repertoire Analytics for Immunotherapy and Vaccine Design in R

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

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

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)

immunarch documentation built on Nov. 5, 2025, 7:21 p.m.