cluster_choice: Cluster Choice - sweep k, dissimilarity and method

In Nestimate: Network Estimation, Bootstrap, and Higher-Order Analysis

Cluster Choice – sweep k, dissimilarity and method

Description

One-call sweep across any combination of k, dissimilarity metric, and clustering algorithm for distance-based sequence clustering. Mirrors compare_mmm for model-based clustering: returns a data frame with one row per swept configuration, a best marker on the silhouette-max row in the print method, and a plot() that adapts to the swept axes.

Usage

cluster_choice(
  data,
  k = 2:5,
  dissimilarity = "hamming",
  method = "ward.D2",
  ...
)

Arguments

data	Sequence data (data frame or matrix) – forwarded to build_clusters.
k	Integer vector of cluster counts to sweep. Default 2:5. Each value must be >= 2 and <= n - 1.
dissimilarity	Character vector of dissimilarity metrics. Use "all" to expand to every supported metric: c("hamming", "osa", "lv", "dl", "lcs", "qgram", "cosine", "jaccard", "jw"). Default "hamming".
method	Character vector of clustering algorithms. Use "all" to expand to every supported method: c("pam", "ward.D2", "ward.D", "complete", "average", "single", "mcquitty", "median", "centroid"). Default "ward.D2".
...	Other arguments forwarded to build_clusters (weighted, lambda, q, p, seed, na_syms, covariates). Note: weighted = TRUE only works with dissimilarity = "hamming" and is rejected up-front when sweeping mixed dissimilarities.

Value

A cluster_choice object (a data.frame subclass) with one row per (k, dissimilarity, method) combination and columns:

k, dissimilarity, method

The configuration for that row.

silhouette

Overall average silhouette width (from cluster::silhouette, computed inside build_clusters).

mean_within_dist

Size-weighted mean of within-cluster distances, in the units of the row's dissimilarity.

min_size, max_size, size_ratio

Cluster-size balance bounds and their ratio (max / min).

See Also

build_clusters, compare_mmm for the model-based equivalent, cluster_diagnostics for the post-fit diagnostic surface on a single clustering.

Examples

seqs <- data.frame(V1 = sample(c("A","B","C"), 40, TRUE),
                   V2 = sample(c("A","B","C"), 40, TRUE))
cluster_choice(seqs, k = 2:4)

# Sweep dissimilarities at fixed k
cluster_choice(seqs, k = 3, dissimilarity = c("hamming", "lcs", "jaccard"))

# Full grid of k x dissimilarity
cluster_choice(seqs, k = 2:4, dissimilarity = c("hamming", "lcs"))

# "all" sentinel
cluster_choice(seqs, k = 3, dissimilarity = "all")

Nestimate documentation built on July 11, 2026, 1:09 a.m.