Skip to contents

Write Clustering Results to HDF5

Source: R/write_cluster_result.R
write_cluster_result.Rd

A convenience function for writing clustering results (e.g., from supervoxels()) along with the original neuroimaging data to an HDF5 file. This function serves as a user-friendly interface to write_dataset.

Usage

write_cluster_result(
  cluster_result,
  neurovec,
  filename,
  scan_name = "scan_001",
  type = c("full", "summary"),
  cluster_metadata = NULL,
  overwrite = FALSE,
  compress = TRUE,
  verbose = TRUE,
  ...
)

Arguments

cluster_result

Either a ClusteredNeuroVol object or a list containing:

  • clusters: Numeric vector of cluster assignments for each voxel within the mask

  • mask: A LogicalNeuroVol defining which voxels were included in clustering

  • metadata: (Optional) Additional cluster information

neurovec

A NeuroVec object containing the 4D fMRI time series data

filename

Character string specifying the output HDF5 file path

scan_name

Character string naming this scan in the HDF5 file (default: "scan_001")

type

Character string, either "full" for voxel-level data or "summary" for cluster-averaged data

cluster_metadata

Optional data.frame containing metadata for each cluster. Should have a column named cluster_id matching the unique cluster IDs.

overwrite

Logical, whether to overwrite an existing file (default: FALSE)

compress

Logical or numeric. If logical: TRUE uses compression level 4, FALSE uses no compression. If numeric: specify compression level 0-9.

verbose

Logical, whether to print progress messages (default: TRUE)

...

Additional arguments passed to write_dataset

Value

Invisibly returns NULL. Called for its side effect of creating an HDF5 file.

Details

This function bridges clustering results from various sources (e.g., supervoxels(), custom clustering algorithms) with the fmristore HDF5 storage system. It automatically converts the clustering information into the required ClusteredNeuroVol format and delegates to write_dataset() for efficient HDF5 storage.

When type = "full", the complete voxel-level time series are stored organized by cluster. When type = "summary", only the cluster-averaged time series are stored, resulting in much smaller file sizes.

See also

write_dataset for the underlying implementation read_dataset for loading the saved data ClusteredNeuroVol for the cluster representation

Examples

if (FALSE) { # \dontrun{
# Example with clustering results from supervoxels()
clust_result <- supervoxels(brain_data, n_clusters = 100)

# Write full voxel-level data
write_cluster_result(
  cluster_result = clust_result,
  neurovec = my_4d_data,
  filename = "clustered_data.h5",
  type = "full"
)

# Write only cluster averages (more compact)
write_cluster_result(
  cluster_result = clust_result,
  neurovec = my_4d_data,
  filename = "clustered_summary.h5",
  type = "summary",
  compress = 6  # Higher compression
)

# With cluster metadata
cluster_info <- data.frame(
  cluster_id = 1:100,
  region = rep(c("frontal", "parietal", "temporal", "occipital"), 25),
  size = sapply(1:100, function(i) sum(clust_result$clusters == i))
)

write_cluster_result(
  cluster_result = clust_result,
  neurovec = my_4d_data,
  filename = "clustered_with_metadata.h5",
  cluster_metadata = cluster_info,
  type = "full"
)
} # }