HierarchicalClustering: Unified Wrapper for Hierarchical Clustering

In FCPS: Fundamental Clustering Problems Suite

Unified Wrapper for Hierarchical Clustering

Description

Provides a unified interface for hierarchical clustering from either raw numeric data or precomputed distances.

The wrapper dispatches to the appropriate lower-level implementation according to the selected clustering Type and the form of DataOrDistances. Ordinary agglomerative methods, generalized Ward pseudo-inertia clustering, and several specialized hierarchical methods are supported.

Usage

HierarchicalClustering(
  DataOrDistances,
  ClusterNo = 0,
  Type = "SingleL",
  Fast = TRUE,
  PlotIt=FALSE,
  Data,
  ...
)

Arguments

DataOrDistances	Either nonsymmetric [1:n,1:d] numerical matrix of a dataset to be clustered. It consists of n cases of d-dimensional data points. Every case has d attributes, variables or features. or symmetric [1:n,1:n] distance matrix, e.g. as.matrix(dist(Data,method))
ClusterNo	Number of clusters. For the ordinary hierarchical methods and "WardPseudo", ClusterNo = 0 delegates complete-hierarchy/dendrogram handling to the lower-level function. A positive value cuts the hierarchy into the requested number of groups. For "HDBSCAN", values greater than one explicitly cut the returned hierarchy, while smaller values use the automatic clustering produced by the HDBSCAN implementation.
Type	Character scalar selecting the hierarchical clustering method. The following public choices are supported: "Ward": Ward hierarchical clustering using the Ward.D2 criterion. This is the historical/default Ward interpretation in the wrapper. "WardPseudo": generalized Ward-like clustering based on dissimilarity pseudo-inertia. It is intended for precomputed, potentially non-Euclidean dissimilarities, for example Minkowski p = 6 distances. The input must be the original unsquared dissimilarities. "SingleL": single-linkage clustering. "CompleteL": complete-linkage clustering. "AverageL": average-linkage clustering (UPGMA). "WPGMA": weighted pair-group method using arithmetic averages. "MedianL": median linkage (WPGMC). "CentroidL": centroid linkage (UPGMC). "Minimax": minimax-linkage clustering through MinimaxLinkageClustering(). "MinEnergy": minimum-energy hierarchical clustering through MinimalEnergyClustering(). "Gini": Genie/Gini-based clustering through GenieClustering(). "Sparse": sparse hierarchical clustering through SparseClustering(..., Type = "Hierarchical"). "HDBSCAN": hierarchical density-based clustering through HierarchicalDBSCAN(). Default is "SingleL".
Fast	Logical scalar. Passed to the ordinary lower-level hierarchical clustering implementations. If supported, a faster implementation such as fastcluster may be used. Specialized methods manage their own implementations. Default is TRUE.
PlotIt	If TRUE and ClusterNo > 0, plots the dendrogram using ClusterDendrogram. If TRUE and ClusterNo = 0, plots the complete dendrogram using base R graphics. The default is FALSE.
Data	Legacy alias for DataOrDistances. It is used only when DataOrDistances is missing.
...	Further arguments passed to the selected lower-level clustering function.

Details

Input dispatch

The wrapper distinguishes raw data from precomputed distances or dissimilarities.

A dist object is always treated as precomputed distances or dissimilarities. A square matrix or data frame is treated as a distance matrix only when it is numeric, finite, symmetric within numerical tolerance, has a zero diagonal, and is non-negative within tolerance. This reduces the risk of accidentally treating a square raw-data matrix as a distance matrix.

Precomputed distances or dissimilarities are sent to HierarchicalClusterDists(). Raw data are sent to HierarchicalClusterData().

WardPseudo

"WardPseudo" exposes the generalized Ward-like dissimilarity pseudo-inertia criterion implemented by HierarchicalClusterDists().

It is especially useful when the desired dissimilarity is not Euclidean. For example, Minkowski p = 6 dissimilarities can be calculated explicitly before clustering:

D6 <- stats::dist(scale(X), method = "minkowski", p = 6)

res <- HierarchicalClustering(
  D6,
  ClusterNo = 6,
  Type = "WardPseudo"
)

The supplied dissimilarities must be unsquared. "WardPseudo" is distinct from applying the ordinary legacy Ward method directly to raw non-Euclidean distances and is also distinct from de Amorim's Ward_p algorithm.

Specialized methods

The choices "MinEnergy", "Gini", "Minimax", "Sparse", and "HDBSCAN" are dispatched directly to their specialized implementations.

For "HDBSCAN", if ClusterNo > 1, the returned hierarchy is cut with stats::cutree(). Otherwise, the automatically selected classes from HierarchicalDBSCAN() are returned.

Backward compatibility

The argument Data remains available as a legacy alias for DataOrDistances. If neither is supplied, the function stops.

The public choice "Ward" retains its established meaning corresponding to Ward.D2 behavior. Use "WardPseudo" explicitly when the generalized dissimilarity pseudo-inertia criterion is desired.

Value

A method-specific list.

For ordinary hierarchical methods and "WardPseudo", the result is normally a list with components:

Cls	For ClusterNo > 0, a numerical vector of length n containing the classification. For ClusterNo = 0, usually NULL; some specialized methods may return automatically selected classes.
Dendrogram	Object of class "dendrogram".
Object	Underlying hierarchical clustering object, typically of class "hclust".

For "HDBSCAN", the result additionally contains OriginalObject, which stores the original object returned by HierarchicalDBSCAN().

Other specialized methods return the corresponding method-specific list from their lower-level implementation.

Note

The mathematical details of the generalized Ward pseudo-inertia criterion, including its height scale and relationship to Ward.D2, are documented in HierarchicalClusterDists.

Author(s)

Michael Thrun

See Also

HierarchicalClusterDists, HierarchicalClusterData, HierarchicalDBSCAN

Examples

## Not run: 
data("Hepta")

# Raw data with ordinary single linkage
res_single <- HierarchicalClustering(
  DataOrDistances = Hepta$Data,
  ClusterNo = 7,
  Type = "SingleL"
)

# Ward clustering from raw data
res_ward <- HierarchicalClustering(
  Hepta$Data,
  ClusterNo = 7,
  Type = "Ward"
)

# WardPseudo with explicitly computed Minkowski p = 6 dissimilarities
D6 <- stats::dist(
  scale(Hepta$Data),
  method = "minkowski",
  p = 6
)

res_pseudo <- HierarchicalClustering(
  D6,
  ClusterNo = 6,
  Type = "WardPseudo"
)

# HDBSCAN with automatic cluster-number selection
res_hdbscan <- HierarchicalClustering(
  Hepta$Data,
  Type = "HDBSCAN"
)

## End(Not run)

FCPS documentation built on Oct. 3, 2026, 9:06 a.m.