NeuroHyperVec-class: NeuroHyperVec Class

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

NeuroHyperVec Class

Description

A class representing a five-dimensional brain image, where the first three dimensions are spatial, the fourth dimension is typically time or trials, and the fifth dimension represents features within a trial.

The NeuroHyperVec class provides an efficient container for five-dimensional neuroimaging data where spatial dimensions are sparse. It is particularly suited for analyses involving multiple features per trial/timepoint, such as basis functions, spectral components, or multi-modal measurements.

Details

Five-Dimensional Sparse Neuroimaging Data Container

The class organizes data in a 5D structure:

• Dimensions 1-3: Spatial coordinates (x, y, z)

• Dimension 4: Trials or timepoints

• Dimension 5: Features or measurements

Data is stored internally as a three-dimensional array for efficiency:

• Dimensions 1: Features (dimension 5)

• Dimensions 2: Trials (dimension 4)

• Dimensions 3: Voxels (flattened spatial)

Key features:

• Memory-efficient sparse storage of spatial dimensions

• Fast access to feature vectors and time series

• Flexible indexing across all dimensions

• Maintains spatial relationships and metadata

Slots

mask

An object of class LogicalNeuroVol defining the sparse spatial domain of the brain image.

data

A 3D array with dimensions [features x trials x voxels] containing the neuroimaging data.

space

A NeuroSpace object representing the dimensions and voxel spacing of the neuroimaging data.

lookup_map

An integer vector for O(1) spatial index lookups.

mask

A LogicalNeuroVol object defining the spatial mask

data

A three-dimensional array with dimensions [features x trials x voxels] containing the data

space

A NeuroSpace object defining the 5D space

lookup_map

An integer vector for O(1) spatial index lookups.

See Also

NeuroVec, LogicalNeuroVol, NeuroSpace

Examples

## Not run: 
# Create a simple 5D dataset (10x10x10 spatial, 5 trials, 3 features)
dims <- c(10, 10, 10)
space <- NeuroSpace(c(dims, 5, 3))

# Create a sparse mask (20% of voxels)
mask_data <- array(runif(prod(dims)) < 0.2, dims)
mask <- LogicalNeuroVol(mask_data, NeuroSpace(dims))

# Generate random data for active voxels
n_voxels <- sum(mask_data)
data <- array(rnorm(3 * 5 * n_voxels), dim = c(3, 5, n_voxels))  # [features x trials x voxels]

# Create NeuroHyperVec object
hvec <- NeuroHyperVec(data, space, mask)

# Access operations
# Get data for specific voxel across all trials/features
series(hvec, 5, 5, 5)

# Extract a 3D volume for specific trial and feature
hvec[,,,2,1]

## End(Not run)

bbuchsbaum/neuroim2 documentation built on Jan. 2, 2025, 3:38 p.m.