Skip to contents

Annotate clonality - per-receptor labels for overabundance

Source: R/v1_clonality_annotate.R
annotate_clonality.Rd

[Experimental]

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

Examples

# \dontrun{
idata <- get_test_idata() |> agg_repertoires("Therapy")
#> Rows: 2 Columns: 4
#> ── Column specification ────────────────────────────────────────────────────────
#> Delimiter: "\t"
#> chr (4): File, Therapy, Response, Prefix
#> 
#> ℹ Use `spec()` to retrieve the full column specification for this data.
#> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message.
#> ℹ Found 2/2 repertoire files from the metadata on the disk
#> ✔ Metadata parsed successfully
#> 
#> ── Reading repertoire data 
#>   1. /home/runner/work/_temp/Library/immundata/extdata/tsv/sample_0_1k.tsv
#>   2. /home/runner/work/_temp/Library/immundata/extdata/tsv/sample_1k_2k.tsv
#> ℹ Checking if all files are of the same type
#> ✔ All files have the same extension
#> 
#> ── Renaming the columns and schemas 
#> ✔ Renaming is finished
#> 
#> ── Preprocessing the data 
#>   1. exclude_columns
#>   2. filter_nonproductive
#> ✔ Preprocessing plan is ready
#> 
#> ── Aggregating the data to receptors 
#> ℹ No locus information found
#> ℹ Processing data as immune repertoire tables - no counts, no barcodes, no chain pairing possible
#> ✔ Execution plan for receptor data aggregation and annotation is ready
#> 
#> ── Joining the metadata table with the dataset using 'filename' column 
#> ✔ Joining plan is ready
#> 
#> ── Postprocessing the data 
#>   1. prefix_barcodes
#> ✔ Postprocessing plan is ready
#> 
#> ── Saving the newly created ImmunData to disk 
#> ℹ Writing the receptor annotation data to [/tmp/RtmpPHpsgz/file1eef61c7a646/annotations.parquet]
#> ℹ Writing the metadata to [/tmp/RtmpPHpsgz/file1eef61c7a646/metadata.json]
#> ✔ ImmunData files saved to [/tmp/RtmpPHpsgz/file1eef61c7a646]
#> ℹ Reading ImmunData files from [/tmp/RtmpPHpsgz/file1eef61c7a646]
#> ✔ Loaded ImmunData with the receptor schema: [c("cdr3_aa", "v_call") and list()]
#> ℹ Reading ImmunData files from [/tmp/RtmpPHpsgz/file1eef61c7a646]
#> 
#> ── Summary 
#> ℹ Time elapsed: 2.32 secs
#> ✔ Loaded ImmunData with the receptor schema: [c("cdr3_aa", "v_call") and NULL]
#> ✔ Loaded ImmunData with [1902] chains
idata_rank <- annotate_clonality_rank(idata)
idata_prop <- annotate_clonality_prop(idata)
# }