agg_strata: Group repertoires into biological strata

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

Group repertoires into biological strata

Description

Use agg_strata() to place sample repertoires into biological comparison groups, such as treatment arms, tissues, or disease groups.

Use this function after agg_repertoires() when several repertoires should be analysed as one group. A stratum contains every repertoire with the same value, or the same combination of values, in schema.

The unit being grouped is a whole repertoire. The function returns a new ImmunData object. The original object is not changed.

Usage

agg_strata(idata, schema, prefix = "Strata")

Arguments

idata	An ImmunData object with repertoires already defined. Use agg_repertoires() first if the object does not contain repertoires.
schema	A non-empty character vector. One or more repertoire-level columns that define a stratum. For example, use "Therapy" for treatment arms or c("Tissue", "Disease") for each tissue and disease combination. The columns must be present in idata$repertoires.
prefix	A non-empty character string. Prefix for the automatic stratum labels. The default, "Strata", produces labels such as "Strata1" and "Strata2". You can use rename_strata() to assign meaningful labels later instead.

Details

If schema contains several columns, a separate stratum is created for each observed combination. For example, c("Tissue", "Therapy") can define separate blood and tumour strata within each treatment arm.

Calling agg_strata() again replaces the existing strata with groups defined by the new schema.

Value

A new ImmunData object in which every repertoire belongs to one stratum. The ⁠$strata⁠ table lists the strata, their defining biological values, and their automatic labels. Repertoire definitions and summary statistics are preserved.

Identifiers and storage

imd_strata_id is an internal identifier and can change when strata are rebuilt. It is added to the repertoire table and to the underlying chain annotations. strata_name is stored only in the smaller repertoire and strata tables.

Calling agg_repertoires() again rebuilds the repertoires, so it removes the existing strata. Call agg_strata() again after redefining repertoires.

See Also

agg_repertoires(), rename_strata(), ImmunData

Examples

library(immundata)
library(dplyr)

options(immundata.verbose = FALSE)

# Define sample repertoires using the biological metadata in the test data
idata <- get_test_idata() |>
  agg_repertoires(c("Response", "Therapy"))

# Group the sample repertoires into treatment arms
treatment_groups <- idata |>
  agg_strata(schema = "Therapy")

treatment_groups$repertoires |>
  select(Therapy, Response, imd_strata_id, strata_name) |>
  arrange(imd_strata_id)
# Expected result:
#   Therapy Response imd_strata_id strata_name
#   CAR-T   PR                   1 Strata1
#   ICI     FR                   2 Strata2

# Each repertoire is now assigned to its treatment stratum. Any additional
# repertoire with the same Therapy value would receive the same stratum ID.

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