Skip to contents

Create a Latent Backend

Source: R/backends.R
latent_backend.Rd

Creates a storage backend for accessing latent space representations of fMRI data using LatentNeuroVec objects from the fmristore package. This backend provides efficient access to data stored in a compressed latent space format.

Usage

latent_backend(source, mask_source = NULL, preload = FALSE)

Arguments

source

A character vector of file paths to LatentNeuroVec HDF5 files (.lv.h5), or a list of LatentNeuroVec objects from the fmristore package.

mask_source

Optional mask source. If NULL, the mask will be extracted from the first LatentNeuroVec object.

preload

Logical indicating whether to preload all data into memory. Default is FALSE (lazy loading).

Value

A latent_backend object that implements the storage backend interface.

Details

The latent backend supports LatentNeuroVec objects which store fMRI data in a compressed latent space representation using basis functions and spatial loadings. This format is particularly efficient for data that can be well-represented by a lower-dimensional basis (e.g., from PCA, ICA, or dictionary learning).

LatentNeuroVec Structure:

  • basis: Temporal components (n_timepoints × k_components)

  • loadings: Spatial components (n_voxels × k_components)

  • offset: Optional per-voxel offset terms

  • Data is reconstructed as: data = basis %*% t(loadings) + offset

IMPORTANT: Data Access Behavior Unlike other backends that return voxel-wise data, the latent_backend returns latent scores (the basis/temporal components) rather than reconstructed voxel data. This is because:

  • Analyses are typically performed in the latent space for efficiency

  • The latent scores capture the temporal dynamics in the compressed representation

  • Reconstructing to ambient voxel space defeats the purpose of the compression

  • backend_get_data() returns a matrix of size (time × components), not (time × voxels)

  • backend_get_mask() returns a logical vector indicating active components, not spatial voxels

Supported Input Types:

  • File paths to .lv.h5 files (LatentNeuroVec HDF5 format)

  • Pre-loaded LatentNeuroVec objects

  • Mixed lists of files and objects

See also

h5_backend, nifti_backend, matrix_backend

Examples

if (FALSE) { # \dontrun{
# From LatentNeuroVec HDF5 files
backend <- latent_backend(
  source = c("run1.lv.h5", "run2.lv.h5", "run3.lv.h5")
)

# From pre-loaded LatentNeuroVec objects
lvec1 <- fmristore::read_vec("run1.lv.h5")
lvec2 <- fmristore::read_vec("run2.lv.h5")
backend <- latent_backend(source = list(lvec1, lvec2))

# Mixed sources
backend <- latent_backend(
  source = list(lvec1, "run2.lv.h5", "run3.lv.h5")
)
} # }