read_vec: read_vec

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

read_vec

Description

Loads a neuroimaging volume from one or more files, with support for various input formats and memory management strategies.

Usage

read_vec(
  file_name,
  indices = NULL,
  mask = NULL,
  mode = c("normal", "mmap", "bigvec", "filebacked")
)

Arguments

file_name	The name(s) of the file(s) to load. If multiple files are specified, they are loaded and concatenated along the time dimension.
indices	The indices of the sub-volumes to load (e.g. if the file is 4-dimensional). Only supported in "normal" mode.
mask	A logical mask defining which spatial elements to load. Required for "bigvec" mode and optional for other modes.
mode	The IO mode which is one of: * "normal": Standard in-memory loading * "mmap": Memory-mapped access (more memory efficient) * "bigvec": Optimized for large datasets with masking * "filebacked": File-backed storage with on-demand loading

Details

This function supports multiple file formats: * .nii: Standard NIfTI format * .nii.gz: Compressed NIfTI (not supported in mmap mode)

Memory management modes: * "normal": Loads entire dataset into memory. Best for smaller datasets or when memory is not a constraint. * "mmap": Memory-maps the file, providing efficient access for large files without loading entirely into memory. Not available for compressed files. * "bigvec": Optimized for large datasets where only a subset of voxels are of interest. Requires a mask to specify which voxels to load. * "filebacked": Similar to mmap but with more flexible caching strategies.

Value

An NeuroVec object representing the loaded volume(s).

Note

* Memory-mapping (.mmap mode) is not supported for gzipped files * For .lv.h5 and .h5 files, the indices and mask parameters are ignored * The bigvec mode requires a mask to be specified * When loading multiple files, they must have compatible dimensions

Examples

## Not run: 
# Load a single NIfTI file
img <- read_vec("subject01.nii")

# Load multiple volumes and concatenate
imgs <- read_vec(c("run1.nii", "run2.nii"))

# Memory-mapped loading for large files
big_img <- read_vec("large_volume.nii", mode="mmap")

# Load masked data for memory efficiency
mask <- read_vol("brain_mask.nii")
masked_data <- read_vec("functional.nii", mask=mask, mode="bigvec")

## End(Not run)

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