Write Dataset to HDF5 — write_dataset • fmristore

Generic function for writing neuroimaging datasets to HDF5 format

Write a single NeuroVec object with clustering to HDF5

Write multiple NeuroVec objects with clustering to HDF5

Export an existing H5ParcellatedMultiScan object to a new HDF5 file

Export an existing H5NeuroVec object to a new HDF5 file

Export an existing H5NeuroVol object to a new HDF5 file

Write a LatentNeuroVec object to HDF5

Write a neuroim2::ClusteredNeuroVec object to HDF5 using fmristore's clustered format

Usage

write_dataset(x, ...)

# S4 method for class 'NeuroVec'
write_dataset(
  x,
  file,
  clusters,
  mask = NULL,
  summary = FALSE,
  summary_fun = mean,
  scan_name = "scan_001",
  compression = 4,
  ...
)

# S4 method for class 'list'
write_dataset(
  x,
  file,
  clusters,
  mask = NULL,
  summary = FALSE,
  summary_fun = mean,
  scan_names = NULL,
  compression = 4,
  ...
)

# S4 method for class 'H5ParcellatedMultiScan'
write_dataset(x, file, overwrite = FALSE, ...)

# S4 method for class 'H5NeuroVec'
write_dataset(x, file, overwrite = FALSE, ...)

# S4 method for class 'H5NeuroVol'
write_dataset(x, file, overwrite = FALSE, ...)

# S4 method for class 'LatentNeuroVec'
write_dataset(x, file, compression = 6, ...)

# S4 method for class 'ClusteredNeuroVec'
write_dataset(
  x,
  file,
  scan_name = "scan_001",
  as_multiscan = FALSE,
  compression = 4,
  ...
)

Arguments

x: A neuroim2::ClusteredNeuroVec object
...: Additional arguments passed to underlying write functions
file: Output HDF5 file path
clusters: A ClusteredNeuroVol object defining spatial clusters
mask: Optional LogicalNeuroVol mask (extracted from first element if not provided)
summary: Logical, whether to summarize data by clusters (default: FALSE)
summary_fun: Function to use for summarization (default: mean)
scan_name: Name for the scan (default: "scan_001")
compression: Compression level 0-9 (default: 4)
scan_names: Character vector of scan names (auto-generated if not provided)
overwrite: Logical, whether to overwrite existing file (default: FALSE)
as_multiscan: Logical, whether to create a multi-scan container (default: FALSE)

Value

Invisible NULL or file path, depending on the method

Invisible NULL

Invisible file path

Invisible NULL

An H5ParcellatedScanSummary object (if as_multiscan=FALSE) or H5ParcellatedMultiScan object (if as_multiscan=TRUE)

Details

This method converts a neuroim2::ClusteredNeuroVec to fmristore's HDF5 format. The ClusteredNeuroVec stores time series data per cluster (T x K matrix), which is written as summary data in the HDF5 file.

By default (as_multiscan=FALSE), creates a single scan file and returns an H5ParcellatedScanSummary object. When as_multiscan=TRUE, creates a multi-scan container with one scan and returns an H5ParcellatedMultiScan object.

Examples

if (FALSE) { # \dontrun{
# Write full voxel-level data
write_dataset(nvec, file = "output.h5", clusters = cvol)

# Write summarized data (mean per cluster)
write_dataset(nvec, file = "output_summary.h5", clusters = cvol, summary = TRUE)

# Use median for summarization
write_dataset(nvec,
  file = "output_median.h5", clusters = cvol,
  summary = TRUE, summary_fun = median
)
} # }

if (FALSE) { # \dontrun{
# Write multiple scans
scans <- list(nvec1, nvec2, nvec3)
write_dataset(scans, file = "multi_scan.h5", clusters = cvol)

# With custom names and summary
write_dataset(scans,
  file = "multi_summary.h5", clusters = cvol,
  summary = TRUE, scan_names = c("rest", "task1", "task2")
)
} # }

if (FALSE) { # \dontrun{
# Export existing H5 object to new file
h5_obj <- H5ParcellatedMultiScan("existing.h5")
write_dataset(h5_obj, file = "copy.h5")
} # }

if (FALSE) { # \dontrun{
# Write latent representation
write_dataset(latent_nvec, file = "latent.h5")
} # }

if (FALSE) { # \dontrun{
# Assuming you have a ClusteredNeuroVec object from neuroim2
# cnvec <- neuroim2::ClusteredNeuroVec(...)

# Default: create single scan file
h5_scan <- write_dataset(cnvec, file = "single_scan.h5")

# Create multi-scan container
h5_multi <- write_dataset(cnvec, file = "multi_scan.h5", as_multiscan = TRUE)
} # }