Package {phynotype}

phynotype: Clustering Workflows and Consensus Meta-Clustering

Description

phynotype provides tools for unsupervised phenotyping workflows. The six-step pipeline is:

1. Cluster: fit a single clustering solution with cluster().

2. Meta-cluster: aggregate candidate solutions into a consensus partition with metacluster().

3. Validate: score a solution with internal and external metrics using validate().

4. Explore: summarize cluster sizes, feature profiles, and two-dimensional embeddings with explore().

5. Predict: assign new observations to learned clusters with predict.cluster_fit().

6. Interpret: explain the clustering rule with feature_importance(), lime_explain(), and ceteris_paribus().

All steps operate through S3 generic functions and return structured objects with print(), summary(), and plot() methods.

Supported clustering methods

"kmeans"

Lloyd's k-means algorithm for numeric data.

"pam"

Partitioning Around Medoids for numeric data.

"hclust"

Hierarchical clustering via stats::hclust().

"agnes"

Agglomerative nesting via cluster::agnes().

"dbscan"

Density-based spatial clustering via dbscan::dbscan().

"gmm"

Gaussian mixture models via mclust::Mclust().

"kproto"

K-prototypes for mixed numeric/categorical data.

"kmm"

K-Mixed-Modes, a native mixed-data algorithm.

Validation metrics

Internal metrics: silhouette width (Rousseeuw, 1987), Calinski-Harabasz index (Calinski and Harabasz, 1974), Davies-Bouldin index (Davies and Bouldin, 1979), total within-cluster sum of squares, and bootstrap ARI. External metrics (when reference labels are available): adjusted Rand index (Hubert and Arabie, 1985) and normalized mutual information (Strehl and Ghosh, 2002).

Mixed-type data

Use prepare_mixed_data() to encode mixed-type data frames into a numeric matrix before distance-based methods. Use mixed_distance() to build a Gower distance matrix (Gower, 1971) before hierarchical methods. The exploratory embedding layer automatically selects PCA for numeric data, FAMD for mixed numeric/categorical data, MCA for categorical data, and classical MDS for distance objects.

Author(s)

Maintainer: Imad EL BADISY elbadisyimad@gmail.com

References

Rousseeuw, P.J. (1987). Silhouettes: A graphical aid to the interpretation and validation of cluster analysis. Journal of Computational and Applied Mathematics, 20, 53–65.

Calinski, T. and Harabasz, J. (1974). A dendrite method for cluster analysis. Communications in Statistics, 3(1), 1–27.

Davies, D.L. and Bouldin, D.W. (1979). A cluster separation measure. IEEE Transactions on Pattern Analysis and Machine Intelligence, 1(2), 224–227.

Hubert, L. and Arabie, P. (1985). Comparing partitions. Journal of Classification, 2(1), 193–218.

Strehl, A. and Ghosh, J. (2002). Cluster ensembles: A knowledge reuse framework for combining multiple partitions. Journal of Machine Learning Research, 3, 583–617.

Gower, J.C. (1971). A general coefficient of similarity and some of its properties. Biometrics, 27(4), 857–874.

See Also

cluster(), metacluster(), validate(), explore(), predict.cluster_fit(), feature_importance(), lime_explain(), ceteris_paribus()

Adjusted Rand Index

Description

Computes the Adjusted Rand Index (ARI) between two partitions, correcting the Rand Index for chance agreement (Hubert and Arabie, 1985). ARI equals 1 for identical partitions and has expectation 0 under independent random labelings.

Usage

adjusted_rand_index(x, y)

Arguments

Value

A single numeric value in (-\infty, 1].

References

Hubert, L. and Arabie, P. (1985). Comparing partitions. Journal of Classification, 2(1), 193–218.

Examples

adjusted_rand_index(c(1, 1, 2, 2), c(1, 1, 2, 3))

Cluster centers

Description

Extract the numeric cluster center matrix. Available for k-means and hierarchical methods trained on numeric data; returns NULL for PAM, k-prototypes, and GMM (use prototypes() or membership() instead).

Usage

centers(x, ...)

Arguments

Value

A numeric matrix with one row per cluster and one column per feature, or NULL.

See Also

prototypes(), clusters(), membership()

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
centers(fit)

Ceteris paribus profiles for clustering

Description

Compute individual conditional profiles for a fitted clustering rule. A ceteris paribus profile varies one feature over a grid while holding all other features fixed at an observed profile. It describes how the predicted cluster assignment or a cluster score changes locally as a single feature is perturbed.

Usage

ceteris_paribus(
  object,
  new_data,
  features = NULL,
  grid = NULL,
  grid_size = 25L,
  target = c("cluster", "score"),
  cluster = NULL,
  parallel = FALSE,
  cores = NULL,
  workers = NULL,
  progress = FALSE,
  ...
)

Arguments

Details

For observation x_i, feature j, and grid value z, define x_{i,-j} as all coordinates of x_i except feature j. The ceteris paribus profile is

CP_{i,j}(z) = g\{f(x_{i,-j}, z)\},

where f is the fitted clustering rule and g extracts either the predicted cluster label or a cluster-specific score. For methods that return membership probabilities, the score is the predicted membership. For distance-based methods, phynotype converts distances into normalized radial similarity scores so that larger values indicate stronger association with a cluster prototype.

These profiles are local diagnostic curves. They should be interpreted as behavior of the fitted clustering rule under controlled perturbation, not as causal effects.

Value

A ceteris_paribus object with a tidy profiles data frame. Each row records: the observation index, the feature being varied, the grid value at that step, the predicted target (cluster label or score), the observed feature value, and the baseline prediction.

References

Biecek, P. and Burzykowski, T. (2021). Explanatory Model Analysis. Chapman and Hall/CRC, Boca Raton. https://ema.drwhy.ai/

Gosiewska, A. and Biecek, P. (2019). iBreakDown: Uncertainty of model explanations for non-additive predictive models. arXiv:1903.11420.

Apley, D.W. and Zhu, J. (2020). Visualizing the effects of predictor variables in black box supervised learning models. Journal of the Royal Statistical Society: Series B, 82(4), 1059–1086.

See Also

lime_explain() for local linear surrogate explanations, feature_importance() for global permutation importance, predict.cluster_fit() which is used internally.

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
cp <- ceteris_paribus(fit, iris[1:3, 1:4], features = 1:2, grid_size = 10)
head(cp$profiles)

Fit a clustering solution

Description

Fit a single clustering solution using a supported method.

Usage

cluster(
  x,
  method = "kmeans",
  ...,
  k = NULL,
  scale = FALSE,
  center = TRUE,
  seed = NULL
)

Arguments

Details

cluster() is the single entry point for all supported methods. It dispatches to a method-specific backend registered via the internal cluster_registry, validates inputs, applies any requested preprocessing, and returns a cluster_fit object with a uniform interface regardless of the underlying engine.

Method-specific notes:

"kmeans"

Minimizes total within-cluster sum of squares \sum_j \sum_{x_i \in C_j} \|x_i - \mu_j\|^2 (Lloyd, 1982). Requires numeric x and k.

"pam"

Partitioning Around Medoids: minimizes \sum_i \min_g d(x_i, m_g) over actual observations (Kaufman and Rousseeuw, 1990). Requires the cluster package.

"hclust" / "agnes"

Hierarchical agglomerative methods. Accept a precomputed dist object or raw numeric data. Specify linkage to choose the merging criterion (default "complete" for hclust, "average" for agnes). "agnes" requires the cluster package.

"dbscan"

Density-Based Spatial Clustering of Applications with Noise (Ester et al., 1996). Requires eps (neighborhood radius) and minPts. Observations in sparse regions are labeled noise (cluster 0). Requires the dbscan package.

"gmm"

Gaussian Mixture Model fitted via the EM algorithm (Fraley and Raftery, 2002). Returns soft membership probabilities. Requires the mclust package.

"kproto"

K-prototypes for mixed numeric/categorical data (Huang, 1998). Use lambda to control the numeric-vs-categorical trade-off. Requires the clustMixType package.

"kmm"

K-Mixed-Modes: a native mixed-data algorithm that minimizes a weighted prototype distance combining squared Euclidean and Hamming contributions controlled by lambda.

Value

A cluster_fit object with components:

method

Character; the method used.

clusters

Integer vector of cluster assignments.

n_clusters

Integer; number of clusters found.

centers

Cluster centers (numeric methods) or NULL.

prototypes

Cluster prototypes (mixed methods) or NULL.

membership

Soft membership matrix (GMM) or NULL.

data_info

List of input metadata for downstream use.

References

Lloyd, S.P. (1982). Least squares quantization in PCM. IEEE Transactions on Information Theory, 28(2), 129–137.

Kaufman, L. and Rousseeuw, P.J. (1990). Finding Groups in Data: An Introduction to Cluster Analysis. John Wiley & Sons, New York.

Ester, M., Kriegel, H.-P., Sander, J. and Xu, X. (1996). A density-based algorithm for discovering clusters in large spatial databases with noise. Proceedings of the 2nd ACM SIGKDD, pp. 226–231.

Fraley, C. and Raftery, A.E. (2002). Model-based clustering, discriminant analysis, and density estimation. Journal of the American Statistical Association, 97(458), 611–631.

Huang, Z. (1998). Extensions to the k-means algorithm for clustering large data sets with categorical values. Data Mining and Knowledge Discovery, 2(3), 283–304.

See Also

validate() to score the fit, explore() to summarize cluster structure, predict.cluster_fit() to assign new observations, metacluster() for consensus clustering, feature_importance(), lime_explain(), ceteris_paribus() for interpretability.

Examples

# Numeric data: k-means
fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
fit
clusters(fit)
centers(fit)

# PAM (requires the cluster package)
if (requireNamespace("cluster", quietly = TRUE)) {
  fit_pam <- cluster(iris[, 1:4], method = "pam", k = 3)
  fit_pam
}

# Hierarchical clustering from a distance object
d <- mixed_distance(iris[, 1:4])
fit_hc <- cluster(d, method = "hclust", k = 3)
fit_hc

# Mixed data: k-prototypes
if (requireNamespace("clustMixType", quietly = TRUE)) {
  fit_kp <- cluster(iris, method = "kproto", k = 3, seed = 1)
  fit_kp
}

Cluster assignments

Description

Extract the integer cluster assignment vector from a fitted clustering object.

Usage

clusters(x, ...)

Arguments

Value

Integer vector of length equal to the number of training observations.

See Also

sizes(), n_clusters(), centers(), membership()

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
clusters(fit)

Calinski-Harabasz index

Description

The Calinski-Harabasz index is

Usage

compute_calinski_harabasz(data, clusters)

Arguments

Details

\mathrm{CH} = \frac{\mathrm{BSS} / (k - 1)}{\mathrm{WSS} / (n - k)},

where k is the number of clusters, n is the number of observations, \mathrm{BSS} is the between-cluster sum of squares, and \mathrm{WSS} is the within-cluster sum of squares. Higher values indicate better separation (Calinski and Harabasz, 1974).

References

Calinski, T. and Harabasz, J. (1974). A dendrite method for cluster analysis. Communications in Statistics, 3(1), 1–27.

Davies-Bouldin index

Description

The Davies-Bouldin index is

Usage

compute_davies_bouldin(data, clusters)

Arguments

Details

\mathrm{DB} = \frac{1}{k} \sum_{j=1}^{k} \max_{l \ne j} \frac{s_j + s_l}{d(\mu_j, \mu_l)},

where s_j is the average intra-cluster scatter of cluster j, \mu_j is its centroid, and d(\mu_j, \mu_l) is the Euclidean distance between centroids. Lower values indicate better separation (Davies and Bouldin, 1979).

References

Davies, D.L. and Bouldin, D.W. (1979). A cluster separation measure. IEEE Transactions on Pattern Analysis and Machine Intelligence, 1(2), 224–227.

Mean silhouette width by cluster

Description

Returns the average silhouette width within each cluster. Used internally by validate() to populate the per_cluster_table slot.

Usage

compute_per_cluster_silhouette(data, clusters)

Arguments

Mean silhouette width

Description

The silhouette width of an observation is

Usage

compute_silhouette_metric(data, clusters)

Arguments

Details

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

where a(i) is the mean distance from observation i to the other observations in its own cluster and b(i) is the minimum mean distance from i to the observations in any other cluster. The returned value is the mean over all observations (Rousseeuw, 1987).

References

Rousseeuw, P.J. (1987). Silhouettes: A graphical aid to the interpretation and validation of cluster analysis. Journal of Computational and Applied Mathematics, 20, 53–65.

Total within-cluster sum of squares

Description

The total within-cluster dispersion is

Usage

compute_total_within(data, clusters)

Arguments

Details

\mathrm{WSS} = \sum_{j=1}^{k} \sum_{i \in C_j} \|x_i - \mu_j\|^2.

Lower values indicate more compact clusters.

Explore clustering structure

Description

Summarize cluster sizes, feature profiles, feature separation, and a two-dimensional embedding for a fitted clustering solution.

Usage

explore(
  x,
  data = NULL,
  embedding = c("auto", "pca", "famd", "mca", "mds"),
  ...
)

Arguments

Details

explore() computes four summaries:

Size table

Number of observations per cluster.

Feature summary

Per-cluster mean, standard deviation, median, min, and max for each feature.

Separation table

The eta-squared statistic for each feature, \eta^2_j = \mathrm{SS}_{B,j} / \mathrm{SS}_{T,j}, measuring how much between-cluster variance each feature explains.

Embedding

Two-dimensional projection for visualization (see plot_clusters()).

Value

A cluster_explore object with components:

size_table

Data frame with cluster sizes.

feature_summary

Data frame with per-cluster descriptive statistics for each feature.

separation_table

Data frame with per-feature eta-squared values.

embedding

Data frame with two embedding coordinates and cluster labels.

See Also

cluster() to fit, plot_clusters() to plot the embedding, plot_feature_profiles() to plot feature profiles.

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
exp <- explore(fit)
exp$size_table
head(exp$feature_summary)
exp$separation_table

External clustering agreement metrics

Description

These helpers implement the reference-label metrics used by validate().

Permutation feature importance for clustering

Description

Estimate global feature importance by measuring how much a fitted clustering solution changes when each feature is independently permuted. The method is model-agnostic: it uses the fitted object's predict() method and therefore applies to clustering engines with native prediction support.

Usage

feature_importance(
  object,
  data = NULL,
  features = NULL,
  metric = c("instability", "silhouette", "total_within"),
  loss = NULL,
  n_repeats = 10L,
  seed = NULL,
  parallel = FALSE,
  cores = NULL,
  workers = NULL,
  progress = FALSE,
  ...
)

Arguments

Details

Let f denote the fitted clustering rule, X the evaluation data, \hat{c}=f(X) the baseline predicted partition, and X^{(m)}_{\pi(j)} the data matrix where feature j has been permuted in repetition m. For the default instability metric, feature importance is

FI_j = \frac{1}{M}\sum_{m=1}^{M} \frac{1}{n}\sum_{i=1}^{n} I\{\hat{c}_i \neq f(X^{(m)}_{\pi(j)})_i\}.

This quantity estimates the expected fraction of assignments that change when the marginal information in feature j is broken. Larger values indicate that the fitted clustering rule relies more strongly on that feature.

For score-style internal metrics, the package computes a baseline score S(f, X) and a permuted score S(f, X^{(m)}_{\pi(j)}). For silhouette, larger is better and

FI_j = \frac{1}{M}\sum_{m=1}^{M} \left[S(f, X) - S(f, X^{(m)}_{\pi(j)})\right].

For total within-cluster sum of squares, smaller is better and

FI_j = \frac{1}{M}\sum_{m=1}^{M} \left[W(f, X^{(m)}_{\pi(j)}) - W(f, X)\right].

Users can pass a custom loss function for domain-specific objectives. It must accept ⁠(data, clusters, object)⁠ and return a numeric scalar where larger values mean worse fit.

Value

A feature_importance object with components:

results

Data frame with one row per (feature, repeat) combination recording the baseline loss, the permuted loss, and the computed importance.

summary

Data frame with one row per feature, containing the mean importance, standard error, and number of repeats.

References

Breiman, L. (2001). Random forests. Machine Learning, 45(1), 5–32. (Permutation importance concept introduced in the context of random forests.)

Fisher, A., Rudin, C. and Dominici, F. (2019). All models are wrong, but many are useful: Learning a variable's importance by studying an entire class of prediction models simultaneously. Journal of Machine Learning Research, 20(177), 1–81.

See Also

lime_explain() for local explanations, ceteris_paribus() for individual conditional profiles, predict.cluster_fit() which is used internally.

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
imp <- feature_importance(fit, n_repeats = 3, seed = 1)
imp$summary

Fit the KMM algorithm

Description

KMM is a mixed-data clustering algorithm that minimizes a weighted prototype distance combining squared Euclidean distance on numeric variables and mismatch counts on categorical variables:

Usage

fit_kmm(data, params)

Arguments

Details

D(x_i, p_g) = \sum_{j \in \mathcal{N}} (x_{ij} - \mu_{gj})^2 + \lambda \sum_{j \in \mathcal{C}} I(x_{ij} \neq \nu_{gj}),

where \lambda \ge 0 balances categorical and numeric contributions.

Internal clustering metric metadata and formulas

Description

These helpers implement the internal validation criteria used by validate() and feature_importance().

Usage

metric_metadata(metric)

Estimate the KMM lambda weight

Description

Estimate the KMM lambda weight

Usage

lambda_kmm(data, scale_numeric = TRUE)

Arguments

LIME-style local explanations for clustering

Description

Explain individual cluster assignments or cluster scores with a locally weighted surrogate model. The method builds a synthetic neighborhood around each observation, predicts the fitted clustering behavior in that neighborhood, weights perturbed samples by proximity to the explained observation, and fits a simple weighted linear model.

Usage

lime_explain(
  object,
  new_data,
  n_features = 5L,
  n_permutations = 500L,
  kernel_width = NULL,
  target = c("cluster", "score"),
  cluster = NULL,
  seed = NULL,
  parallel = FALSE,
  cores = NULL,
  workers = NULL,
  progress = FALSE,
  ...
)

Arguments

Details

For an observation x, perturbed samples z_i, fitted clustering rule f, target extractor g, local surrogate h, and kernel \pi_x(z_i), the LIME objective is

\hat{h} = \arg\min_{h \in H} \sum_{i=1}^{N} \pi_x(z_i) \left[g\{f(z_i)\} - h(z_i)\right]^2 + \Omega(h).

phynotype uses a weighted linear surrogate for H. Feature ranking is based on the absolute fitted local coefficients after standardizing features by the training-data scale. The penalty term \Omega(h) is represented operationally by returning the largest n_features effects, which keeps the explanation sparse and readable without adding a heavy modeling dependency.

For target = "cluster", g\{f(z_i)\} is an indicator that the predicted cluster equals the cluster being explained. For target = "score", it is the cluster-specific membership or similarity score.

Value

A lime_explanation object with components:

explanations

Tidy data frame with one row per (observation, feature) pair, containing the local surrogate coefficient, absolute effect size, direction, and rank.

neighborhoods

Data frame with all perturbed samples, their predicted responses, kernel weights, and distances to the explained observation.

References

Ribeiro, M.T., Singh, S. and Guestrin, C. (2016). "Why should I trust you?": Explaining the predictions of any classifier. Proceedings of the 22nd ACM SIGKDD International Conference on Knowledge Discovery and Data Mining, pp. 1135–1144.

See Also

ceteris_paribus() for individual conditional profiles, feature_importance() for global importance, predict.cluster_fit() which is used internally.

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
lx <- lime_explain(fit, iris[1:2, 1:4], n_permutations = 50, seed = 1)
lx$explanations

Membership matrix

Description

Extract the soft membership (posterior probability) matrix. Only methods that return probabilistic assignments (e.g. GMM) populate this slot; all other methods return NULL.

Usage

membership(x, ...)

Arguments

Value

A numeric matrix with one row per observation and one column per cluster, or NULL.

See Also

clusters(), centers(), prototypes()

Examples

if (requireNamespace("mclust", quietly = TRUE)) {
  fit <- cluster(iris[, 1:4], method = "gmm", k = 3, seed = 1)
  head(membership(fit))
}

Fit a consensus meta-clustering solution

Description

Fit several candidate clustering solutions and summarize their agreement through a co-association consensus matrix. The consensus partition is obtained by hierarchical clustering of the dissimilarity matrix D = 1 - C, where C_{ij} is the proportion of candidate partitions that place observations i and j in the same cluster.

Usage

metacluster(
  x,
  methods = c("kmeans", "pam", "hclust"),
  k = 2:6,
  consensus = "coassoc",
  scale = FALSE,
  center = TRUE,
  seed = NULL,
  ...
)

Arguments

Details

Co-association consensus

For B candidate partitions, the co-association matrix is

C_{ij} = \frac{1}{B} \sum_{b=1}^{B} I\{i \text{ and } j \text{ are in the same cluster in partition } b\}.

This estimator is related to the Evidence Accumulation Clustering framework (Fred and Jain, 2002). The consensus dissimilarity D = 1 - C is then hierarchically clustered (average linkage), and the optimal number of clusters is chosen by maximizing the mean silhouette width.

Stability of the ensemble is summarized by the mean pairwise partition agreement (PPA) across all candidate pairs:

\mathrm{PPA}(U, V) = \frac{1}{\binom{n}{2}} \sum_{i < j} I\{(u_i = u_j) = (v_i = v_j)\}.

Value

A metacluster_fit object with components:

final_clusters

Integer vector of final consensus assignments.

final_k

Integer; the selected number of clusters.

coassoc_matrix

The n \times n co-association matrix.

candidate_table

Data frame listing all fitted candidate solutions.

stability_summary

Mean, min, and max pairwise partition agreement.

selection_summary

Per-k silhouette scores used for selection.

References

Fred, A.L.N. and Jain, A.K. (2002). Data clustering using evidence accumulation. Proceedings of the 16th International Conference on Pattern Recognition (ICPR'02), Vol. 4, pp. 276–280.

Strehl, A. and Ghosh, J. (2002). Cluster ensembles: A knowledge reuse framework for combining multiple partitions. Journal of Machine Learning Research, 3, 583–617.

See Also

cluster() for single solutions, validate() to score the consensus partition, plot_coassoc() to visualize the agreement matrix, plot_consensus() for a 2-D embedding of the final clusters.

Examples

mfit <- metacluster(iris[, 1:4], methods = c("kmeans", "hclust"), k = 2:4,
                    seed = 1)
mfit

# Inspect the co-association matrix
mfit$coassoc_matrix[1:4, 1:4]

# Score the consensus partition
validate(mfit)$metrics_table

Method used

Description

Return the name of the clustering method used to fit the object.

Usage

method_used(x, ...)

Arguments

Value

Character scalar (e.g. "kmeans", "pam", "hclust").

See Also

cluster()

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
method_used(fit)

Compute a mixed-type distance matrix

Description

Build a Gower dissimilarity matrix for mixed-type data using cluster::daisy(). This is the recommended first step before hierarchical clustering ("hclust" or "agnes") when the input contains categorical variables.

Usage

mixed_distance(x, metric = "gower", ...)

Arguments

Details

For two observations x_i and x_j, the Gower coefficient (Gower, 1971) is

d_G(i, j) = \frac{\sum_{f=1}^{p} w_{ijf}\, \delta_{ijf}\, s_{ijf}} {\sum_{f=1}^{p} w_{ijf}\, \delta_{ijf}},

where \delta_{ijf} indicates whether feature f is comparable (not missing), w_{ijf} is an optional weight, and s_{ijf} is the partial similarity: the scaled absolute difference for numeric features and 0 (match) or 1 (mismatch) for categorical features.

Value

A dist object.

References

Gower, J.C. (1971). A general coefficient of similarity and some of its properties. Biometrics, 27(4), 857–874.

See Also

prepare_mixed_data() for converting mixed data to a numeric matrix, cluster() for fitting with the resulting distance object.

Examples

d <- mixed_distance(iris)
fit <- cluster(d, method = "hclust", k = 3)
fit

Number of clusters

Description

Return the number of clusters in a fitted clustering object. For DBSCAN, this excludes the noise cluster (label 0).

Usage

n_clusters(x, ...)

Arguments

Value

Integer scalar.

See Also

sizes(), clusters()

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
n_clusters(fit)

Discrete color/fill scales matching theme_phynotype

Description

Colorblind-friendly discrete color and fill scales (Okabe-Ito palette, recycled/interpolated beyond 8 levels) for consistent group colors across phynotype figures.

Usage

scale_color_phynotype(...)

scale_fill_phynotype(...)

Arguments

Value

A ggplot2 discrete scale object.

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
plot_clusters(fit) + scale_color_phynotype()

Plot a cluster biplot

Description

A self-contained reimplementation of factoextra's fviz_pca_biplot() and fviz_mca_biplot() geometry (individual points/arrows, variable arrows or category points, axis percentage labels, dashed origin lines), producing the same plots without depending on factoextra. Only the "pca" and "mca" embeddings are supported, matching the biplot functions factoextra itself provides; there is no FAMD biplot equivalent, and MDS has no variable space to project.

Usage

plot_biplot(
  x,
  data = NULL,
  embedding = c("auto", "pca", "mca"),
  variant = c("cluster", "cos2", "label"),
  top_n = NULL,
  ...
)

Arguments

Details

Three display variants, matching factoextra's own documented examples (?factoextra::fviz_pca):

"cluster"

Individuals colored and shaped by cluster assignment. The default.

"cos2"

Individuals colored by their quality of representation (cos2) on a white-blue-orange gradient.

"label"

Individuals shown as text labels (observation names or row numbers) instead of points.

For a "pca" embedding, variables are drawn as arrows from the origin, scaled so their spread matches that of the individuals (factoextra's own scaling rule (ratio * 0.7), where ratio is the ratio of the individuals' to variables' coordinate ranges). For a "mca" embedding, variable categories are drawn as unscaled points (matching factoextra::fviz_mca_biplot()'s default arrows = c(FALSE, FALSE)).

Value

A ggplot object.

See Also

plot_clusters(), explore() for the underlying embedding.

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
plot_biplot(fit)
plot_biplot(fit, variant = "cos2")
plot_biplot(fit, variant = "label")

Plot cluster sizes

Description

Display a bar chart of the number of observations per cluster.

Usage

plot_cluster_sizes(x, ...)

Arguments

Value

A ggplot object.

See Also

sizes(), plot_clusters(), plot_feature_profiles()

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
plot_cluster_sizes(fit)

Plot clustered observations in 2D

Description

Project observations onto a two-dimensional embedding and color them by cluster assignment. For metacluster_fit objects, delegates to plot_consensus().

Usage

plot_clusters(
  x,
  data = NULL,
  embedding = c("auto", "pca", "famd", "mca", "mds"),
  ...
)

Arguments

Value

A ggplot object.

See Also

explore() for the underlying embedding, plot_cluster_sizes(), plot_feature_profiles()

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
plot_clusters(fit)

Plot the co-association matrix

Description

Display the n \times n co-association matrix as a heatmap. High values (near 1) indicate pairs of observations that were consistently co-clustered across candidate partitions.

Usage

plot_coassoc(x, ...)

Arguments

Value

A ggplot object.

See Also

metacluster(), plot_consensus()

Examples

mfit <- metacluster(iris[, 1:4], methods = c("kmeans", "hclust"),
                    k = 2:3, seed = 1)
plot_coassoc(mfit)

Plot consensus clustering in 2D

Description

Project the consensus cluster assignments onto a two-dimensional embedding.

Usage

plot_consensus(
  x,
  data = NULL,
  embedding = c("auto", "pca", "famd", "mca", "mds"),
  ...
)

Arguments

Value

A ggplot object.

See Also

metacluster(), plot_coassoc()

Examples

mfit <- metacluster(iris[, 1:4], methods = c("kmeans", "hclust"),
                    k = 2:3, seed = 1)
plot_consensus(mfit)

Plot a clustering dendrogram

Description

Draw the dendrogram from a hierarchical cluster_fit (fitted via "hclust" or "agnes") or the consensus hierarchical tree from a metacluster_fit.

Usage

plot_dendrogram(x, ...)

Arguments

Value

The underlying hclust object, invisibly.

See Also

cluster(), metacluster(), plot_consensus()

Examples

d <- mixed_distance(iris[, 1:4])
fit <- cluster(d, method = "hclust", k = 3)
plot_dendrogram(fit)

mfit <- metacluster(iris[, 1:4], methods = c("kmeans", "hclust"),
                    k = 2:3, seed = 1)
plot_dendrogram(mfit)

Plot feature profiles by cluster

Description

Display per-cluster mean values for each feature as a grouped bar chart.

Usage

plot_feature_profiles(x, features = NULL, ...)

Arguments

Value

A ggplot object.

See Also

explore(), plot_clusters(), plot_cluster_sizes()

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
exp <- explore(fit)
plot_feature_profiles(exp)
plot_feature_profiles(exp, features = c("Sepal.Length", "Petal.Length"))

Plot silhouette widths

Description

Display observation-level silhouette widths colored by cluster. Observations with negative widths lie closer to a neighboring cluster than to their own and may be misclassified.

Usage

plot_silhouette(x, ...)

Arguments

Value

A ggplot object.

See Also

validate()

Examples

if (requireNamespace("cluster", quietly = TRUE)) {
  fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
  plot_silhouette(fit)
}

Predict cluster assignments for new observations

Description

Assign new observations to the clusters of a fitted cluster_fit object. The prediction strategy is method-dependent: k-means, PAM, and hierarchical methods use nearest-centroid or nearest-prototype rules; GMM uses the posterior mode; DBSCAN uses a density-based rule falling back to the nearest core point.

Usage

## S3 method for class 'cluster_fit'
predict(object, new_data, ...)

Arguments

Value

A cluster_prediction object with components:

clusters

Integer vector of predicted cluster assignments.

distances

Distance matrix to each cluster center/prototype, or NULL for methods that do not produce distances.

membership

Soft membership matrix (GMM only), or NULL.

See Also

cluster() to fit, feature_importance(), lime_explain(), and ceteris_paribus() which all use predict() internally.

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)

# Predict on the training data
pred <- predict(fit, iris[1:10, 1:4])
pred$clusters

# Predict on new data
new_obs <- data.frame(
  Sepal.Length = c(5.0, 7.0),
  Sepal.Width  = c(3.5, 3.0),
  Petal.Length = c(1.5, 5.0),
  Petal.Width  = c(0.3, 1.8)
)
predict(fit, new_obs)$clusters

Predict with KMM

Description

Predict with KMM

Usage

predict_kmm(object, new_data, ...)

Arguments

Prepare mixed-type data for numeric clustering methods

Description

Convert a data frame containing numeric, logical, character, or factor columns into a numeric design matrix suitable for methods such as "kmeans", "pam", "dbscan", and "gmm".

Usage

prepare_mixed_data(
  x,
  center = TRUE,
  scale = TRUE,
  drop_first = FALSE,
  na_action = c("keep", "fail")
)

Arguments

Details

Categorical variables are one-hot encoded (full-rank by default), numeric variables are optionally centered and scaled, and missingness can be preserved as an explicit level or trigger an error.

This is intentionally a manual first step. Clustering algorithms that use Euclidean distances or Gaussian models should not silently coerce mixed data. For hierarchical methods on mixed data, use mixed_distance() instead.

Value

A numeric matrix with preprocessing metadata stored in the attribute "phynotype_preprocess".

See Also

mixed_distance() for Gower-distance computation before hierarchical clustering.

Examples

# Mixed data frame
df <- data.frame(
  x1 = c(1.2, 0.5, 3.1),
  x2 = factor(c("A", "B", "A"))
)
mat <- prepare_mixed_data(df)
mat

Cluster prototypes

Description

Extract the cluster prototype table. Prototypes are actual observations (PAM medoids) or mixed-type representatives (k-prototypes, KMM); returns NULL for methods that use centroids rather than prototypes.

Usage

prototypes(x, ...)

Arguments

Value

A matrix or data frame with one row per cluster, or NULL.

See Also

centers(), clusters()

Examples

if (requireNamespace("cluster", quietly = TRUE)) {
  fit <- cluster(iris[, 1:4], method = "pam", k = 3)
  prototypes(fit)
}

Cluster sizes

Description

Return the number of observations assigned to each cluster.

Usage

sizes(x, ...)

Arguments

Value

Named integer vector, where names are the cluster labels.

See Also

clusters(), n_clusters()

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
sizes(fit)

phynotype ggplot2 theme

Description

The single ggplot2 theme used consistently across every phynotype plot function (plot_clusters(), plot_cluster_sizes(), plot_feature_profiles(), plot_consensus(), plot_coassoc(), plot_biplot(), plot() methods for feature_importance, ceteris_paribus, and lime_explanation objects, and plot_validation()). Built on ggplot2::theme_classic() with an Okabe-Ito colorblind-safe palette, matching the style used by the funcml package's theme_funcml().

Usage

theme_phynotype(base_size = 11)

Arguments

Value

A ggplot2 theme object.

See Also

scale_color_phynotype(), scale_fill_phynotype()

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)
plot_clusters(fit) + theme_phynotype()

Validate clustering results

Description

Compute internal and external validation metrics for a fitted clustering object or over a grid of candidate cluster counts.

Usage

validate(
  x,
  ...,
  method = "kmeans",
  k = NULL,
  truth = NULL,
  metrics = NULL,
  n_boot = 10
)

Arguments

Details

Internal metrics

Silhouette width (Rousseeuw, 1987):

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

where a(i) is the mean intra-cluster distance and b(i) is the minimum mean distance to any other cluster. Values near 1 indicate dense, well-separated clusters.

Calinski-Harabasz index (Calinski and Harabasz, 1974):

\mathrm{CH} = \frac{\mathrm{BSS} / (k-1)}{\mathrm{WSS} / (n-k)},

where BSS is the between-cluster sum of squares and WSS is the within-cluster sum of squares. Higher values indicate better separation.

Davies-Bouldin index (Davies and Bouldin, 1979):

\mathrm{DB} = \frac{1}{k} \sum_{j=1}^{k} \max_{l \ne j} \frac{s_j + s_l}{d(\mu_j, \mu_l)},

where s_j is the mean intra-cluster scatter. Lower values are better.

Total within-cluster sum of squares:

\mathrm{WSS} = \sum_{j=1}^{k} \sum_{i \in C_j} \|x_i - \mu_j\|^2.

Bootstrap ARI (Fang and Wang, 2012): mean adjusted Rand index between the reference partition and partitions fitted on bootstrap resamples.

External metrics

Adjusted Rand index (Hubert and Arabie, 1985):

\mathrm{ARI} = \frac{\sum_{ij}\binom{n_{ij}}{2} - E}{\frac{1}{2} \!\left[\sum_i\binom{a_i}{2}+\sum_j\binom{b_j}{2}\right] - E},

where E is the expected index under random partitions. Values near 1 indicate agreement close to the reference.

Normalized mutual information (Strehl and Ghosh, 2002):

\mathrm{NMI}(U, V) = \frac{I(U; V)}{\sqrt{H(U)\, H(V)}}.

Value

A cluster_validation object with components:

metrics_table

Data frame with columns metric, value, scale, direction.

per_cluster_table

Per-cluster mean silhouette widths, or NULL.

References

Rousseeuw, P.J. (1987). Silhouettes: A graphical aid to the interpretation and validation of cluster analysis. Journal of Computational and Applied Mathematics, 20, 53–65.

Calinski, T. and Harabasz, J. (1974). A dendrite method for cluster analysis. Communications in Statistics, 3(1), 1–27.

Davies, D.L. and Bouldin, D.W. (1979). A cluster separation measure. IEEE Transactions on Pattern Analysis and Machine Intelligence, 1(2), 224–227.

Hubert, L. and Arabie, P. (1985). Comparing partitions. Journal of Classification, 2(1), 193–218.

Strehl, A. and Ghosh, J. (2002). Cluster ensembles: A knowledge reuse framework for combining multiple partitions. Journal of Machine Learning Research, 3, 583–617.

Fang, Y. and Wang, J. (2012). Selection of the number of clusters via the bootstrap method. Computational Statistics and Data Analysis, 56(3), 468–477.

See Also

cluster() to fit a solution, plot_silhouette() to visualize per-observation silhouette widths, explore() for structural summaries.

Examples

fit <- cluster(iris[, 1:4], method = "kmeans", k = 3, seed = 1)

# Internal metrics
val <- validate(fit)
val$metrics_table

# External metrics with known labels
val_ext <- validate(fit, truth = iris$Species)
val_ext$metrics_table

# Grid search over k values
grid_val <- validate(iris[, 1:4], method = "kmeans", k = 2:5)
grid_val$metrics_table

Validation helpers for KMM

Description

Validation helpers for KMM

Usage

validate_kmm_params(data, params)

Arguments