Skip to contents

Create an fMRI Dataset Object from LatentNeuroVec Files or Objects

Source: R/dataset_constructors.R
fmri_latent_dataset.Rd

This function creates an fMRI dataset object from LatentNeuroVec files (.lv.h5) or objects using the new backend architecture. LatentNeuroVec represents data in a compressed latent space using basis functions and spatial loadings.

Usage

fmri_latent_dataset(
  latent_files,
  mask_source = NULL,
  TR,
  run_length,
  event_table = data.frame(),
  base_path = ".",
  censor = NULL,
  preload = FALSE
)

Arguments

latent_files

A character vector of file paths to LatentNeuroVec HDF5 files (.lv.h5), or a list of LatentNeuroVec objects, or a pre-created latent_backend object.

mask_source

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

TR

The repetition time in seconds of the scan-to-scan interval.

run_length

A vector of one or more integers indicating the number of scans in each run.

event_table

A data.frame containing the event onsets and experimental variables. Default is an empty data.frame.

base_path

The file path to be prepended to relative file names. Default is "." (current directory).

censor

A binary vector indicating which scans to remove. Default is NULL.

preload

Read LatentNeuroVec objects eagerly rather than on first access. Default is FALSE.

Value

An fMRI dataset object of class c("fmri_file_dataset", "volumetric_dataset", "fmri_dataset", "list").

Details

This function uses the latent_backend to handle LatentNeuroVec data efficiently. LatentNeuroVec objects store fMRI data in a compressed format using:

  • Basis functions (temporal components)

  • Spatial loadings (voxel weights)

  • Optional offset terms

This is particularly efficient for data that can be well-represented by a lower-dimensional basis (e.g., from PCA, ICA, or dictionary learning).

CRITICAL: Data Access in Latent Space Unlike standard fMRI datasets that return voxel-wise data, this dataset returns latent scores (temporal basis components) rather than reconstructed voxel data. The data matrix dimensions are (time × components), not (time × voxels). This is because:

  • Time-series analyses should be performed in the efficient latent space

  • The latent scores capture temporal dynamics in the compressed representation

  • Reconstructing to full voxel space defeats the compression benefits

  • Most analysis workflows (GLM, connectivity, etc.) work directly with these temporal patterns

Use this dataset when you want to analyze temporal dynamics in the latent space. If you need full voxel reconstruction, use the reconstruction methods from fmristore directly.

See also

latent_backend, latent_dataset, fmri_h5_dataset

Examples

if (FALSE) { # \dontrun{
# Create an fMRI dataset from LatentNeuroVec HDF5 files
dset <- fmri_latent_dataset(
  latent_files = c("run1.lv.h5", "run2.lv.h5", "run3.lv.h5"),
  TR = 2,
  run_length = c(150, 150, 150)
)

# Create from pre-loaded LatentNeuroVec objects
lvec1 <- fmristore::read_vec("run1.lv.h5")
lvec2 <- fmristore::read_vec("run2.lv.h5")
dset <- fmri_latent_dataset(
  latent_files = list(lvec1, lvec2),
  TR = 2,
  run_length = c(100, 100)
)

# Create from a latent_backend
backend <- latent_backend(c("run1.lv.h5", "run2.lv.h5"))
dset <- fmri_latent_dataset(backend, TR = 2, run_length = c(100, 100))
} # }