cluster() groups cases using selected numeric features. Its configuration records the algorithm and settings. The interpretation of distance, scale, noise, and membership depends on the method.
2026-11-03 23:31:12 ▶ [cluster]2026-11-03 23:31:12 Input: 150 cases x 4 features. [summarize_unsupervised]2026-11-03 23:31:12 //CPU | serial | 1 worker: algorithm 1 thread [msg_resources]2026-11-03 23:31:12 Clustering with KMeans... [cluster]2026-11-03 23:31:12 Checking unsupervised data... ✔ [check_unsupervised_data]
2026-11-03 23:31:12 Clustering with KMeans ... [cluster_]2026-11-03 23:31:12 Done in 0.09 seconds. [cluster]
table(clusters(fit))
1 2 3
32 96 22
get_metrics(fit)
<Training Clustering Metrics> n Cases: 150
n Clusters: 3
Noise Fraction: 0.00
Not computed: mean_assignment_uncertainty (unsupported), mean_assignment_entropy (unsupported), mean_silhouette (not_requested)
clusters() returns the cluster label of each fitted case. A HardClustering holds only these assignments. A SoftClustering additionally holds a membership matrix with one column per cluster, which get_membership() returns. Membership weights and posterior probabilities have method-specific interpretations.
assign_clusters() assigns each new case to the cluster with the closest centroid for KMeans, HardCL, and NeuralGas. Other methods define no rule for cases outside the fitted data and raise an error naming the methods that do.
26.3 Select a method
available_clustering()
CMeans: Fuzzy c-means clustering
DBSCAN: DBSCAN density-based clustering
GMM: Gaussian mixture model clustering
HOPACH: Hierarchical Ordered Partitioning and Collapsing Hybrid
HardCL: Hard competitive learning
KMeans: K-means clustering
NeuralGas: Neural Gas clustering
PAM: Partitioning Around Medoids
PAMK: Partitioning Around Medoids with estimation of the number of clusters
SpectralLaplace: Spectral clustering with an exponential kernel, which decays more slowly than the Gaussian and so keeps more weight on distant pairs
SpectralLocal: Spectral clustering with a Gaussian kernel whose width is set per case from the distance to its seventh nearest neighbor, which lets one clustering hold groups of differing density
SpectralRBF: Spectral clustering with a Gaussian kernel of one shared width
Constructor
Method
setup_KMeans()
K-means partitioning.
setup_CMeans()
Fuzzy C-means with membership weights.
setup_GMM()
Gaussian mixture modeling, with component-count selection where configured.
setup_PAM()
Partitioning around medoids.
setup_PAMK()
Medoid clustering with selection of the cluster count.
PAMK criteria include average silhouette width, its average over random subsets of the cases, and the Calinski-Harabasz index, which Section 26.5.5 defines. Spectral configurations accept a typed setup_Nystrom() approximation. These choices belong to the configuration and affect the fitted solution.
26.5 Clustering metrics
get_metrics() returns the measures that cluster() stores on its result. clustering_metrics() computes the same measures and adds the mean silhouette width. Both describe the data the clustering was fitted on, and clustering_metrics() raises an error for any other data.
<Training Clustering Metrics> n Cases: 150
n Clusters: 3
Noise Fraction: 0.00
Mean Silhouette: 0.52
Not computed: mean_assignment_uncertainty (unsupported), mean_assignment_entropy (unsupported)
metrics_km[["mean_silhouette"]] reads a single value.
In the definitions below, \(n\) is the number of cases and \(k\) the number of fitted clusters.
Measure
Definition
Range
Available for
n_cases
Number of cases.
\(n \ge 0\)
Every clustering
n_clusters
Number of fitted clusters, excluding noise and including any cluster that holds no case.
\(k \ge 0\)
Every clustering
noise_fraction
Fraction of cases labeled noise. Zero for an algorithm that assigns every case.
\([0, 1]\)
Every clustering
mean_silhouette
Mean silhouette width of the cases not labeled noise.
\([-1, 1]\)
clustering_metrics(), at least two clusters
mean_assignment_uncertainty
Mean of one minus the largest membership of each case.
\([0, 1 - 1/k]\)
SoftClustering
mean_assignment_entropy
Mean Shannon entropy of the membership of each case, in nats.
\([0, \log k]\)
SoftClustering
26.5.1 Mean silhouette width
The silhouette width compares the distance from a case to its own cluster with the distance to the nearest other cluster (Rousseeuw 1987). For case \(i\) in cluster \(C_i\), with \(d(i, j)\) the Euclidean distance between cases \(i\) and \(j\) over the clustered features:
\(a(i)\) is the mean distance to the other cases of the cluster, and \(b(i)\) is the smallest mean distance to the cases of another cluster. mean_silhouette is the mean of \(s(i)\) over the cases not labeled noise.
\(s(i)\) near 1: the case lies much closer to its own cluster than to the nearest other cluster.
\(s(i)\) near 0: the case lies between two clusters.
\(s(i) < 0\): the case lies closer, on average, to another cluster than to its own.
The width of a case alone in its cluster is 0, as is the width of a case with \(a(i) = b(i) = 0\). Cases labeled noise are excluded both as cases and as members of other clusters. With fewer than two clusters, the measure has no value and its status is not_applicable. The cost of the computation is quadratic in the number of cases, so cluster() reports the measure as not_requested.
This chunk computes the width of the first case of the K-means fit:
d <-as.matrix(dist(x))labels <-clusters(fit)same <- labels == labels[1] &seq_along(labels) !=1other <- labels != labels[1]a <-mean(d[1, same])b <-min(tapply(d[1, other], labels[other], mean))c(a = a, b = b, s = (b - a) /max(a, b))
a b s
0.4181654 0.9796849 0.5731633
Struyf et al. (1997) propose the following subjective interpretation of the silhouette coefficient, the largest mean silhouette width over values of \(k\), for partitioning methods:
Silhouette coefficient
Interpretation
0.71 to 1.00
Strong structure
0.51 to 0.70
Reasonable structure
0.26 to 0.50
Weak structure, which could be artificial; try additional methods
0.25 or less
No substantial structure
26.5.2 Assignment uncertainty and entropy
A SoftClustering, from setup_CMeans() or setup_GMM(), holds a membership \(u_{ij}\) of each case \(i\) in each cluster \(j\), with \(\sum_j u_{ij} = 1\):
The entropy uses the natural logarithm and takes \(0 \log 0\) as 0. Both measures are 0 when every case belongs wholly to one cluster, and both reach their maximum when every case belongs equally to all clusters.
<Training Clustering Metrics> n Cases: 150
n Clusters: 3
Noise Fraction: 0.00
Mean Assignment Uncertainty: 0.14
Mean Assignment Entropy: 0.40
Mean Silhouette: 0.55
Both measures describe the concentration of the memberships. A fuzzy membership is not a calibrated probability, so values are not comparable between models fitted under different assumptions, such as CMeans and GMM.
26.5.3 Noise
DBSCAN labels cases that belong to no cluster as noise, with cluster label 0. n_clusters excludes this label, and noise_fraction reports its share of the cases:
<Training Clustering Metrics> n Cases: 150
n Clusters: 2
Noise Fraction: 0.11
Mean Silhouette: 0.74
Not computed: mean_assignment_uncertainty (unsupported), mean_assignment_entropy (unsupported)
The mean silhouette width of a clustering with noise describes only the cases assigned to a cluster, so it is read together with noise_fraction.
26.5.4 Measure status
Every measure has a status, which states why it holds its value. The print method lists the measures without a value after Not computed:, and the @status property holds the full row.
Status
Meaning
computed
The measure holds a value.
unsupported
The clustering lacks what the measure needs, such as a membership matrix.
not_requested
The measure was not computed. cluster() reports mean_silhouette with this status.
not_applicable
The measure does not apply to this result: mean_silhouette with fewer than two clusters.
undefined
Declared by the schema for a computed measure with no defined value. cluster() and clustering_metrics() do not assign it.
26.5.5 Criteria for selecting the number of clusters
setup_PAMK() fits a clustering for each candidate in krange and keeps the one with the largest value of its criterion. These criteria are separate from ClusteringMetrics.
Constructor
Criterion
setup_ASWCriterion()
Average silhouette width over all cases.
setup_MultiASWCriterion()
Average silhouette width averaged over random subsets of the cases, for large datasets.
setup_CHCriterion()
Calinski-Harabasz index.
The Calinski-Harabasz index is the ratio of between-cluster to within-cluster dispersion, each divided by its degrees of freedom (Caliński and Harabasz 1974):
\(\operatorname{tr}(W)\) is the sum of squared distances from each case to its cluster centroid. \(\operatorname{tr}(B)\) is the total sum of squares minus \(\operatorname{tr}(W)\). Larger values indicate compact, well-separated clusters. The index has no fixed upper bound, so it compares values of \(k\) on the same data.
26.6 Assessment and interpretation
Internal measures, such as the silhouette, characterize a solution under its feature representation and distance. External labels can support a separate comparison, for example a cross-tabulation of clusters() with a known grouping.
When features have different units, define scaling before fitting and retain the fitted preprocessor. A low-dimensional plot displays a projection of the cases; apparent separation in that projection is distinct from separation in the space used for clustering.
Rousseeuw, Peter J. 1987. “Silhouettes: A Graphical Aid to the Interpretation and Validation of Cluster Analysis.”Journal of Computational and Applied Mathematics 20: 53–65. https://doi.org/10.1016/0377-0427(87)90125-7.
Struyf, Anja, Mia Hubert, and Peter J. Rousseeuw. 1997. “Clustering in an Object-Oriented Environment.”Journal of Statistical Software 1 (4): 1–30. https://doi.org/10.18637/jss.v001.i04.