Choose the right neurocluster interface

neurocluster has one main workflow and several specialist surfaces. If you are starting an analysis, use cluster4d(): it gives every method the same input checks and the same result contract. Move to a direct method function only when you need controls that the unified interface intentionally does not standardize.

What is the shortest successful path?

Task	Start here	What comes back
Fit one spatial clustering	`cluster4d()`	A validated-shape `cluster4d_result`
Check a fitted result against its inputs	`validate_cluster4d()`	Errors, warnings, and a compact summary
Compare compatible fits	`compare_cluster4d()`	Explicit size, dispersion, coherence, or agreement estimands
Choose a defensible setting	`suggest_cluster4d_params()`	A starting point to validate on your own data
Create a reproducible example	`generate_synthetic_volume()`	Data, mask, and known latent labels

The complete first-use journey is in Getting started. Parameter effects and validation are covered by Choose parameters and Validate and compare clusterings.

Which methods share the unified interface?

methods <- eval(formals(cluster4d)$method)
paste(methods, collapse = ", ")
#> [1] "supervoxels, snic, slic, corr_slic, brs_slic, slice_msf, flash3d, g3s, rena, rena_plus, mcl, acsc, commute"

The list above is read from the installed function, so it cannot silently drift from the current API. Method names select implementations; they are not a performance ranking or endorsement. In particular, slice_msf remains experimental, is excluded from automatic recommendations, and should only be used for explicit evaluation under its documented contract. See Compare clustering methods for a scoped comparison and Method deep dives for algorithmic distinctions.

When should you use a direct function?

Typed method-specific wrappers expose native controls while retaining the standard result contract. Examples include cluster4d_snic(), cluster4d_slic(), cluster4d_g3s(), cluster4d_rena(), cluster4d_mcl(), and cluster4d_acsc().

The current cluster4d() documentation classifies supervoxels(), snic(), slic4d_supervoxels(), slice_msf(), and supervoxels_flash3d() as legacy, deprecated entry points. They remain exported for compatibility, but new code should use cluster4d() or a typed cluster4d_*() wrapper. Arguments and defaults need not match across lifecycle generations. The mapping guide is Direct method APIs and cluster4d.

What should you inspect after fitting?

Use the result rather than reconstructing state from method internals:

fit$labels          # labels in included-mask voxel order
fit$actual_k        # number of labels actually produced
fit$centers         # cluster means in the original feature space
fit$coord_centers   # cluster centroids in physical millimetres
fit$parameters      # recorded fitting parameters
fit$provenance      # geometry, mask, feature, and label provenance

Read clustering results explains these fields and shows the validation receipt that should accompany a saved or exported fit.