Convert NeuroVecSeq to HDF5 — neurovecseq_to

Writes a NeuroVecSeq object (sequence of multiple 4D neuroimaging scans) to an HDF5 file. Each scan is stored separately within the file, allowing for different time dimensions while maintaining the same spatial dimensions across all scans.

Usage

neurovecseq_to_h5(
  neurovecseq,
  file = NULL,
  scan_names = NULL,
  data_type = "FLOAT",
  chunk_dim = NULL,
  compression = 6,
  scan_metadata = NULL
)

Arguments

neurovecseq: A NeuroVecSeq object containing multiple NeuroVec objects
file: Path to the output HDF5 file. If NULL, uses a temporary file.
scan_names: Optional character vector of names for each scan. If NULL, uses "scan_1", "scan_2", etc.
data_type: Character string specifying the data type: "FLOAT" (default), "DOUBLE", or "INT"
chunk_dim: Numeric vector specifying chunk dimensions for HDF5 storage. If NULL, uses time-optimized chunking (small spatial chunks, full time dimension).
compression: Integer compression level 0-9. Default is 6.
scan_metadata: Optional named list where each element is a list of metadata for the corresponding scan. Names should match scan_names.

Value

The file path of the created HDF5 file

Details

The HDF5 file structure created is:

/ - Root group with attributes "rtype" = "NeuroVecSeq" and "n_scans"
/space/ - Group containing shared spatial information
/space/dim - Spatial dimensions (3D)
/space/origin - Spatial origin
/space/trans - Spatial transformation matrix
/scans/ - Group containing all scans
/scans/<scan_name>/ - Group for each scan with "n_time" attribute
/scans/<scan_name>/data - 4D data array for the scan
/scans/<scan_name>/metadata/ - Optional metadata group

Examples

if (FALSE) { # \dontrun{
# Create example NeuroVec objects with different time dimensions
vec1 <- NeuroVec(array(rnorm(10*10*5*20), dim=c(10,10,5,20)), 
                 NeuroSpace(c(10,10,5,20)))
vec2 <- NeuroVec(array(rnorm(10*10*5*30), dim=c(10,10,5,30)),
                 NeuroSpace(c(10,10,5,30)))

# Create NeuroVecSeq
nvs <- NeuroVecSeq(vec1, vec2)

# Convert to HDF5
h5_file <- neurovecseq_to_h5(nvs, 
                              scan_names = c("rest_run1", "task_run1"),
                              scan_metadata = list(
                                rest_run1 = list(TR = 2.0, task = "rest"),
                                task_run1 = list(TR = 2.0, task = "motor")
                              ))

# File can later be read back (functionality to be implemented)
unlink(h5_file)
} # }