Write a NeuroVec to an HDF5 file with NIfTI-like quaternions

Creates an HDF5 file following a NIfTI-like header layout, storing:

/header/dim => [4, X, Y, Z, nVols, 1,1,1]
/header/pixdim => [0.0, dx, dy, dz, ...] (Note: qfac stored in /header/qfac)
/header/quatern_b,c,d and qoffset_x,y,z
/header/qfac => Quaternion factor (+/-1)
/mask => 3D dataset [X, Y, Z] (0/1) at root level
/labels => array of label strings at root level
/data/<label> => 1D array (length = number of nonzero mask voxels) storing the sub-volume values

Usage

write_labeled_vec(
  vec,
  mask,
  labels,
  file,
  compression = 4,
  dtype = hdf5r::h5types$H5T_NATIVE_DOUBLE,
  chunk_size = 1024,
  header_values = list(),
  verbose = FALSE
)

Arguments

vec: A 4D NeuroVec with dimension [X,Y,Z,nVols].
mask: A LogicalNeuroVol of shape [X,Y,Z] (the same 3D shape as vec).
labels: A character vector of length nVols, labeling each 4D sub-volume.
file: Either a character path to the HDF5 file to create or an open H5File in write mode.
compression: Integer 0-9 for gzip level; default 4.
dtype: An HDF5 data type object (e.g., hdf5r::h5types$H5T_NATIVE_FLOAT). Default is hdf5r::h5types$H5T_NATIVE_DOUBLE.
chunk_size: If non-NULL, the chunk dimension for the 1D datasets. Default is 1024.
header_values: A named list of optional overrides for fields in the header (e.g., list(qform_code=1L, sform_code=2L)). Note that fields derived from `vec` or `mask` (like `dim`, `pixdim`, quaternion fields) cannot be overridden here.
verbose: Logical, whether to print verbose messages during processing.

Value

Invisibly returns the open H5File handle containing the written data. The caller should close this handle when finished.

Details

The 4x4 matrix in trans(space(vec)) is passed to matrixToQuatern, which returns a list containing:

quaternion = c(b, c, d) (the three imaginary parts)
qfac (+/-1 sign)

This function stores qfac in /header/qfac and sets /header/pixdim[0]=0. We also gather voxel spacing (dx,dy,dz) from spacing(space(vec)) and the origin from origin(space(vec)).

We store a subset of NIfTI-like header fields in the /header group. The user can supply header_values (a named list) to override or augment *some* additional fields (e.g., qform_code=1L). See implementation notes for which fields are protected.

Lifecycle Management

The HDF5 file is opened in write mode and the resulting handle is returned without being automatically closed. **It is the caller's responsibility to close this handle** (via h5file$close_all() or close()) when finished working with the file.

Examples

if (FALSE) { # \dontrun{
# Create a simple labeled neuroimaging dataset
vec <- fmristore:::create_minimal_DenseNeuroVec(dims = c(4, 4, 3, 5))

# Create mask with same spatial dimensions
mask <- fmristore:::create_minimal_LogicalNeuroVol(dims = c(4, 4, 3))

# Define labels for each volume
labels <- c("condition_A", "condition_B", "condition_C", "condition_D", "condition_E")

# Write to temporary HDF5 file
temp_file <- tempfile(fileext = ".h5")
h5_handle <- write_labeled_vec(vec, mask, labels, file = temp_file)

# Close the file handle returned by write_labeled_vec
h5_handle$close_all()

# Read it back
labeled_data <- read_labeled_vec(temp_file)
print(labeled_data@labels)

# Clean up
close(labeled_data)
unlink(temp_file)
} # }