rename_strata: Give biological strata readable labels

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

Give biological strata readable labels

Description

Use rename_strata() to replace automatic stratum labels with names that are clear in figures and result tables, such as "Control", "Treated", or "Tumour tissue".

Use this function after agg_strata() when labels such as "Strata1" do not describe the biological groups. The unit being changed is the stratum label. Stratum membership and the repertoires, receptors, cells, and chains remain unchanged.

The function returns a new ImmunData object. The original object is not changed.

Usage

rename_strata(
  idata,
  names,
  unnamed = c("error", "auto", "keep"),
  auto_prefix = "Strata"
)

Arguments

idata	An ImmunData object with strata already created by agg_strata().
names	A named character vector or a data frame. New labels matched to imd_strata_id. Supply either: a named character vector, such as c("1" = "Control", "2" = "Treated"); or a data frame with columns imd_strata_id and strata_name. Every new label must be non-empty and unique.
unnamed	A character string. What to do when names does not include every stratum. The default, "error", asks for a complete mapping. Use "auto" to generate labels for missing strata or "keep" to preserve their current labels.
auto_prefix	A non-empty character string. Prefix used to generate labels when unnamed = "auto". The default is "Strata".

Details

The names of a named character vector are the stratum IDs, not the current labels. Inspect idata$strata to find the ID for each biological group.

The mapping cannot contain unknown or repeated IDs, and the resulting labels must be unique across strata.

Value

A new ImmunData object with the requested labels in its ⁠$strata⁠ and ⁠$repertoires⁠ tables. All biological group assignments and repertoire summaries are preserved.

Storage details

The readable strata_name is stored in the repertoire and strata tables. The underlying chain annotations keep only imd_strata_id, so renaming a stratum does not rewrite or regroup chain-level data.

See Also

agg_strata(), agg_repertoires()

Examples

library(immundata)
library(dplyr)

options(immundata.verbose = FALSE)

# Create treatment strata for the sample repertoires in the test data
treatment_groups <- get_test_idata() |>
  agg_repertoires(c("Response", "Therapy")) |>
  agg_strata(schema = "Therapy")

# Replace automatic labels with names suitable for a figure
labeled_groups <- treatment_groups |>
  rename_strata(
    names = c("1" = "CAR-T arm", "2" = "ICI arm")
  )

labeled_groups$strata |>
  select(Therapy, imd_strata_id, strata_name) |>
  arrange(imd_strata_id)
# Expected result:
#   Therapy imd_strata_id strata_name
#   CAR-T               1 CAR-T arm
#   ICI                 2 ICI arm

# Only the labels changed. Each sample repertoire remains in the same
# treatment stratum.

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