Skip to main content

26  Clustering

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.

26.1 K-means

x <- iris[, 1:4]
execution <- setup_SerialExecution(n_workers_algorithm = 1L, seed = 2026L)
fit <- cluster(x, config = setup_KMeans(k = 3L), execution_config = execution)
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.

soft <- cluster(x, config = setup_CMeans(k = 3L), execution_config = execution)
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 CMeans... [cluster]
2026-11-03 23:31:13 Checking unsupervised data... ✔ [check_unsupervised_data]
2026-11-03 23:31:13 Clustering with CMeans ... [cluster_]
2026-11-03 23:31:13 Done in 0.03 seconds. [cluster]
head(get_membership(soft))
             1         2           3
         <num>     <num>       <num>
1: 0.001072023 0.9966236 0.002304386
2: 0.007498304 0.9758511 0.016650582
3: 0.006414809 0.9798250 0.013760200
4: 0.010107992 0.9674256 0.022466455
5: 0.001767930 0.9944703 0.003761748
6: 0.020620472 0.9345711 0.044808474

26.2 Assign new cases

assign_clusters(fit, x[1:5, ])
2026-11-03 23:31:13 Checking unsupervised data... ✔ [check_unsupervised_data]

[1] 1 3 3 3 1

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.
setup_DBSCAN() Density-based clustering with noise assignments.
setup_HOPACH() Hierarchical ordered partitioning and collapsing.
setup_SpectralRBF(), setup_SpectralLaplace(), setup_SpectralLocal() Spectral clustering using the selected kernel.
setup_HardCL(), setup_NeuralGas() Competitive-learning methods.

26.4 Cluster selection and approximation

config_pamk <- setup_PAMK(krange = 2:5, criterion = setup_ASWCriterion())
config_spectral <- setup_SpectralRBF(k = 3L)

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.

metrics_km <- clustering_metrics(fit, x)
2026-11-03 23:31:13 Checking unsupervised data... ✔ [check_unsupervised_data]

metrics_km
<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) = \frac{1}{|C_i| - 1} \sum_{j \in C_i,\, j \ne i} d(i, j) \]

\[ b(i) = \min_{C \ne C_i} \frac{1}{|C|} \sum_{j \in C} d(i, j) \]

\[ s(i) = \frac{b(i) - a(i)}{\max\{a(i), b(i)\}} \]

\(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) != 1
other <- 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\):

\[ \text{mean assignment uncertainty} = \frac{1}{n} \sum_{i=1}^{n} \left(1 - \max_j u_{ij}\right) \]

\[ \text{mean assignment entropy} = \frac{1}{n} \sum_{i=1}^{n} \left(- \sum_{j=1}^{k} u_{ij} \log u_{ij}\right) \]

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.

clustering_metrics(soft, x)
2026-11-03 23:31:13 Checking unsupervised data... ✔ [check_unsupervised_data]

<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
membership <- as.matrix(get_membership(soft))
mean(1 - apply(membership, 1, max))
[1] 0.1427576

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:

clust_dbscan <- cluster(
  x,
  config = setup_DBSCAN(eps = 0.5, min_points = 5L),
  execution_config = execution
)
2026-11-03 23:31:13 ▶ [cluster]
2026-11-03 23:31:13 Input: 150 cases x 4 features. [summarize_unsupervised]
2026-11-03 23:31:13 // CPU | serial | 1 worker: algorithm 1 thread [msg_resources]
2026-11-03 23:31:13 Clustering with DBSCAN... [cluster]
2026-11-03 23:31:13 Checking unsupervised data... ✔ [check_unsupervised_data]
2026-11-03 23:31:13 Clustering with DBSCAN ... [cluster_]
2026-11-03 23:31:13 Found 2 clusters. [cluster]
2026-11-03 23:31:13 Done in 0.04 seconds. [cluster]
clustering_metrics(clust_dbscan, x)
2026-11-03 23:31:13 Checking unsupervised data... ✔ [check_unsupervised_data]

<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):

\[ \text{CH} = \frac{\operatorname{tr}(B) / (k - 1)}{\operatorname{tr}(W) / (n - k)} \]

\(\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.

© 2026 E.D. Gennatas