fcluster
First introduced in version: 3.00.5.1
Syntax
fcluster(Z, t, [criterion='inconsistent'], [depth=2], [R],
[monocrit])
Details
Forms flat clusters from the hierarchical clustering defined by the linkage matrix Z.
The linkage matrix Z, returned by the linkage function, describes
the complete tree structure from n original observations to a single root
node. fcluster partitions this tree into several disjoint flat
clusters based on the criterion specified by criterion and the threshold
t, and returns the cluster label for each original observation.
Parameters
Z A numeric matrix specifying the linkage matrix. It must have shape (n-1) ×
4, where n is the number of original observations. It is typically generated by the
linkage function.
t A numeric scalar.
-
When criterion is “inconsistent”, “distance”, or “monocrit”, t specifies the threshold used to form flat clusters.
-
When criterion is “maxclust” or “maxclust_monocrit”, t specifies the maximum number of clusters and must be a positive integer greater than or equal to 1.
criterion (optional) A string scalar specifying the criterion used to form flat clusters.
-
“inconsistent” (default): Thresholds the inconsistency statistics.
-
“distance”: Thresholds the cophenetic distance.
-
“maxclust”: Finds a minimum threshold so that no more than t clusters are formed.
-
“monocrit”: Thresholds a user-defined monotonic statistic monocrit.
-
“maxclust_monocrit”: Finds a threshold on monocrit so that no more than t clusters are formed.
depth (optional) A positive integer scalar. It is only effective when
criterion='inconsistent' and R is not provided. It specifies
the maximum depth used to compute inconsistency matrix. The default is 2.
R (optional) A numeric matrix specifying the inconsistency matrix. Used only when criterion is "inconsistent".
-
If R is not specified, the function computes the inconsistency matrix internally based on Z and depth.
-
If R is specified, its shape must be (n - 1) × 4, where R[i, 3] specifies the inconsistency coefficient of the i-th non-leaf cluster.
monocrit (optional) A numeric vector of length n - 1. Required when criterion is "monocrit" or "maxclust_monocrit".
-
monocrit[i] specifies the statistic associated with the non-leaf cluster numbered n + i.
-
For "maxclust_monocrit", the monocrit must satisfy non-strict monotonicity on the tree: if the non-leaf cluster n + j is a descendant of the non-leaf cluster n + i, then monocrit[i] >= monocrit[j] must hold.
Returns
Returns an INT vector of length n, where n is the number of original observations. Cluster labels are numbered starting from 1. The i-th element indicates the cluster label assigned to the i-th original observation.
Examples
Example 1: Partitioning based on distance threshold (distance)
X = [1.0, 2.0, 3.0]
Z = linkage(X)
fcluster(Z, t=1.5, criterion="distance")
// output: [1, 1, 2]With a distance threshold of 1.5, the first two observations are assigned to the same cluster because the distance between them is smaller than the threshold, while the third observation forms a separate cluster.
X = [1.0, 2.0, 3.0]
Z = linkage(X)
fcluster(Z, t=2, criterion="maxclust")
// output: [1, 1, 2]When the maximum number of clusters is set to 2, the function automatically chooses an appropriate cut level so that the final result contains no more than two clusters.
Example 3: Using the default inconsistency criterion (inconsistent). If criterion is not explicitly specified, inconsistent is used by default. In this example, all three observations are assigned to the same cluster under the default inconsistency-based rule.
X = matrix(0.0 0.0, 0.0 4.0, 3.0 0.0)
Z = linkage(X, method="single", metric="euclidean")
fcluster(Z, 1.0)
// output: [1, 1, 1]Z = linkage([1.0, 2.0, 3.0])
monocrit = [1.0, 2.0]
fcluster(Z, t=1.5, criterion="monocrit", monocrit=monocrit)
// output: [1, 1, 2]Related functions: linkage