Constructor for H5ClusterExperiment Objects

Creates a new `H5ClusterExperiment` object, representing a collection of clustered neuroimaging runs sharing a common HDF5 file, mask, and cluster map.

This function handles opening the HDF5 file (if a path is provided), identifying available scans, and creating the appropriate run objects (`H5ClusterRun` or `H5ClusterRunSummary`) for each scan based on the available data within the HDF5 file structure (following the ClusteredTimeSeriesSpec).

Usage

H5ClusterExperiment(
  file,
  scan_names = NULL,
  mask = NULL,
  clusters = NULL,
  scan_metadata = NULL,
  cluster_metadata = NULL,
  summary_preference = NULL,
  keep_handle_open = TRUE
)

Arguments

file

Either a character string path to the HDF5 file or an open H5File object.

scan_names

(Optional) A character vector specifying which scans under `/scans/` to include in the experiment. If `NULL` (default), the constructor attempts to discover all available scan groups under `/scans/`.

mask

(Optional) A `LogicalNeuroVol` object for the brain mask. If `NULL`, the constructor attempts to load it from `/mask` in the HDF5 file.

clusters

(Optional) A `ClusteredNeuroVol` object for cluster assignments. If `NULL`, the constructor attempts to load it from `/cluster_map` and potentially `/voxel_coords` in the HDF5 file.

scan_metadata

(Optional) A list to override or supplement metadata read from the HDF5 file. If provided, its length should match the number of scans.

cluster_metadata

(Optional) A data.frame to override or supplement cluster metadata read from `/clusters/cluster_meta` in the HDF5 file.

summary_preference

(Optional) Character string controlling which run type to load. If NULL (default), the constructor reads the /scans@summary_only attribute to choose a default: "require" if summary_only=TRUE, "ignore" if summary_only=FALSE, otherwise "prefer". Explicit values can be "require" (only load summary runs, error if missing), "prefer" (load summary if available, else full), or "ignore" (load full runs only). This influences whether make_run_summary or make_run_full is called. *Note: This parameter requires careful implementation based on HDF5 content checks.*

keep_handle_open

(Logical) Only relevant if file_source is a path. If TRUE (default), the HDF5 file handle is kept open within the returned object. If FALSE, the handle is closed after reading metadata. *Note:* For most operations, the handle needs to remain open.

Value

A new H5ClusterExperiment object.

See also

Other H5Cluster: $,H5ClusterExperiment-method, H5ClusterExperiment-class, H5ClusterRun-class, H5ClusterRunSummary-class, H5ClusteredArray-class, [,H5ClusterRun,ANY,ANY,ANY-method, [,H5ClusterRun,ANY,missing,ANY-method, as.data.frame(), as.matrix(), close(), cluster_metadata,H5ClusterExperiment-method, clusters(), dim(), h5file,H5ClusteredArray-method, linear_access-methods, make_run_full(), make_run_summary(), mask(), matrix_concat(), n_scans,H5ClusterExperiment-method, scan_metadata,H5ClusterExperiment-method, scan_names,H5ClusterExperiment-method, series(), series_concat(), show,H5ClusterRun-method

Examples

if (FALSE) { # \dontrun{
# Create temporary HDF5 file with minimal experiment structure
temp_file <- tempfile(fileext = ".h5")
exp_file <- fmristore:::create_minimal_h5_for_H5ClusterExperiment(file_path = temp_file)

# Create H5ClusterExperiment object
experiment <- H5ClusterExperiment(exp_file)

# Access scan names
print(scan_names(experiment))

# Get number of scans
print(n_scans(experiment))

# Access runs
print(names(experiment@runs))

# Extract data for specific voxels (first 5 mask indices)
voxel_data <- series_concat(experiment, mask_idx = 1:5)
print(dim(voxel_data))

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