Process chain rows while reading repertoire files¶

Description¶

Use these functions to preprocess or postprocess rows of the input data before returning the final ImmunData object to the session. A couple of example use cases: keep productive receptor chains, remove technical columns, or make cell barcodes unique while importing repertoire files with read_repertoires().

The defaults provide steps for common AIRR or 10x inputs. Use an individual step when your files need only one operation or when you are building a custom preprocess or postprocess list.

Preprocessing changes chain rows before receptors are defined. Barcode prefixing changes the cell identifier after receptor and manifest information are combined. The input files and input table are not changed: every step returns a new duckplyr table.

Usage¶

make_default_preprocessing(format = c("default", "airr", "10x"))

make_default_postprocessing()

make_exclude_columns(cols = imd_drop_cols("airr"))

make_productive_filter(col_name = c("productive"), truthy = TRUE)

make_barcode_prefix(prefix_col = "Prefix")

Arguments¶

format A character string. One input format: “default”, “airr”, or “10x”. The default is “default”. This choice controls which technical columns are removed. It does not rename columns.

cols A character vector. Columns to remove. The default is imd_drop_cols(“airr”). Use character() to create a step that removes no columns.

col_name A character string. Column containing the productive-chain indicator. The default is “productive”.

truthy A vector. Values that mean the chain is productive. Values are compared as text. The default is TRUE; use a character vector when the source uses several representations, for example c(“TRUE”, “true”, “1”).

prefix_col A character vector. One or more candidate columns containing the text to place before each cell barcode. The first candidate present in the data is used. The default is “Prefix”.

Value¶

make_default_preprocessing() and make_default_postprocessing() return named lists of processing functions. The other functions return one processing function. Each processing function accepts a duckplyr table as its first argument, accepts unused arguments through …, and returns a new duckplyr table.

Choose processing steps¶

make_default_preprocessing() returns two steps. The first removes common technical columns. The second keeps rows whose productive value indicates a productive chain. If the productive column is absent, the filtering step gives a warning and keeps all rows.
make_default_postprocessing() returns one step that adds a sample-specific prefix to cell barcodes. If the prefix column is absent, the step gives a warning and leaves barcodes unchanged.
make_exclude_columns() creates one step that removes the columns in cols. Column names that are not present are ignored.
make_productive_filter() creates one step that keeps rows whose value in col_name matches any value in truthy.
make_barcode_prefix() creates one step that joins a prefix, such as “Tumor\_”, to the start of each imd_barcode value.

read_repertoires() applies functions in list order. You can therefore add, remove, or reorder steps in a custom list.

Input formats¶

For make_default_preprocessing(), format = “default” removes the union of the standard AIRR and 10x technical columns. Use format = “airr” or format = “10x” to remove only the columns expected for that format. All three defaults recognize common text representations of a productive value, including “TRUE”, “true”, “yes”, and “1”.

Examples¶

library("immundata")

library(immundata)
library(dplyr)

# Three 10x chain rows from two samples. One chain is non-productive.
chains <- duckplyr::duckdb_tibble(
  imd_barcode = c("AAAC-1", "AAAG-1", "AATT-1"),
  cdr3_aa = c("CASSA", "CASSB", "CASSC"),
  productive = c("TRUE", "FALSE", "TRUE"),
  full_length = c(TRUE, TRUE, TRUE),
  Prefix = c("Tumor_", "Tumor_", "Blood_")
)

# read_repertoires() performs these calls for you. They are shown here to
# make the effect of each list clear.
prepared <- Reduce(
  function(data, step) step(data),
  make_default_preprocessing("10x"),
  init = chains
)
prepared <- Reduce(
  function(data, step) step(data),
  make_default_postprocessing(),
  init = prepared
)

prepared |>
  collect() |>
  select(imd_barcode, cdr3_aa, productive)

#> # A tibble: 2 × 3
#>   imd_barcode  cdr3_aa productive
#> * <chr>        <chr>   <chr>     
#> 1 Tumor_AAAC-1 CASSA   TRUE      
#> 2 Blood_AATT-1 CASSC   TRUE

# Expected result:
#   imd_barcode  cdr3_aa productive
#   Tumor_AAAC-1 CASSA   TRUE
#   Blood_AATT-1 CASSC   TRUE

# The non-productive chain was removed, `full_length` was dropped, and the
# sample prefixes made the retained cell barcodes unique.