NeuroHyperVec Class

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 class '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

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.

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)
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    0    0    0    0    0
#> [2,]    0    0    0    0    0
#> [3,]    0    0    0    0    0

# Extract a 3D volume for specific trial and feature
hvec[,,,2,1]
#> , , 1
#> 
#>              [,1]       [,2]      [,3]       [,4]       [,5]        [,6]
#>  [1,]  0.00000000  0.0000000 0.0000000  0.0000000  0.0000000  0.00000000
#>  [2,]  0.00000000  1.0404999 0.0000000  0.0000000  0.0000000  0.01325173
#>  [3,] -0.43979877 -0.8051761 0.0000000  0.0000000 -0.1987408 -0.48725179
#>  [4,]  0.00000000  0.0000000 0.0000000  0.0000000  0.0000000  0.89532866
#>  [5,]  0.00000000 -1.3777868 0.0000000 -0.2161112  0.0000000  0.00000000
#>  [6,]  0.00000000  0.0000000 0.0000000  0.0000000  0.0000000  0.00000000
#>  [7,] -0.05130566  0.0000000 0.7941954  0.0000000  0.0000000  0.00000000
#>  [8,]  0.00000000  0.3765108 0.0000000  0.7848214  0.0000000  0.00000000
#>  [9,]  0.00000000  0.0000000 0.0000000  0.0000000 -1.2441360  0.00000000
#> [10,]  0.00000000  0.0000000 0.0000000  0.0000000  0.0000000  0.00000000
#>            [,7]       [,8]       [,9]     [,10]
#>  [1,] 0.0000000  0.0000000  0.0000000 0.0000000
#>  [2,] 0.0000000  0.0000000  0.0000000 0.0000000
#>  [3,] 0.0000000  0.0000000  0.5128688 0.0000000
#>  [4,] 0.0000000  0.9320505  0.0000000 0.0000000
#>  [5,] 0.0000000  0.0000000  0.0000000 0.0000000
#>  [6,] 0.0000000 -0.2551572  0.0000000 0.0000000
#>  [7,] 0.0000000 -0.7349525  0.0000000 0.0000000
#>  [8,] 0.0000000  0.0000000  0.0000000 0.0000000
#>  [9,] 0.0000000  0.0000000 -1.3089513 0.0000000
#> [10,] 0.4598022  0.0000000  0.0000000 0.8306207
#> 
#> , , 2
#> 
#>             [,1]       [,2]     [,3]       [,4]       [,5]       [,6]
#>  [1,]  0.0000000  0.0000000 0.000000  0.6805044 -0.9324005  0.0000000
#>  [2,] -0.4663474  0.0000000 0.000000  0.0000000 -1.2635755 -0.7434976
#>  [3,]  0.0000000  0.0000000 0.000000 -0.9032888  0.0000000  0.0000000
#>  [4,]  0.0000000  0.0000000 0.000000  1.3668869  0.0000000  0.0000000
#>  [5,]  0.0000000  0.0000000 0.000000  0.0000000  0.0000000  0.0000000
#>  [6,]  0.0000000  0.0000000 0.000000  0.0000000 -0.9121381  0.0000000
#>  [7,]  0.0000000  0.0000000 1.259754  0.0000000  0.0000000  0.0000000
#>  [8,]  0.0000000  0.0000000 0.000000  0.0000000  0.0000000  0.0000000
#>  [9,]  0.0000000  0.0000000 0.000000  0.0000000  0.0000000  0.0000000
#> [10,]  0.0000000 -0.3176069 0.000000  0.0000000  0.0000000  0.0000000
#>             [,7]      [,8]        [,9]      [,10]
#>  [1,]  0.0000000 0.0000000  0.00000000  0.0000000
#>  [2,]  0.0000000 0.0000000 -1.29138195  0.0000000
#>  [3,] -0.4720966 0.0000000  0.00000000  0.0000000
#>  [4,]  0.0000000 0.9536053  0.00000000  0.0000000
#>  [5,]  0.0000000 0.0000000  0.00000000  1.1720330
#>  [6,]  0.0000000 0.0000000  0.00000000  0.0000000
#>  [7,]  0.0000000 0.0000000 -0.05976167  0.0000000
#>  [8,]  0.1344962 0.0000000  0.00000000  0.0000000
#>  [9,]  0.0000000 0.0000000  0.00000000  0.0000000
#> [10,]  0.0000000 0.0000000  0.00000000 -0.8664894
#> 
#> , , 3
#> 
#>       [,1]     [,2]       [,3]       [,4]      [,5]       [,6]       [,7]
#>  [1,]    0 1.514937  0.0000000  0.0000000 0.0000000 -0.5965181  0.0000000
#>  [2,]    0 0.000000  0.0000000  1.3640070 0.0000000  0.0000000  0.0000000
#>  [3,]    0 0.000000  0.0000000 -0.6870889 0.0000000  0.0000000  0.0000000
#>  [4,]    0 0.000000 -0.1728739  0.0000000 0.0000000  0.0000000  0.0000000
#>  [5,]    0 0.000000  0.0000000  0.0000000 0.0000000  0.4520542  0.0000000
#>  [6,]    0 0.000000  0.0000000  0.0000000 0.0000000  0.0000000  0.0000000
#>  [7,]    0 0.000000  0.0000000  0.0000000 0.1032508  0.0000000 -0.3305394
#>  [8,]    0 0.000000  0.0000000  0.0000000 0.0000000 -2.1435004  0.0000000
#>  [9,]    0 1.707345  0.0000000  0.0000000 0.0000000  0.0000000  0.2597764
#> [10,]    0 0.000000  0.0000000  0.0000000 0.0000000 -0.4552385  0.0000000
#>             [,8] [,9]     [,10]
#>  [1,]  0.0000000    0 0.8931473
#>  [2,]  0.0000000    0 0.0000000
#>  [3,]  0.0000000    0 0.0000000
#>  [4,]  0.2402700    0 0.0000000
#>  [5,] -0.2311434    0 0.0000000
#>  [6,]  0.0000000    0 0.0000000
#>  [7,]  0.0000000    0 0.0000000
#>  [8,]  0.0000000    0 0.0000000
#>  [9,]  0.0000000    0 0.0000000
#> [10,]  0.0000000    0 0.0000000
#> 
#> , , 4
#> 
#>             [,1]      [,2]      [,3]       [,4] [,5]       [,6]      [,7]
#>  [1,] -0.6674656  0.000000  0.000000 0.00000000    0  0.0000000  0.000000
#>  [2,]  0.0000000  0.000000 -0.291054 0.00000000    0  0.0000000 -1.121393
#>  [3,]  0.0000000  0.000000  0.000000 0.65784975    0  0.0000000  0.000000
#>  [4,]  0.0000000  0.000000  0.000000 0.00000000    0  0.0000000  0.000000
#>  [5,]  0.0000000  0.000000  0.000000 0.00000000    0 -1.0637954  0.000000
#>  [6,]  0.4706340  0.000000  0.000000 0.00000000    0  0.0000000  0.000000
#>  [7,]  0.0000000  0.000000  0.000000 0.00000000    0  0.0000000  0.000000
#>  [8,]  0.0000000  0.000000  0.000000 0.00000000    0  0.0000000  0.000000
#>  [9,]  0.0000000 -1.229384  0.000000 0.05777532    0  0.0000000  0.000000
#> [10,]  0.0000000  0.000000  0.000000 0.54955257    0 -0.8158955  0.000000
#>            [,8]       [,9]      [,10]
#>  [1,]  0.000000  0.0000000 -0.8667013
#>  [2,]  0.000000  0.0000000  0.0000000
#>  [3,]  0.000000  0.0000000  0.0000000
#>  [4,]  0.000000  0.0000000  0.0000000
#>  [5,] -0.698654  0.0000000 -0.6551059
#>  [6,]  0.000000 -2.4921894  0.0000000
#>  [7,]  0.000000 -0.4061575 -1.2311501
#>  [8,]  0.000000  0.0000000  0.0000000
#>  [9,]  0.000000  0.0000000  0.0000000
#> [10,]  0.000000  0.0000000  0.0000000
#> 
#> , , 5
#> 
#>              [,1]       [,2]        [,3]      [,4]       [,5]        [,6]
#>  [1,] -0.08861383  0.0000000  0.00000000 -0.364904  0.0000000 -0.25624884
#>  [2,]  0.00000000 -0.1037142 -0.23449229  0.000000 -1.6441044 -0.24142928
#>  [3,]  0.00000000 -1.0739085  0.00000000  0.000000  0.0000000  0.00000000
#>  [4,]  1.06805664  0.0000000  0.00000000  0.000000 -1.1106262  0.00000000
#>  [5,]  0.84077875  0.0000000  0.00000000  0.000000  0.0000000  0.00000000
#>  [6,]  0.17431688  0.0000000  0.76329670  0.000000  0.0000000 -1.17040117
#>  [7,]  0.00000000  0.0000000 -0.06401328  0.000000  0.0000000  1.78956557
#>  [8,]  0.00000000  0.0000000  0.00000000  0.000000  0.0000000  0.00000000
#>  [9,]  0.00000000  0.0000000  0.00000000  0.000000 -0.8548826  0.09829919
#> [10,]  0.00000000  0.0000000  0.00000000  0.000000  0.0000000  0.00000000
#>             [,7]      [,8]       [,9]     [,10]
#>  [1,]  0.0000000 1.7819000 -0.7904945  0.000000
#>  [2,] -0.6513149 0.4360502  0.0000000  0.000000
#>  [3,]  0.0000000 0.0000000  0.0000000  0.000000
#>  [4,]  0.0000000 0.0000000 -0.4564257 -0.840887
#>  [5,]  2.6080344 0.0000000  0.0000000  0.000000
#>  [6,]  0.0000000 0.0000000  0.0000000  0.000000
#>  [7,]  0.0000000 0.0000000  0.0000000  2.129556
#>  [8,]  0.0000000 0.0000000  0.0000000  0.000000
#>  [9,]  0.0000000 0.0000000  0.0000000  0.000000
#> [10,]  0.0000000 0.0000000  0.0000000  0.000000
#> 
#> , , 6
#> 
#>       [,1]     [,2]      [,3]       [,4] [,5]       [,6]       [,7]     [,8]
#>  [1,]    0 0.000000  0.000000  0.0000000    0  0.0000000  0.0000000 1.669816
#>  [2,]    0 0.000000  0.000000  0.0000000    0  0.0000000  2.0813972 2.177550
#>  [3,]    0 0.000000  0.000000  0.4537497    0 -0.3039783  0.0000000 0.000000
#>  [4,]    0 1.336522 -1.410724  0.0000000    0  0.0000000  0.0000000 0.000000
#>  [5,]    0 0.000000  0.000000  0.0000000    0 -1.7253602  0.0000000 0.000000
#>  [6,]    0 0.000000  0.000000 -1.1127899    0  0.0000000  1.0402502 0.000000
#>  [7,]    0 0.000000  0.000000  0.0000000    0  0.0000000  0.0000000 0.000000
#>  [8,]    0 0.000000  0.000000  0.0000000    0  0.0000000  0.0000000 0.000000
#>  [9,]    0 0.000000  0.000000 -0.6596931    0  0.0000000 -0.3449057 0.000000
#> [10,]    0 0.000000  0.000000  0.0000000    0 -0.4923074  0.0000000 0.000000
#>             [,9]     [,10]
#>  [1,]  0.0000000 0.0000000
#>  [2,]  0.2506986 0.0000000
#>  [3,]  0.0000000 0.0000000
#>  [4,]  0.0000000 0.7615471
#>  [5,]  0.0000000 0.0000000
#>  [6,] -0.7585719 0.0000000
#>  [7,]  0.0000000 0.0000000
#>  [8,]  0.0000000 0.0000000
#>  [9,]  0.0000000 0.0000000
#> [10,] -0.7283967 0.0000000
#> 
#> , , 7
#> 
#>             [,1]      [,2]       [,3]     [,4]       [,5]        [,6]
#>  [1,]  0.0000000  1.308012  0.1337980 0.000000 -0.2724824  0.00000000
#>  [2,] -0.3858064 -2.057172  0.0000000 0.000000  0.0000000  0.00000000
#>  [3,]  0.0000000  0.000000  0.0000000 0.321356  0.0000000  0.02616624
#>  [4,]  0.0000000  0.000000  0.0000000 0.000000  0.0000000  0.00000000
#>  [5,]  0.0000000  0.000000  0.0000000 0.000000  0.2526463  0.00000000
#>  [6,]  0.0000000  0.000000  0.0000000 0.000000  0.0000000 -0.02010863
#>  [7,]  0.1526855  0.000000 -0.6398130 0.000000  0.0000000  0.00000000
#>  [8,]  0.0000000  0.000000 -0.1355788 0.000000  0.0000000  0.00000000
#>  [9,] -1.1840398  0.000000  0.0000000 0.000000  1.3545779  0.00000000
#> [10,] -1.3959004  0.000000  0.0000000 0.000000 -0.1126705  0.00000000
#>             [,7]       [,8] [,9]     [,10]
#>  [1,]  0.0000000  0.0000000    0 0.0000000
#>  [2,] -0.1985515  0.0000000    0 0.0000000
#>  [3,]  0.0000000 -0.3815563    0 0.0000000
#>  [4,]  0.0000000  0.0000000    0 0.0000000
#>  [5,]  0.4683365  0.0000000    0 0.0000000
#>  [6,]  0.0000000  0.0000000    0 0.0000000
#>  [7,]  0.0000000  0.0000000    0 0.0000000
#>  [8,]  0.5813904  0.0000000    0 0.0000000
#>  [9,]  0.0000000 -2.3212255    0 0.4848574
#> [10,]  0.0000000  0.0000000    0 0.0000000
#> 
#> , , 8
#> 
#>              [,1]       [,2]        [,3]      [,4]       [,5]       [,6]
#>  [1,]  0.00000000  0.0000000  0.17863233  0.000000  0.0000000  0.0000000
#>  [2,] -0.03408942  0.0000000  0.00000000  0.000000  0.0000000  0.0000000
#>  [3,]  0.00000000  0.7940213 -0.64883596  0.000000  1.4565120 -0.4409788
#>  [4,]  0.00000000  0.0000000  0.00000000  0.000000  0.0000000  0.0000000
#>  [5,] -0.72087320  0.0000000  0.00000000  0.000000  0.0000000  0.0000000
#>  [6,]  0.00000000  0.0000000  0.68971963 -1.386156  0.0000000 -0.1242290
#>  [7,]  0.00000000  0.0000000  0.00000000  0.000000  0.0000000 -0.7672668
#>  [8,]  0.00000000  0.0000000  0.00000000  0.000000  0.0000000  0.0000000
#>  [9,]  0.00000000  0.0000000  0.00000000  0.000000 -0.1987678  0.0000000
#> [10,]  0.00000000 -1.1355436  0.04084884  0.000000  0.0000000  0.0000000
#>              [,7]       [,8]       [,9]      [,10]
#>  [1,]  0.00000000  0.0000000  0.0000000  0.0000000
#>  [2,]  0.01342104  0.0000000  0.0000000  0.0000000
#>  [3,]  0.00000000  0.0000000  0.0000000 -0.2741878
#>  [4,]  0.00000000  0.0000000 -0.7256544  0.0000000
#>  [5,]  0.00000000  0.0000000  0.0000000  0.0000000
#>  [6,]  0.00000000  0.8460959  0.0000000  0.0000000
#>  [7,]  1.92134489  0.0000000  0.0000000  0.0000000
#>  [8,]  0.64996292 -0.6508212 -0.8920984  0.0000000
#>  [9,] -1.77673619  0.0000000  0.0000000  0.0000000
#> [10,]  0.00000000  0.0000000  0.0000000  0.0000000
#> 
#> , , 9
#> 
#>             [,1]       [,2]      [,3]      [,4]       [,5]       [,6]      [,7]
#>  [1,] -0.3552321  0.0000000 0.0000000 0.0000000  0.0000000  0.0000000 1.0525874
#>  [2,]  0.0000000  0.0000000 0.0000000 0.0000000  0.0000000  0.0000000 0.0000000
#>  [3,]  0.0000000  0.0000000 0.0000000 0.0000000  0.0000000  0.0000000 0.0000000
#>  [4,]  0.0000000  0.0000000 0.0000000 0.0000000  0.0000000  0.0000000 0.0000000
#>  [5,]  0.8124608  1.4614600 0.0000000 0.0000000  0.0000000  0.0000000 0.0000000
#>  [6,]  0.0000000 -1.0933854 0.0000000 0.0000000 -0.7483808  0.0000000 0.0000000
#>  [7,]  0.0000000  0.4646127 0.0000000 0.2318331  0.0000000  0.0000000 0.0000000
#>  [8,]  0.0000000  0.0000000 0.4656822 0.0000000 -2.3041337  0.0000000 0.0000000
#>  [9,]  0.0000000  0.0000000 0.0000000 0.0000000 -0.4509994  0.5737143 0.8619809
#> [10,]  0.0000000  0.0000000 0.0000000 0.0000000  0.0000000 -0.2378712 0.0000000
#>             [,8]        [,9]      [,10]
#>  [1,]  0.0000000 -0.64434413  0.0000000
#>  [2,]  0.0000000  0.00000000  0.0000000
#>  [3,]  0.0000000  0.05292059  0.0000000
#>  [4,]  0.0000000 -2.00773040  0.0000000
#>  [5,]  0.0000000  0.00000000 -0.3271793
#>  [6,]  0.0000000  0.00000000  0.0000000
#>  [7,] -1.8281137  0.00000000  0.0000000
#>  [8,] -0.4662601  0.00000000  0.0000000
#>  [9,]  0.0000000  0.00000000  0.0000000
#> [10,]  0.0000000 -1.07414617 -0.3788847
#> 
#> , , 10
#> 
#>           [,1]       [,2]      [,3]       [,4]      [,5]     [,6]       [,7]
#>  [1,] 1.006574  0.0000000  0.000000 -0.8098863 0.1783268  0.00000  0.0000000
#>  [2,] 0.000000  0.0000000  0.000000  0.0000000 0.0000000  0.00000  0.0000000
#>  [3,] 0.000000  0.0000000  0.000000  0.0000000 0.0000000  0.00000  0.0000000
#>  [4,] 0.000000  0.0000000  0.000000  0.0000000 0.0000000  0.00000  0.0000000
#>  [5,] 0.000000  0.0000000  0.000000  0.0000000 0.0000000  0.00000  0.0000000
#>  [6,] 0.000000  0.0000000  0.000000  0.0000000 0.0000000  0.00000  0.0000000
#>  [7,] 0.000000  0.0000000  0.000000 -1.3424599 0.0000000  0.00000  0.0000000
#>  [8,] 0.000000  0.0000000  0.000000 -0.4125947 0.0000000  0.00000  1.6801291
#>  [9,] 0.000000  0.0000000  0.000000  1.2021519 0.0000000 -1.02118  0.0000000
#> [10,] 1.059448 -0.9747293 -1.944061  0.0000000 0.0000000  0.00000 -0.4961598
#>             [,8]       [,9]      [,10]
#>  [1,]  0.0000000  0.0000000 0.00000000
#>  [2,]  0.0000000  0.0000000 0.00000000
#>  [3,]  0.0000000  0.0000000 0.07134881
#>  [4,]  0.0000000  0.0000000 0.00000000
#>  [5,]  0.0000000  1.2804792 0.00000000
#>  [6,]  0.0000000  0.6679445 0.00000000
#>  [7,] -0.6013051 -0.3746087 0.00000000
#>  [8,]  0.0000000  0.0000000 0.00000000
#>  [9,]  0.0000000 -2.5127248 0.00000000
#> [10,]  0.0000000  0.0000000 0.91343246
#>

Usage

Arguments

Details

Slots

See also

Examples