Read Immcantation immune repertoire tables in R
Immcantation is a toolkit for analysing adaptive immune receptor repertoires. read_immcantation() imports tables using its AIRR-C format in single-cell or bulk mode. This format uses AIRR column names; the legacy Change-O format uses different names. The bundled example uses a TSV representation of the AIRR fields.
Installation:
install.packages("pak")
pak::pak("immunomind/immunread")
How it works:
- The function returns an
ImmunDataobject with one row per retained chain after filtering out non-productive sequences. - In
mode = "sc", the function usesumi_countif present, otherwiseduplicate_count, thenconsensus_count, for chain selection. The chosen column keeps its original name and meaning. At least one of these count columns is required. - If you request paired receptors, the function selects the chain with the highest count at each required locus for each barcode. It keeps only cells with both required chains.
- In
mode = "bulk", the function usesduplicate_count, otherwiseumi_count, for abundance. With neither column, each input row represents one observed chain.
Existing AIRR names are unchanged: cell_id, locus, v_call, d_call, j_call, junction, junction_aa, and the count columns.
Key arguments:
path: your input file or a glob matching several files. Gzip-compressed files are supported.schema: receptor features using the output column names above. See the receptor schema guide for single-chain and paired-chain definitions.mode:"sc"for single-cell data or"bulk"for bulk data.column_profile: defaults to"standard". Set it to"full"to also keep source columns.output_folder: where to save the imported data. The example uses a temporary directory.
The example uses a small file bundled with immunread.
library(immunread)
path <- system.file("extdata", "immcantation", "single-cell.tsv.gz",package = "immunread", mustWork = TRUE)
schema <- c("v_call", "junction_aa")
idata <- read_immcantation(
path = path,
schema = schema,
output_folder = tempfile("immunread-"),
mode = "sc"
)
print(idata)