Load bulk sequencing immune repertoire data in AIRR-C format to immunarch in R
The AIRR Rearrangement format stores immune receptor sequences and annotations in TSV files. read_airr_bulk() imports bulk AIRR data with rearrangement sequences and their abundance.
The specification documents the TSV input structure and the meaning of each annotation field.
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. - The function uses
duplicate_countfor abundance when present, otherwiseumi_count. If neither is supplied, each input row represents one observed chain.
AIRR names such as v_call, d_call, j_call, junction, and junction_aa are unchanged. The count column also keeps its original name. Use these names in your receptor schema.
Quick start with immunread
Key arguments:
path: the input file or a glob matching several files.schema: receptor features using AIRR column names.column_profile: defaults to"standard". Set it to"full"to keep all source columns.output_folder: where to store the imported data. The example uses a temporary directory.
library(immunread)
path <- system.file(
"extdata", "airr", "2.0-bulk", "contigs.tsv.gz",
package = "immunread", mustWork = TRUE
)
schema <- c("v_call", "junction_aa")
idata <- read_airr_bulk(
path = path,
schema = schema,
output_folder = tempfile("immunread-")
)
print(idata)
Replace path with your own file or a glob such as "/path/to/bulk_airr/*.tsv". Choose a permanent output_folder when you want to keep the imported data.
Advanced: read_repertoires()
Use immundata::read_repertoires() directly when you want to choose the input columns and preprocessing yourself. This is also the reader used by immunread.
Key arguments:
path: your input file or glob, or"<manifest>"to read files listed in a manifest.schema: the receptor features and loci to analyse.count_col: the abundance column, such as"duplicate_count"or"umi_count". Choose the column that represents abundance in your data.preprocess: transformations applied before receptor construction.manifest: an optional table of file paths and sample information.repertoire_schema: columns that define your repertoires, such as patient or tissue.
This example uses the same bundled file and sets the column names explicitly.
library(immundata)
path <- system.file(
"extdata", "airr", "2.0-bulk", "contigs.tsv.gz",
package = "immunread", mustWork = TRUE
)
schema <- c("v_call", "junction_aa")
idata <- read_repertoires(
path = path,
schema = schema,
count_col = "duplicate_count",
preprocess = make_default_preprocessing("airr"),
rename_columns = NULL,
output_folder = tempfile("airr-")
)
print(idata)
To attach sample information, list your files in a manifest. Here, study_sample also defines the repertoire. For your own data, add columns such as patient, tissue, or treatment and choose the appropriate repertoire_schema.
manifest <- data.frame(file = path, study_sample = "example")
idata <- read_repertoires(
path = "<manifest>",
manifest = manifest,
manifest_file_col = "file",
schema = schema,
count_col = "duplicate_count",
preprocess = make_default_preprocessing("airr"),
rename_columns = NULL,
repertoire_schema = "study_sample",
output_folder = tempfile("airr-manifest-")
)
print(idata)