LatentNeuroVec Class

A class that represents a 4-dimensional neuroimaging array using a latent space decomposition. It stores the data as a set of basis functions (dictionary) and a corresponding set of loadings (coefficients), enabling efficient representation and manipulation of high-dimensional data.

The LatentNeuroVec class provides a memory-efficient representation of neuroimaging data in a latent space (e.g., from PCA or ICA). It stores data as a product of basis vectors and loadings, allowing for efficient storage and computation of high-dimensional neuroimaging data.

Details

LatentNeuroVec inherits from NeuroVec-class and AbstractSparseNeuroVec-class. The original 4D data can be reconstructed as: $$data[v,t] = \sum_k \bigl(basis[t,k] \times loadings[v,k]\bigr) + offset[v]$$. (Note: `v` indexes voxels within the mask).

**Important Naming Note:** * In this R object: `@basis` stores temporal components (`nTime x k`), `@loadings` stores spatial components (`nVox x k`). * In the HDF5 spec: `/scans/.../embedding` stores temporal (`nTime x k`), `/basis/basis_matrix` stores spatial (`k x nVox`). The I/O functions handle the mapping and transposition.

This approach is especially useful for large datasets where storing the full 4D array is expensive.

Slots

basis

A Matrix object where each column represents a basis vector in the latent space.

loadings

A Matrix object (often sparse) containing the coefficients for each basis vector across the spatial dimensions.

offset

A numeric vector representing a constant offset term for each voxel or spatial location.

map

A IndexLookupVol object representing the mapping from basis to loadings.

label

A character string representing the label for the latent vector.

Inheritance

LatentNeuroVec inherits from:

• NeuroVec-class

• AbstractSparseNeuroVec-class

Implementation Details

The class implements a matrix factorization approach where the data is represented as: $$X = B \times L^T + c$$ where:

• B is the basis matrix (\(n \times k\))

• L is the loadings matrix (\(p \times k\))

• c is an optional offset vector

• n is the number of time points

• p is the number of voxels

• k is the number of components

See also

NeuroVec-class, AbstractSparseNeuroVec-class.

NeuroVec-class for the base 4D brain image class. AbstractSparseNeuroVec-class for the sparse representation framework.

Examples

if (FALSE) { # \dontrun{
if (requireNamespace("neuroim2", quietly = TRUE) &&
  requireNamespace("Matrix", quietly = TRUE) &&
  !is.null(fmristore:::create_minimal_LatentNeuroVec)) {
  # Create a LatentNeuroVec object using the helper
  # The helper creates a mask, basis, and loadings internally.
  # It uses new("LatentNeuroVec", ...) after creating constituent parts if not directly calling
  # a LatentNeuroVec constructor, or directly calls a constructor.
  # Our helper fmristore:::create_minimal_LatentNeuroVec returns a LatentNeuroVec.

  latent_vec <- NULL
  tryCatch(
    {
      latent_vec <- fmristore:::create_minimal_LatentNeuroVec(
        space_dims = c(5L, 5L, 3L),
        n_time = 8L,
        n_comp = 2L
      )

      print(latent_vec)

      # Access slots (example)
      # print(dim(latent_vec@basis))
      # print(dim(latent_vec@loadings))

      # Example of accessing data (reconstruction for a voxel would be more complex)
      # This class is more about representation; direct element access is usually via methods.
      # For example, a method might be `series(latent_vec, vox_indices = c(1,2,3))`
      # For a simple demonstration, we can show its dimensions:
      print(dim(latent_vec)) # from NeuroVec inheritance

    },
    error = function(e) {
      message("LatentNeuroVec example failed: ", e$message)
    })

} else {
  message("Skipping LatentNeuroVec example: neuroim2, Matrix, or helper not available.")
}
} # }