neuroim2 (version 0.8.5)

NeuroHyperVec-class: 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.

Usage

# S4 method for NeuroHyperVec,ANY,ANY,ANY
[(x, i, j, k, l, m, ..., drop = TRUE)

Arguments

x

The NeuroHyperVec object

i, j, k, l, m

Indices for each dimension

...

Additional arguments (not used)

drop

Whether to drop dimensions of length 1

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.

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

See Also

NeuroVec, LogicalNeuroVol, NeuroSpace

Examples

# 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]