Skip to contents

read_vec

Source: R/neurovec.R
read_vec.Rd

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

A character vector of one or more file paths to load. A 3D file is promoted to a 4D NeuroVec with a single time point (see Details). When multiple paths are supplied the result is always a NeuroVecSeq (which itself extends NeuroVec), regardless of whether the individual files are 3D, 4D, or a mix of both.

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

Value

The return type depends on how many files are supplied:

  • Single 3D file — a NeuroVec with dim(x)[4] == 1 (concrete class depends on mode: e.g. DenseNeuroVec for "normal", MappedNeuroVec for "mmap", BigNeuroVec for "bigvec", FileBackedNeuroVec for "filebacked").

  • Single 4D file — a NeuroVec of the same concrete class as above, with dim(x)[4] equal to the 4th dimension of the file (or length(indices) when indices is supplied).

  • Multiple files (any mix of 3D and 4D) — a NeuroVecSeq wrapping one NeuroVec per input file in the order given. Because NeuroVecSeq extends NeuroVec, it can be used wherever a NeuroVec is accepted, but its underlying storage is segmented rather than a single contiguous 4D array. For example, read_vec(c(vol, vec, vec, vol)) returns a 4-element NeuroVecSeq whose segments have time lengths c(1, T2, T3, 1).

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.

Which mode to use. "normal" is the default because it is the simplest thing that works, but it is the wrong default once the data stops being small. An R image always holds doubles, so a 56 MB int16 run becomes 236 MB in memory and a session-worth of runs will not fit. Two cheaper routes exist and both are usually faster, not just smaller:

* Pass a mask when the analysis only touches part of the brain – which is nearly every analysis. Only the in-mask voxels are read, and the result is a sparse NeuroVec that series and the searchlight iterators consume directly. * Use mode = "mmap" when voxels are visited in a scattered order, as in searchlight, ROI and connectivity work. The file is not read up front and pages are served on demand.

On an ordinary single run (64 x 64 x 36 x 200), extracting 5,000 scattered voxel time series measured 44 ms with mask=, 144 ms via "mmap" including the open, and 4.8 s by loading the whole image first. Reach for "normal" when you genuinely need every voxel of a small image in memory at once.

3D inputs: A path pointing at a 3D image is not rejected. It is promoted to a 4D NeuroVec whose fourth dimension has length 1, so the return type is always a NeuroVec, never a NeuroVol. If you want a true volume, use read_vol (or vec[[1]]).

Multiple files: When file_name has length > 1, each file is loaded independently and the results are wrapped with NeuroVecSeq. No data is copied or re-concatenated into a single dense 4D array; the returned NeuroVecSeq holds the constituent NeuroVecs in its @vecs slot and exposes them as a single logical time series. Time-point lookups (e.g. x[[i]], sub_vector(x, i), linear_access(x, i)) transparently walk across the segments. The per-file time lengths may differ (e.g. a 3D file contributes 1 time point, a 4D file contributes dim(file)[4]); all spatial dimensions must match.

Note

* Memory-mapping (.mmap mode) is not supported for gzipped files * The bigvec mode requires a mask to be specified * When loading multiple files, they must have compatible dimensions

Examples


# Load a single NIfTI file
img <- read_vec(system.file("extdata", "global_mask_v4.nii", package="neuroim2"))


# Memory-mapped loading for large files
big_img <- read_vec(system.file("extdata", "global_mask_v4.nii", package="neuroim2"), mode="mmap")
#> loading /home/runner/work/_temp/Library/neuroim2/extdata/global_mask_v4.nii as mmaped file 

# Load masked data for memory efficiency
mask <- as.logical(big_img[[1]])
masked_data <- read_vec(system.file("extdata", "global_mask_v4.nii", package="neuroim2"),
               mask=mask, mode="bigvec")
#> loading /home/runner/work/_temp/Library/neuroim2/extdata/global_mask_v4.nii as bigvec