agg_receptors: Group AIRR sequence rows into receptors

In immundata: A Unified Data Layer for Large-Scale Single-Cell, Spatial and Bulk Immunomics

Group AIRR sequence rows into receptors

Description

agg_receptors() is a low-level function used during AIRR data ingestion. It decides which sequence rows represent the same biological receptor and adds package-standard identifiers and counts to the input table.

A receptor can be one chain or a pair of chains from the same cell. The schema argument defines which sequence features and loci make two receptors identical.

This function works with a prepared duckplyr table and returns a duckplyr table. It does not accept or return an ImmunData object. Most analysis workflows should provide the same arguments to read_repertoires(), which calls agg_receptors() during import.

Usage

agg_receptors(
  dataset,
  schema,
  barcode_col = NULL,
  count_col = NULL,
  locus_col = NULL,
  umi_col = NULL,
  verbose = getOption("immundata.verbose", TRUE)
)

Arguments

dataset	A duckplyr table containing AIRR sequence data, with one row per chain or bulk clonotype. It must contain the columns named in schema and in any of barcode_col, count_col, locus_col, and umi_col that are supplied.
schema	Definition of receptor identity. Supply either: A character vector naming the features that must match, such as c("v_call", "j_call", "junction_aa"). An object created by make_receptor_schema(). Its features define chain identity, while its optional chains select one locus or define a pair of loci. A schema can contain at most two chain entries. Use syntax such as c("IGH", "IGL|IGK") to accept either IGH-IGL or IGH-IGK pairs.
barcode_col	Name of the column containing cell barcodes. Supply this for single-cell data. umi_col is then also required, and count_col cannot be supplied. If imd_filename is present, identical barcode values from different source files are treated as different cells. The default is NULL.
count_col	Name of the column containing non-negative abundance values in bulk repertoire data. These values are copied to imd_n_chains. count_col cannot be used together with barcode_col. The default is NULL.
locus_col	Name of the column containing loci such as "TRA", "TRB", or "IGH". It is required when schema specifies one or more chains. The column is renamed to the standard name locus when necessary. The default is NULL.
umi_col	Name of the column containing per-chain UMI or read counts. It is required when barcode_col is supplied and is used to choose one chain when a cell contains several chains from the same locus. The default is NULL.
verbose	Whether to print information about the selected processing mode and loci. Defaults to getOption("immundata.verbose", TRUE).

Details

The receptor features are the columns that define the identity of one chain. Two chains with the same values in all feature columns receive the same receptor identity in a single-chain analysis. Common features include V gene, J gene, and CDR3 amino acid sequence.

The function supports three input modes:

• Uncounted sequence table: If neither barcode_col nor count_col is supplied, every input row is treated as one observed chain. A synthetic barcode is created for each row, and imd_n_chains is set to 1.

• Bulk repertoire: If count_col is supplied, every input row receives a synthetic barcode and its abundance is copied to imd_n_chains.

• Single-cell repertoire: If barcode_col is supplied, rows are grouped by cell. umi_col is required and imd_n_chains is set to 1 for every retained cell-chain observation.

When one chain is specified in schema, only that locus is retained. If a cell contains several chains from that locus, the row with the highest value in umi_col is retained. If the highest values are tied, the first row is retained.

When two chains are specified, only cells containing both requested loci are retained. The selected chains are paired by barcode, and both rows receive the same imd_receptor_id. Cells with incomplete pairs are excluded.

A relaxed pair such as c("IGH", "IGL|IGK") requires IGH and exactly one of the two alternative light-chain loci. Cells containing both IGL and IGK are excluded.

Numeric imd_receptor_id values identify receptors within the returned table. The particular number assigned to a receptor is not a biological identifier and may change when the data are aggregated again.

Value

A duckplyr table containing the retained input rows and these package-standard columns:

• imd_receptor_id: links rows that belong to the same receptor.

• imd_barcode: contains the input cell barcode, or a synthetic row-level barcode for uncounted and bulk data.

• imd_chain_id: identifies an individual retained chain row.

• imd_n_chains: contains 1 for uncounted and single-cell data, or the value from count_col for bulk data.

• imd_count: initialized to 0; receptor counts are calculated later by agg_repertoires().

See Also

read_repertoires(), make_receptor_schema(), agg_repertoires(), ImmunData

immundata documentation built on Aug. 26, 2026, 5:08 p.m.