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.

Examples¶

library("immundata")

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)

#> # A tibble: 2 × 4
#>   Therapy Response imd_strata_id strata_name
#> * <chr>   <chr>            <int> <chr>      
#> 1 CAR-T   PR                   1 Strata1    
#> 2 ICI     FR                   2 Strata2

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