LatentNeuroVec-class: LatentNeuroVec Class
In bbuchsbaum/neuroim2: Data Structures and IO for Neuroimaging Data with an Emphasis on Functional Magnetic Resonance Imaging (FMRI)

LatentNeuroVec-class

R Documentation

LatentNeuroVec Class

Description

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), allowing for efficient representation and manipulation of high-dimensional neuroimaging data.

This function constructs a LatentNeuroVec object, which represents a latent space representation of neuroimaging data. It combines a basis, associated loadings, a NeuroSpace instance, a mask, and an optional offset.

Usage

LatentNeuroVec(basis, loadings, space, mask, offset = NULL)

Arguments

`basis`	A numeric n-by-k matrix containing the latent vectors forming the reduced space.
`loadings`	A numeric p-by-k matrix of p loadings.
`space`	A `NeuroSpace` instance defining the dimensions, spacing, origin, axes, and transformation of the neuroimaging space.
`mask`	A 3D logical array, 1D logical vector, or an instance of `LogicalNeuroVol` class representing the brain mask.
`offset`	An optional numeric 1-by-p offset vector. If not provided, it defaults to a zero vector.

Details

The LatentNeuroVec class provides a memory-efficient representation of 4D neuroimaging data by decomposing it into a set of basis functions and their corresponding loadings. This approach is particularly useful for large datasets where direct storage of the full 4D array would be prohibitively expensive.

The original 4D data can be reconstructed as: data[x,y,z,t] = sum(basis[t,i] * loadings[i,v]) + offset[v] where v is the voxel index corresponding to coordinates (x,y,z), and i indexes the basis functions.

The function performs several checks to ensure the consistency of the input data:

The 'space' argument must be a NeuroSpace object.
If 'mask' is not a LogicalNeuroVol, it's converted to one.
The number of rows in 'loadings' must match the number of non-zero entries in 'mask'.
The number of columns in 'basis' and 'loadings' must be the same.
The number of rows in 'basis' must match the 4th dimension of 'space'.

The function also converts 'basis' and 'loadings' to Matrix objects for efficient computation.

Value

A new LatentNeuroVec instance representing the latent neuroimaging vectors.

Slots

basis: A Matrix object where each column represents a basis vector in the latent space.
loadings: A Matrix object (typically 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.

Inheritance

LatentNeuroVec inherits from:

NeuroVec: Base class for 4D brain images
AbstractSparseNeuroVec: Provides sparse representation framework

Examples

## Not run: 
# Create a simple LatentNeuroVec object
basis <- Matrix(rnorm(100 * 10), nrow = 100, ncol = 10)
loadings <- Matrix(rnorm(10 * 1000), nrow = 10, ncol = 1000, sparse = TRUE)
offset <- rnorm(1000)

latent_vec <- new("LatentNeuroVec",
                  basis = basis,
                  loadings = loadings,
                  offset = offset,
                  space = NeuroSpace(dim = c(10, 10, 10)))  # Assuming 1000 voxels total

# Access the basis functions
basis_functions <- latent_vec@basis

# Reconstruct a single time point (this is a simplified example)
time_point_1 <- latent_vec@loadings %*% latent_vec@basis[1,] + latent_vec@offset

## End(Not run)

# Create a simple NeuroSpace
bspace <- NeuroSpace(c(2,2,2,10), c(1,1,1))

# Create a mask
mask <- array(rnorm(2*2*2) > -100, c(2,2,2))

# Create some random data
mat <- matrix(rnorm(sum(mask) * 10), 10, sum(mask))

# Perform PCA
pres <- prcomp(mat)

# Create a LatentNeuroVec
svec <- LatentNeuroVec(pres$x, pres$rotation, bspace, 
                       mask, offset = colMeans(mat))

# Compare with SparseNeuroVec
svec2 <- SparseNeuroVec(mat, bspace, mask)

# Check consistency
stopifnot(length(indices(svec)) == sum(mask))
stopifnot(all.equal(svec2[1:prod(dim(mask))], svec[1:prod(dim(mask))]))

bbuchsbaum/neuroim2 documentation built on Nov. 3, 2024, 9:31 a.m.