Skip to contents

NeuroVec Class

Source: R/all_class.R, R/neurovec.R
NeuroVec-class.Rd

This S4 class represents a four-dimensional brain image, which is used to store and process time series neuroimaging data such as fMRI or 4D functional connectivity maps. The class extends the basic functionality of NeuroObj.

The NeuroVec class represents a vectorized form of neuroimaging data, supporting both in-memory and file-backed data modes. It provides efficient data storage and access methods and integrates with the spatial reference system provided by NeuroSpace.

Usage

NeuroVec(data, space = NULL, mask = NULL, label = "")

Arguments

data

The image data. This can be:

  • A matrix (voxels x time points)

  • A 4D array

  • A list of NeuroVol objects

If a list of NeuroVol objects is provided, the geometric space (NeuroSpace) will be inferred from the constituent volumes, which must all be identical.

space

An optional NeuroSpace object defining the spatial properties of the image. Not required if data is a list of NeuroVol objects.

mask

An optional logical array specifying which voxels to include. If provided, a SparseNeuroVec object will be created.

label

A character string providing a label for the NeuroVec object. Default is an empty string.

Value

A concrete instance of the NeuroVec class:

Details

NeuroVec objects are designed to handle 4D neuroimaging data, where the first three dimensions represent spatial coordinates, and the fourth dimension typically represents time or another series dimension. This structure is particularly useful for storing and analyzing functional MRI data, time series of brain states, or multiple 3D volumes in a single object.

The function performs several operations:

  • If data is a list of NeuroVol objects, it combines them into a single 4D array.

  • It checks that the dimensions of data match the provided space.

  • Depending on whether a mask is provided, it creates either a DenseNeuroVec or a SparseNeuroVec object.

Slots

space

A NeuroSpace object defining the spatial properties of the image.

label

A character string providing a label for the NeuroVec object.

Methods

Methods specific to NeuroVec objects may include operations for time series analysis, 4D data manipulation, and extraction of 3D volumes or time courses.

Usage

To create a NeuroVec object, use the constructor function NeuroVec(). This function should handle the appropriate initialization of the 4D data structure and associated spatial information.

See also

NeuroObj-class for the parent class. DenseNeuroVec-class and SparseNeuroVec-class for specific implementations.

NeuroSpace for spatial information, sub_vector for subsetting routines, and index_to_coord for coordinate conversion. DenseNeuroVec-class, SparseNeuroVec-class for the specific NeuroVec types. NeuroVol-class for 3D volumetric data.

Examples


# Load an example 4D brain image
example_4d_image <- read_vec(system.file("extdata", "global_mask_v4.nii", package = "neuroim2"))

# Create a NeuroVec object
neuro_vec <- NeuroVec(data = array(rnorm(64*64*32*10), dim = c(64, 64, 32, 10)),
                      space = NeuroSpace(dim = c(64, 64, 32,10),
                      origin = c(0, 0, 0),
                      spacing = c(3, 3, 4)))


dim(neuro_vec)
#> [1] 64 64 32 10

# Extract a single 3D volume (e.g., the first time point)
first_volume <- neuro_vec[[1]]


# Load an example 4D brain image
example_file <- system.file("extdata", "global_mask_v4.nii", package = "neuroim2")
example_4d_image <- read_vec(example_file)

# Create a DenseNeuroVec object
dense_vec <- NeuroVec(data = example_4d_image@.Data,
                      space = space(example_4d_image))
print(dense_vec)
#> 
#> DenseNeuroVec (3.13 bytes MB)
#> 
#> - Spatial Info ---------------------------
#> | Dimensions    : 64 x 64 x 25 (4 timepoints)
#> | Total Voxels  : 102,400
#> | Spacing       : 3.5 x 3.5 x 3.7
#> 
#> - Properties ---------------------------
#> | Origin        : 112 x -108 x -46.2
#> | Orientation   : Right-to-Left Posterior-to-Anterior Inferior-to-Superior
#> 
#> - Statistics ---------------------------
#>     Mean +/- SD    : 0.288 +/- 0.453
#> 

# Create a SparseNeuroVec object with a mask
mask <- array(runif(prod(dim(example_4d_image)[1:3])) > 0.5,
              dim = dim(example_4d_image)[1:3])
sparse_vec <- NeuroVec(data = example_4d_image@.Data,
                       space = space(example_4d_image),
                       mask = mask)
print(sparse_vec)
#> 
#> SparseNeuroVec 
#> 
#> += Spatial Info ---------------------------
#> | Dimensions    : 64 x 64 x 25
#> | Time Points   : 4
#> | Spacing       : 3.5 x 3.5 x 3.7
#> | Origin        : 112 x -108 x -46.2
#> 
#> +- Sparse Info  ----------------------------
#> | Cardinality   : 51134
#> 
#> += Memory Usage --------------------------
#>   Size          : 2.56 MB
#>