Skip to contents

NeuroHyperVec Class

Source: R/all_class.R, R/neurohypervec.R
NeuroHyperVec-class.Rd

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.

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)
#>      [,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]      [,7]
#>  [1,]  0.0000000  0.000000  0.000000 0.5349385  0.0000000 0.0000000  0.000000
#>  [2,]  0.0000000  0.000000  0.000000 1.0049842  0.0000000 0.0000000  0.000000
#>  [3,]  0.0000000  0.000000 -1.123313 0.0000000  0.0000000 0.0000000  0.000000
#>  [4,]  0.0000000  0.000000  0.000000 0.0000000  0.0000000 1.6214254  0.000000
#>  [5,]  0.0000000  0.000000  0.000000 0.0000000  0.0000000 0.0000000  0.000000
#>  [6,]  0.0000000  0.000000  0.000000 0.0000000 -0.6933217 0.0000000  1.201458
#>  [7,]  0.0000000  0.000000  0.000000 0.0000000  0.0000000 0.3549994  0.000000
#>  [8,]  0.0000000 -0.513793  0.000000 0.0000000  0.0000000 0.0000000 -1.206527
#>  [9,]  0.0000000  0.000000  0.000000 0.0000000  0.0000000 0.9706734  0.000000
#> [10,] -0.6579816  0.000000  0.000000 0.0000000 -0.3453785 0.0000000  0.000000
#>             [,8]       [,9]     [,10]
#>  [1,]  0.0000000  0.0000000 0.0000000
#>  [2,]  0.0000000  0.0000000 0.0000000
#>  [3,] -0.4759719  0.0000000 0.0000000
#>  [4,]  0.2149874  0.0000000 0.0000000
#>  [5,]  0.0000000  0.0000000 0.0000000
#>  [6,]  0.0000000  0.0000000 0.0000000
#>  [7,]  0.0000000  0.0000000 0.0000000
#>  [8,]  0.0000000  0.0000000 0.0000000
#>  [9,]  0.0000000  0.0000000 0.0000000
#> [10,]  0.0000000 -0.9566662 0.6162621
#> 
#> , , 2
#> 
#>            [,1]       [,2]       [,3]       [,4] [,5]     [,6]     [,7]
#>  [1,] 0.0000000  0.0000000 0.03145748  0.0000000    0 0.000000 1.308736
#>  [2,] 0.0000000  0.0000000 0.00000000  0.3295068    0 0.000000 0.000000
#>  [3,] 0.0000000  0.0000000 0.00000000  0.0000000    0 0.000000 0.000000
#>  [4,] 0.0000000  0.0000000 0.00000000  0.0000000    0 1.714350 0.000000
#>  [5,] 0.0587178  0.0000000 0.00000000  0.0000000    0 0.000000 0.000000
#>  [6,] 0.0000000  0.0000000 0.00000000  0.0000000    0 0.000000 0.000000
#>  [7,] 0.0000000  0.0000000 0.00000000  0.0000000    0 0.000000 0.000000
#>  [8,] 0.0000000 -0.5961966 0.00000000 -0.6816598    0 0.000000 0.000000
#>  [9,] 0.0000000  0.0000000 0.00000000  0.1058725    0 1.018301 0.000000
#> [10,] 0.0000000  0.0000000 0.00000000  0.0000000    0 0.000000 0.000000
#>            [,8]       [,9]      [,10]
#>  [1,] 0.0000000  0.0000000  0.0000000
#>  [2,] 0.0000000  0.0000000  0.0000000
#>  [3,] 0.0000000  0.0000000  0.0000000
#>  [4,] 0.5978998  0.0000000  0.6807253
#>  [5,] 0.0000000 -1.0496493  0.0000000
#>  [6,] 0.0000000 -0.6240894  1.0489098
#>  [7,] 0.0000000  0.0000000  0.0000000
#>  [8,] 0.0000000  0.0000000  0.0000000
#>  [9,] 0.0000000  0.0000000  0.0000000
#> [10,] 0.0000000 -0.4059872 -0.2465186
#> 
#> , , 3
#> 
#>              [,1]       [,2]       [,3] [,4]        [,5]       [,6]       [,7]
#>  [1,]  0.00000000 -0.7446588  0.6103916    0 -0.09996982  0.1649302  0.4174158
#>  [2,]  0.00000000  0.9997293  0.0000000    0  0.00000000  0.0000000  0.0000000
#>  [3,]  0.04547398  0.0000000  0.0000000    0 -0.41284518  0.0000000  0.0000000
#>  [4,]  0.74521467  0.0000000  0.0000000    0  0.00000000  0.0000000 -0.2579218
#>  [5,] -0.14035696  0.0000000 -0.6945320    0  0.00000000  0.8140233  0.0000000
#>  [6,]  0.00000000  0.0000000  0.1112403    0  0.00000000  0.1315534  0.0000000
#>  [7,]  0.00000000  0.0000000  0.0000000    0  0.00000000  0.0000000  0.0000000
#>  [8,]  0.00000000  0.0000000  0.0000000    0  0.35457499 -0.2867912  0.0000000
#>  [9,]  0.00000000  0.0000000  0.0000000    0  0.00000000  0.0000000  0.0000000
#> [10,]  0.00000000  0.0000000  1.0791456    0 -1.03165843  0.0000000  0.7378348
#>            [,8]       [,9]     [,10]
#>  [1,]  1.854125  0.0000000 0.0000000
#>  [2,]  0.000000  0.0000000 0.0000000
#>  [3,]  0.000000 -0.1534271 0.7589502
#>  [4,]  0.000000  0.0000000 0.0000000
#>  [5,]  0.000000  0.0000000 0.0000000
#>  [6,]  0.000000  0.0000000 0.1848358
#>  [7,]  0.000000  0.0000000 0.0000000
#>  [8,]  0.000000  0.0000000 0.0000000
#>  [9,]  0.000000  0.0000000 0.0000000
#> [10,] -1.309630  0.0000000 0.0000000
#> 
#> , , 4
#> 
#>       [,1]      [,2]       [,3]      [,4] [,5]       [,6]       [,7]      [,8]
#>  [1,]    0 0.0000000  0.0000000  0.000000    0  0.0000000  0.5260694 0.9586351
#>  [2,]    0 0.0000000  0.0000000  1.084372    0  0.1434784  0.0000000 0.0000000
#>  [3,]    0 0.8656408 -0.1096728  0.000000    0  0.0000000  0.0000000 0.0000000
#>  [4,]    0 0.0000000  0.0000000  0.000000    0 -0.1748462  0.0000000 0.0000000
#>  [5,]    0 0.0000000  0.0000000  1.024529    0  0.0000000 -1.0263358 0.0000000
#>  [6,]    0 0.0000000  0.0000000  0.000000    0  0.0000000  0.0000000 0.0000000
#>  [7,]    0 0.0000000  0.0000000  0.000000    0  0.0000000  0.0000000 0.0000000
#>  [8,]    0 0.0000000  0.0000000 -1.171093    0  0.0000000 -0.4947991 0.0000000
#>  [9,]    0 0.0000000  0.0000000  0.000000    0 -0.3061282  0.0000000 0.0000000
#> [10,]    0 0.0000000  0.0000000  0.000000    0  0.0000000 -1.0539359 0.0000000
#>             [,9]     [,10]
#>  [1,] -1.9305186  0.000000
#>  [2,]  0.0000000  0.000000
#>  [3,]  0.0000000 -0.963248
#>  [4,]  0.0000000  0.000000
#>  [5,]  0.4876503  0.000000
#>  [6,]  0.0000000  0.000000
#>  [7,]  0.0000000  0.000000
#>  [8,]  0.0000000  0.000000
#>  [9,]  0.5446177  0.000000
#> [10,]  0.0000000  0.000000
#> 
#> , , 5
#> 
#>             [,1]       [,2]     [,3]       [,4]      [,5]      [,6]      [,7]
#>  [1,] -0.3821127  0.8118455 0.000000  0.0000000 0.0000000 0.0000000 -1.068863
#>  [2,]  0.0000000  0.0000000 0.000000 -0.0321003 0.0000000 1.6316141  0.000000
#>  [3,]  0.0000000  0.0000000 0.000000  0.0000000 0.0000000 0.0000000  0.000000
#>  [4,]  0.0000000  0.0000000 0.000000  0.0000000 0.3905356 0.0000000  0.358685
#>  [5,]  0.0000000  0.0000000 0.000000  0.0000000 0.0000000 0.4700417  0.000000
#>  [6,] -0.6379294  0.0000000 1.661025  0.0000000 0.0000000 0.0000000  0.000000
#>  [7,]  0.0000000  0.0000000 0.720946  0.0000000 0.0000000 0.0000000  1.065649
#>  [8,] -0.2114513  0.0000000 0.000000  0.0000000 0.3882449 0.0000000  0.000000
#>  [9,]  0.4438444  0.0000000 0.000000  0.0000000 1.3350121 0.0000000  0.000000
#> [10,] -1.6066178 -1.6522958 0.000000  0.3568791 0.0000000 0.0000000  0.000000
#>              [,8] [,9]    [,10]
#>  [1,]  0.00000000    0 0.000000
#>  [2,] -0.05454949    0 0.000000
#>  [3,]  0.00000000    0 0.000000
#>  [4,]  0.00000000    0 0.000000
#>  [5,]  0.00000000    0 0.000000
#>  [6,]  0.00000000    0 0.000000
#>  [7,]  0.00000000    0 0.000000
#>  [8,] -0.12522569    0 1.018399
#>  [9,]  0.00000000    0 0.000000
#> [10,]  0.00000000    0 0.000000
#> 
#> , , 6
#> 
#>              [,1]       [,2]       [,3]      [,4]       [,5]       [,6]
#>  [1,] -0.08306493  0.0000000 0.00000000  0.000000  0.0000000  0.0000000
#>  [2,]  0.00000000 -0.3201147 0.50155656  0.000000 -1.4050790 -0.2195178
#>  [3,]  0.00000000  0.0000000 0.00000000  0.000000  0.0000000  0.0000000
#>  [4,] -1.03958291  0.0000000 0.00000000  0.000000  0.0000000  0.0000000
#>  [5,]  0.00000000  0.0000000 1.20225714 -1.668766  0.0000000  0.1134634
#>  [6,]  0.00000000  0.0000000 0.00000000  0.000000  0.0000000  0.5851992
#>  [7,]  0.00000000  0.0000000 0.00000000  0.000000  0.0000000  0.0000000
#>  [8,]  0.00000000  0.0000000 0.00000000  0.000000  0.4520231  0.0000000
#>  [9,]  0.00000000  0.3287366 0.05721514  0.000000  0.0000000  0.0000000
#> [10,]  0.00000000  0.5732274 0.00000000  0.000000  0.0000000  0.0000000
#>             [,7]       [,8]       [,9]      [,10]
#>  [1,] -1.2132680  0.0000000  0.0000000  0.0000000
#>  [2,]  0.0000000  0.0000000  0.0000000 -0.3609611
#>  [3,]  0.0000000  0.0000000  1.4097688  0.0000000
#>  [4,]  0.0000000  0.0000000  0.0000000  0.0000000
#>  [5,]  0.0000000  0.1110673  0.0000000  0.0000000
#>  [6,] -0.2676124  0.0000000  0.0000000  0.0000000
#>  [7,]  0.1096976 -0.3283657 -0.9234519  0.0000000
#>  [8,] -0.2585718  0.0000000  0.0000000  0.0000000
#>  [9,]  0.0000000  0.0000000  0.0000000  0.0000000
#> [10,]  0.0000000  0.0000000  0.0000000 -0.8305518
#> 
#> , , 7
#> 
#>           [,1]       [,2]      [,3]     [,4]        [,5]      [,6]        [,7]
#>  [1,] 0.000000  0.0000000 0.0000000 0.000000  0.00000000 0.0000000  0.00000000
#>  [2,] 0.000000  0.0000000 0.0000000 0.000000  0.00000000 0.0000000  0.00000000
#>  [3,] 0.000000  0.0000000 0.0000000 0.000000  0.00000000 0.0000000  0.00000000
#>  [4,] 1.176147  0.7218642 0.0000000 0.000000  0.00000000 0.0000000  0.00000000
#>  [5,] 0.000000  0.9586053 0.0000000 0.000000 -0.51705052 0.0000000  0.00000000
#>  [6,] 0.000000 -0.4887232 0.0000000 1.202521  0.00000000 0.0000000  0.00000000
#>  [7,] 0.000000  0.0000000 0.7388022 0.000000 -0.04592876 0.0000000  0.00000000
#>  [8,] 0.000000  0.0000000 0.0000000 0.000000  0.55073245 0.1715847 -0.02499147
#>  [9,] 0.000000  0.0000000 0.0000000 0.000000  0.00000000 1.6162198  0.00000000
#> [10,] 0.000000  0.0000000 0.0000000 0.000000  0.00000000 1.8203664  0.00000000
#>            [,8]       [,9]      [,10]
#>  [1,] 0.0000000  0.0000000 0.00000000
#>  [2,] 0.0000000 -0.4096945 0.00000000
#>  [3,] 0.0000000  1.1885083 0.00000000
#>  [4,] 0.0000000  0.0000000 0.58819617
#>  [5,] 0.0000000  0.0000000 0.00000000
#>  [6,] 0.7765287  0.0000000 0.00000000
#>  [7,] 0.4480127  0.0000000 0.00000000
#>  [8,] 0.0000000  0.0000000 0.00000000
#>  [9,] 0.0000000  0.4289676 0.25097796
#> [10,] 0.5749927  0.0000000 0.01721866
#> 
#> , , 8
#> 
#>             [,1]      [,2]      [,3]       [,4] [,5]     [,6]       [,7]
#>  [1,]  0.0000000 0.0000000 0.0000000  0.0000000    0 0.000000  0.0000000
#>  [2,]  0.0000000 0.0000000 0.0000000  0.0000000    0 0.000000  0.0000000
#>  [3,]  0.0000000 0.0000000 0.0000000  0.0000000    0 0.000000  0.0000000
#>  [4,]  0.0000000 0.0000000 0.0000000  0.0000000    0 0.000000  0.0000000
#>  [5,]  0.0000000 0.0000000 0.0000000  0.0000000    0 0.000000  0.0000000
#>  [6,]  0.0000000 0.0000000 0.0000000  0.6073314    0 0.000000  0.0000000
#>  [7,]  0.0000000 0.0000000 0.0000000  1.7246216    0 0.000000 -0.6704145
#>  [8,]  0.0000000 0.0000000 0.0000000 -0.2957636    0 2.160015  0.0000000
#>  [9,] -0.2376466 0.7007865 1.2312488  0.0000000    0 0.000000  0.1031398
#> [10,]  0.0000000 0.0000000 0.1373712 -1.0121977    0 0.000000  0.0000000
#>           [,8]       [,9]       [,10]
#>  [1,] 0.000000  0.0000000  0.00000000
#>  [2,] 0.000000  0.0000000 -0.53864414
#>  [3,] 0.000000  0.0000000  0.00000000
#>  [4,] 0.000000 -0.4851712  0.00000000
#>  [5,] 0.000000 -0.2063889  0.00000000
#>  [6,] 1.765872 -0.1636628  0.00000000
#>  [7,] 0.000000  0.0000000  0.00000000
#>  [8,] 0.000000  0.8931493  0.00000000
#>  [9,] 0.000000  0.0000000  0.01955717
#> [10,] 0.000000  0.0000000  0.00000000
#> 
#> , , 9
#> 
#>              [,1]       [,2]       [,3]       [,4]     [,5] [,6]      [,7]
#>  [1,] -0.02439452  1.3036189  0.0000000  0.8670644 0.000000    0  0.000000
#>  [2,]  0.00000000  0.0000000  0.0000000  0.0000000 0.000000    0  0.000000
#>  [3,] -0.01555680  0.0000000 -0.6145938 -0.4997926 1.078727    0  0.000000
#>  [4,]  0.00000000  0.0000000  0.0000000  0.0000000 0.000000    0  0.000000
#>  [5,]  0.00000000 -0.4592893  0.0000000  0.0000000 0.000000    0  0.000000
#>  [6,]  0.00000000  0.0000000 -1.4695393  0.0000000 0.000000    0  0.000000
#>  [7,]  0.00000000  0.0000000  0.0000000  0.0000000 0.000000    0  0.000000
#>  [8,]  0.00000000  0.0000000  0.0000000  0.0000000 0.000000    0  0.000000
#>  [9,]  0.00000000  0.0000000  0.0000000  0.0000000 0.000000    0  0.000000
#> [10,]  0.09313177  0.0000000  0.0000000  0.0000000 0.000000    0 -0.399527
#>             [,8]       [,9]       [,10]
#>  [1,] -0.1797869  0.0000000  0.00000000
#>  [2,] -0.1925131  0.0000000 -0.04054727
#>  [3,]  0.0000000  0.0000000  0.00000000
#>  [4,]  0.0000000  0.0000000  0.00000000
#>  [5,]  0.0000000  0.0000000  0.00000000
#>  [6,]  0.0000000  0.0000000  0.00000000
#>  [7,]  0.0000000  0.0000000  0.00000000
#>  [8,]  0.0000000  0.0000000  0.00000000
#>  [9,]  0.0000000 -0.5604334  0.00000000
#> [10,]  0.0000000  0.0000000  0.00000000
#> 
#> , , 10
#> 
#>             [,1]     [,2]      [,3]       [,4]       [,5] [,6]        [,7]
#>  [1,]  0.0000000 0.000000 0.0000000 -0.2707616  0.0000000    0  0.00000000
#>  [2,]  0.6999196 0.000000 0.0000000 -1.1447072 -0.4808042    0 -0.65807866
#>  [3,]  0.0000000 0.000000 0.0000000  0.0000000  0.0580618    0  0.03494695
#>  [4,]  0.0000000 0.000000 0.0000000  0.0000000  0.0000000    0  0.58845464
#>  [5,]  0.0000000 0.000000 0.4317624  0.0000000  0.0000000    0  0.25359357
#>  [6,]  0.0000000 1.060264 0.1078577  0.0000000  0.0000000    0  0.00000000
#>  [7,]  0.0000000 0.000000 0.0000000  0.3566510 -0.2915486    0  0.00000000
#>  [8,]  0.0000000 0.000000 0.0000000 -0.9042032  0.0000000    0  0.00000000
#>  [9,]  0.0000000 0.000000 0.0000000  0.0000000  0.0000000    0  0.00000000
#> [10,] -0.3823253 0.000000 0.0000000  0.0000000  0.0000000    0  0.00000000
#>            [,8] [,9]      [,10]
#>  [1,] 0.0000000    0  0.0000000
#>  [2,] 0.0000000    0  0.0000000
#>  [3,] 0.0000000    0  0.0000000
#>  [4,] 0.0000000    0  0.0000000
#>  [5,] 0.0000000    0  0.0000000
#>  [6,] 0.6989964    0 -0.1348498
#>  [7,] 0.0000000    0  0.0000000
#>  [8,] 0.0000000    0  0.0000000
#>  [9,] 0.0000000    0  0.0000000
#> [10,] 0.0000000    0  0.0000000
#>