FLASH-3D: Fast 3D Superclustering for fMRI

Performs spatially-constrained clustering using Fast Low-rank Approximate Superclusters for Hemodynamics (FLASH-3D). This algorithm uses DCT-based temporal hashing and 3D jump-flood propagation for efficient clustering.

Usage

supervoxels_flash3d(
  vec,
  mask,
  K,
  lambda_s = 0.6,
  lambda_t = 1,
  lambda_g = 0,
  rounds = 2L,
  bits = 64L,
  dctM = 12L,
  vox_scale = NULL,
  barrier = NULL,
  verbose = FALSE
)

Arguments

vec: A NeuroVec instance supplying the 4D data to cluster
mask: A NeuroVol mask defining the voxels to include in the clustering result. If the mask contains numeric data, finite values strictly greater than zero define the included voxels. If the mask is a LogicalNeuroVol, then TRUE will define the set of included voxels.
K: The number of clusters to find
lambda_s: Finite non-negative target spatial weight (default 0.6). Multi-round optimization warms up from half this value and finishes at the requested value.
lambda_t: Finite non-negative temporal weight for Hamming distance of time-series hashes (default 1.0).
lambda_g: Finite non-negative boundary-field weight (default 0.0). If positive, barrier is required.
rounds: Number of outer rounds (seed→flood→recenter). Default 2, typically 2-3 is sufficient.
bits: Maximum temporal hash length (64 or 128). The effective number of non-redundant comparisons is at most choose(dctM, 2).
dctM: Number of low DCT coefficients to rank-hash (default 12, range 4-32)
vox_scale: Voxel size scaling for spatial distance, e.g., c(dx,dy,dz). Default c(1,1,1)
barrier: Optional non-negative finite 3D boundary field with the same geometry as the mask. A candidate site is penalized when its seed and the target voxel have different boundary-field values.
verbose: Logical indicating whether to print progress messages

Value

A list of class cluster_result with the following elements:

clusvol: An instance of type ClusteredNeuroVol
cluster: An integer vector of cluster assignments for each voxel in mask
centers: A matrix of cluster centers in feature space (K x T)
coord_centers: A matrix of spatial coordinates of cluster centers (K x 3)
K: The number of clusters
method: A character string indicating the method used ("FLASH-3D")

Details

FLASH-3D uses a novel approach combining:

DCT-based temporal feature hashing for fast similarity computation
Jump-flood algorithm for efficient spatial propagation
Blue-noise seeding for optimal initial cluster placement
Annealing of spatial weights to encourage compact clusters

The algorithm is particularly efficient for large-scale fMRI data, offering significant speed improvements over iterative methods while maintaining clustering quality.

Note

Consider using cluster4d with method = "flash3d" for a standardized interface across all clustering methods.

References

FLASH-3D algorithm for fast superclustering of fMRI data (2025)

Examples

if (FALSE) { # \dontrun{
  # Basic usage
  result <- supervoxels_flash3d(vec, mask, K = 100)
  
  # With custom parameters
  result <- supervoxels_flash3d(vec, mask, K = 100, 
                                lambda_s = 0.8, lambda_t = 1.2,
                                bits = 128, dctM = 16)
  
  # With barrier for anatomy-aware clustering
  barrier_vol <- create_anatomical_barrier(mask)
  result <- supervoxels_flash3d(vec, mask, K = 100,
                                lambda_g = 0.5, barrier = barrier_vol)
} # }