ImmunData {immundata} | R Documentation |
ImmunData: A Unified Structure for Immune Receptor Repertoire Data
Description
ImmunData
is an abstract R6 class for managing and transforming immune receptor repertoire data.
It supports flexible backends (e.g., Arrow, DuckDB, dbplyr) and lazy evaluation,
and provides tools for filtering, aggregation, and receptor-to-repertoire mapping.
Public fields
.receptors
A receptor-level table containing immune receptor features (e.g., CDR3, V/J gene, clonotype ID, counts). This table is typically aggregated and is used for quantitative analysis of immune repertoire signatures. It can be a local tibble, Arrow Table, DuckDB table, or any other
dplyr
-compatible backend (including lazy data sources)..annotations
A barcode-level table that links each barcode (i.e., cell ID) to a receptor in
.receptors
. It can also store cell-level metadata such as sample ID, donor, or tissue source. This table is not aggregated and typically contains one row per barcode.schema_receptor
A named list describing how to interpret receptor-level data. This includes the fields used for aggregation (e.g.,
CDR3
,V_gene
,J_gene
), and optionally unique identifiers for each receptor row. Used to ensure consistency across processing steps.schema_repertoire
A named list defining how barcodes or annotations should be grouped into repertoires. This may include sample-level metadata (e.g.,
sample_id
,donor_id
) used to define unique repertoires.
Active bindings
receptors
Accessor for the receptor-level table (
.receptors
).annotations
Accessor for the annotation-level table (
.annotations
).
Methods
Public methods
Method new()
Creates a new ImmunData
object.
This constructor expects receptor-level and barcode-level data,
along with a receptor schema defining aggregation and identity fields.
Usage
ImmunData$new(receptors, annotations, schema)
Arguments
receptors
A receptor-level dataset (e.g., grouped by CDR3/V/J).
annotations
A cell/barcode-level dataset mapping barcodes to receptor rows.
schema
A named list specifying the receptor schema (e.g., aggregate fields, ID columns).
Method build_repertoires()
Defines repertoires by concatenating selected annotation columns.
Usage
ImmunData$build_repertoires(schema = "repertoire_id", sep = "-")
Arguments
schema
A character vector of column names in
.annotations
used to define repertoire grouping.sep
A string separator used to concatenate multiple columns into a single repertoire ID.
Method print()
Prints class information for the ImmunData
object.
Usage
ImmunData$print()
Method filter_receptors()
Filters the receptor-level data using tidyverse filter syntax, and then updates the annotation table to include only linked barcodes.
Usage
ImmunData$filter_receptors(...)
Arguments
...
Filtering conditions applied to the receptor-level table.
Returns
A new ImmunData
object with filtered receptor and annotation tables.
Method filter_annotations()
Filters the annotation-level table using tidyverse filter syntax, and updates the receptor table to include only matching receptor entries.
Usage
ImmunData$filter_annotations(...)
Arguments
...
Filtering conditions applied to the annotations table.
Returns
A new ImmunData
object with filtered annotation and receptor tables.
Method filter_barcodes()
Filters the dataset by a set of barcodes (unique cell IDs). The resulting object contains only rows linked to those barcodes.
Usage
ImmunData$filter_barcodes(barcodes = c())
Arguments
barcodes
A character vector of barcodes to retain.
Returns
A new ImmunData
object filtered by barcode.
Method clone()
The objects of this class are cloneable with this method.
Usage
ImmunData$clone(deep = FALSE)
Arguments
deep
Whether to make a deep clone.