Read, validate, and save clustering results

A clustering is useful only if its labels can be tied back to the mask, feature space, and physical geometry that produced them. cluster4d_result keeps those pieces together. Use its public fields and validate the object against the original inputs before interpretation or export.

What does a valid result look like?

fit <- cluster4d(
  syn$vec, syn$mask, n_clusters = 4,
  method = "slic", preserve_k = TRUE,
  max_iterations = 6, parallel = FALSE
)
receipt <- validate_cluster4d(fit, syn$vec, syn$mask)
receipt$summary
#> $n_clusters
#> [1] 4
#> 
#> $n_voxels
#> [1] 576
#> 
#> $cluster_size_range
#> [1] 132 155
#> 
#> $has_centers
#> [1] TRUE
#> 
#> $has_spatial_centers
#> [1] TRUE

The validation call independently checks the label schema, centers, physical centroids, mask ordering, and geometry. Calling it without vec and mask cannot certify all of those relationships.

How are labels related to centers?

Field	Meaning
labels	Contiguous positive IDs in included-mask voxel order
cluster	An identical compatibility alias of labels
label_ids	The label represented by each row of both center matrices
centers	Means in the original feature space; rows are labels
coord_centers	Mean physical coordinates in millimetres; rows are labels
actual_k	Number of final labels; may differ from a requested target when topology makes the target infeasible
clusvol	A neuroim2::ClusteredNeuroVol carrying labels and mask geometry

Never index a center matrix by an undocumented label ordering. The explicit label_ids mapping is the contract.

What should you notice in a slice?

One axial slice of the validated SLIC fit. Colours identify labels, not an ordering or effect magnitude. A slice is a visual screen, not proof of 3-D connectivity.

What to notice. The figure screens label coverage and gross spatial shape, but it cannot establish that each label has one connected component in 3-D. Colour numbers are arbitrary; compare partitions with defined metrics, not by matching hues.

Observed 26-neighbor component count for every final label.

label	voxels	components_26
1	134	1
2	155	1
3	155	1
4	132	1

The fitted result has one 26-neighbor component per label on this fixture. That statement comes from an explicit whole-volume traversal and hidden assertion, not from the middle slice. Use the connectivity definition declared by the method when reproducing this diagnostic.

What belongs in a saved receipt?

Save the fitted object together with the original mask identity and analysis metadata. At minimum retain method, parameters, actual_k, provenance, and the result of validate_cluster4d(). For comparison and export workflows, continue to Validate and compare clusterings and Visualize and export results.