read_immundata: Load a saved ImmunData from disk

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

Load a saved ImmunData from disk

Description

Reconstructs an ImmunData object from files previously saved to a directory by write_immundata() or the internal saving step of read_repertoires(). It reads the annotations.parquet file for the main data and metadata.json to retrieve the necessary receptor and repertoire schemas.

Usage

read_immundata(
  path,
  tag = NULL,
  version = NULL,
  prudence = "stingy",
  verbose = TRUE
)

Arguments

path	Character(1). Path to the directory containing the saved ImmunData files (annotations.parquet and metadata.json).
tag	Character(1) or NULL. Optional snapshot tag to load from ⁠path/snapshots/<tag>/vNNN⁠. When provided, path must point to the project/home folder.
version	Integer(1) or NULL. Optional snapshot version number to load within a tag (e.g. 1 means v001). If NULL, the latest version for the tag is loaded.
prudence	Character(1). Controls strictness of type inference when reading the Parquet file, passed to duckplyr::read_parquet_duckdb(). Default "stingy" likely implies stricter type checking or safer inference.
verbose	Logical(1). If TRUE (default), prints informative messages using cli during loading. Set to FALSE for quiet operation.

Details

This function expects a directory structure created by write_immundata(), containing at least:

• annotations.parquet: The main annotation data table.

• metadata.json: Contains package version, receptor/repertoire schema, current snapshot_id, lineage events, and provenance paths.

The loading process involves:

1. Checking that the specified path is a directory and contains the required annotations.parquet and metadata.json files.

2. Reading metadata.json using jsonlite::read_json().

3. Reading annotations.parquet using duckplyr::read_parquet_duckdb() with the specified prudence level.

4. Extracting the receptor_schema and repertoire_schema from the loaded metadata.

5. Instantiating a new ImmunData object using the loaded annotations data and the receptor_schema.

6. If a non-empty repertoire_schema was found in the metadata, it calls agg_repertoires() on the newly created object to recalculate and attach repertoire-level information based on that schema.

Value

A new ImmunData object reconstructed from the saved files. If repertoire information was saved, it will be recalculated and included.

See Also

write_immundata() for saving ImmunData objects, read_repertoires() for the primary data loading pipeline, ImmunData class, agg_repertoires() for repertoire definition.

Examples

## Not run: 
# Assume 'my_idata' is an ImmunData object created previously
# my_idata <- read_repertoires(...)

# Define a temporary directory for saving
save_dir <- tempfile("saved_immundata_")

# Save the ImmunData object
write_immundata(my_idata, save_dir)

# --- Later, in a new session or script ---

# Load the ImmunData object back from the directory
loaded_idata <- read_immundata(save_dir)

# Verify the loaded object
print(loaded_idata)
# compare_methods(my_idata$annotations, loaded_idata$annotations) # If available

# Clean up
unlink(save_dir, recursive = TRUE)

## End(Not run)

immundata documentation built on April 4, 2026, 9:09 a.m.