get_clust_tendency: Assessing Clustering Tendency

In factoextra: Extract and Visualize the Results of Multivariate Data Analyses

Assessing Clustering Tendency

Description

Before applying clustering methods, assess whether the data show non-random structure, a process known as assessing clustering tendency. get_clust_tendency() uses the Hopkins statistic and, optionally, an ordered dissimilarity image (ODI). Rows containing missing values are omitted, and the remaining matrix must be numeric and finite. The observed rows are sampled without replacement; artificial points are sampled uniformly within the observed bounding box. Zero-range columns are ignored for the Hopkins calculation when at least one column varies; an all-constant data set remains undefined. In the ODI, objects grouped by hierarchical clustering are displayed in consecutive order. For more details and interpretation, see Assessing Clustering Tendency in R.

Usage

get_clust_tendency(
  data,
  n,
  graph = TRUE,
  gradient = list(low = "red", mid = "white", high = "blue"),
  seed = NULL
)

Arguments

data	a numeric data frame or matrix. Columns are variables and rows are samples. Computations are performed on complete rows. To calculate the Hopkins statistic for variables, transpose the data first.
n	a positive integer specifying the number of points selected from sample space and from the observed data. Must be smaller than the number of complete observations.
graph	logical value; if TRUE the ordered dissimilarity image (ODI) is shown.
gradient	a list containing three elements specifying the colors for low, mid and high values in the ordered dissimilarity image. The element "mid" can take the value of NULL.
seed	an integer seed for reproducibility, or NULL to use the current RNG stream. When non-NULL, the function restores the caller RNG state on exit.

Details

Hopkins statistic: Values near 1 support a clustered tendency, values near 0.5 are consistent with complete spatial randomness, and values near 0 indicate regular spacing. The statistic uses the formula from Cross and Jain (1982), with exponent d = D, where D is the number of varying columns. Redundant constant columns therefore do not change the statistic. A Beta(n, n) comparison is an approximation under ideal complete-spatial-randomness assumptions, not an unconditional finite-sample distribution for every data set.

Note on interpretation: This function returns the Hopkins statistic H where values close to 1 indicate clusterable data. Some other packages (e.g., performance::check_clusterstructure) return 1-H, where values close to 0 indicate clusterability. Always check the documentation of the specific implementation you are using.

Breaking change: factoextra uses the corrected Hopkins statistic formula (Wright 2022). Results differ from legacy factoextra and a one-time warning is emitted. Set options(factoextra.warn_hopkins = FALSE) to silence the warning.

For large datasets, nearest-neighbor distances are computed with a low-memory fallback when the full pairwise matrix would exceed getOption("factoextra.hopkins.max_matrix_cells", 2e7) cells. Only the sampled row's own occurrence is excluded from its nearest-neighbor search; a duplicated row therefore remains a valid zero-distance neighbor.

VAT (Visual Assessment of Cluster Tendency): The VAT displays clustering tendency by showing square-shaped dark (or colored) blocks along the diagonal in a VAT image.

Value

A list containing:

hopkins_stat	The Hopkins statistic.
plot	The ordered dissimilarity image generated by fviz_dist(), or NULL when graph = FALSE.

Author(s)

Alboukadel Kassambara [e-mail]

See Also

fviz_dist. Online tutorial: Assessing Clustering Tendency in R.

Examples

data(iris)

# Silence the one-time compatibility warning in examples
old_hopkins_warn <- getOption("factoextra.warn_hopkins")
options(factoextra.warn_hopkins = FALSE)

# Clustering tendency
gradient_col = list(low = "steelblue", high = "white")
get_clust_tendency(iris[,-5], n = 50, gradient = gradient_col)
   
# Random uniformly distributed dataset
# (without any inherent clusters)
set.seed(123)
random_df <- apply(iris[, -5], 2, 
                   function(x){runif(length(x), min(x), max(x))}
                   )
get_clust_tendency(random_df, n = 50, gradient = gradient_col)
options(factoextra.warn_hopkins = old_hopkins_warn)

factoextra documentation built on July 24, 2026, 9:06 a.m.