read_image: read_image

In neuroim2: Data Structures for Brain Imaging Data

read_image

Description

Convenience wrapper that inspects the file header(s) and dispatches to the appropriate specialized reader: read_vol for a single 3D file, read_vec for 4D data or for any multi-file input, or read_hyper_vec for 5D data.

Usage

read_image(
  file_name,
  type = c("auto", "vol", "vec", "hyper"),
  index = 1,
  indices = NULL,
  mask = NULL,
  mode = c("normal", "mmap", "bigvec", "filebacked")
)

Arguments

file_name	Character vector of one or more file paths.
type	One of "auto", "vol", "vec", or "hyper" to override header-based dispatch.
index	Integer volume index. Used as the single-volume selector for read_vol (when dispatching to it) and, when indices is NULL, forwarded to read_vec as indices so you can pull out a subset of time points while still receiving a NeuroVec.
indices	Optional integer vector of sub-volume indices forwarded to read_vec. Takes precedence over index.
mask	Optional spatial mask passed through to the vector or hyper-vector readers. Ignored by read_vol.
mode	IO mode forwarded to read_vec; see that function for details. Ignored for 3D and 5D dispatch.

Details

Auto-dispatch (type = "auto") uses the following rules:

• length(file_name) > 1: always routed to read_vec, so the result is a NeuroVecSeq regardless of whether the individual files are 3D, 4D, or a mix. See read_vec for the return-type details.

• Single file with a 5th dimension > 1: routed to read_hyper_vec, returning a NeuroHyperVec.

• Single file with a 4th dimension > 1: routed to read_vec, returning a NeuroVec. If index is supplied (and indices is not), it is forwarded as indices so you can pull out a subset while still getting a NeuroVec back.

• Single effectively-3D file (either truly 3D or 4D with dim[4] == 1): routed to read_vol, returning a DenseNeuroVol.

Explicit type values bypass header inspection:

• type = "vol": requires a single file; always returns a DenseNeuroVol. The index argument picks the sub-volume when the file is 4D.

• type = "vec": forwards to read_vec. Multi-file input yields a NeuroVecSeq. A single 3D file is promoted to a NeuroVec with dim[4] == 1.

• type = "hyper": requires a single file; returns a NeuroHyperVec.

Value

The return type depends on dispatch:

• 3D dispatch (single effectively-3D file, or type = "vol"): a DenseNeuroVol.

• 4D dispatch (single 4D file, or type = "vec" with one file): a NeuroVec (concrete subclass depends on mode).

• Multi-file dispatch (length(file_name) > 1, or type = "vec" with multiple files): a NeuroVecSeq, which extends NeuroVec but stores each file as a distinct segment rather than concatenating into a single contiguous 4D array. Mixed 3D/4D inputs are allowed; each 3D file contributes one time point to the sequence.

• 5D dispatch (single 5D file, or type = "hyper"): a NeuroHyperVec.

See Also

read_vol, read_vec, read_hyper_vec

Examples

# 3D file -> DenseNeuroVol
vol <- read_image(system.file("extdata", "global_mask2.nii.gz", package = "neuroim2"))

# 4D file -> NeuroVec
vec <- read_image(system.file("extdata", "global_mask_v4.nii", package = "neuroim2"))

# Multiple files (any mix of 3D and 4D) -> NeuroVecSeq
fn <- system.file("extdata", "global_mask_v4.nii", package = "neuroim2")
seq_vec <- read_image(c(fn, fn))
class(seq_vec)  # "NeuroVecSeq"

neuroim2 documentation built on April 16, 2026, 5:07 p.m.