Recommended Free Tools
Use scipy.cluster.hierarchy.fcluster to turn an existing linkage matrix into one flat-cluster label for each original observation. The key choice is criterion: it determines whether t is an inconsistency threshold, a cophenetic-distance threshold, or a maximum cluster count.
What `fcluster` returns
The SciPy v1.18.0 API reference describes fcluster as forming flat clusters from the hierarchical clustering defined by a linkage matrix. Its output is an array of length n, where T[i] is the cluster identifier assigned to original observation i. The identifiers are labels, not measurements of cluster quality or distance.
As an Amazon Associate I earn from qualifying purchases.
The function cuts a hierarchy that already exists; it does not build that hierarchy. In the usual workflow, linkage creates the hierarchy and fcluster turns it into flat assignments.
Build the linkage matrix first
Z is normally the (n - 1) × 4 matrix returned by scipy.cluster.hierarchy.linkage. Each row records the two cluster indices merged, the distance at which they are merged, and the number of original observations in the resulting cluster. linkage accepts observation vectors or a condensed pairwise-distance vector.
#1 Best Overall
from scipy.cluster.hierarchy import fcluster, linkage
from scipy.spatial.distance import pdist
Z = linkage(pdist(X), method="ward")
labels = fcluster(Z, t=3, criterion="maxclust")Here, X contains the observations. labels has one cluster identifier per row of X. Since the criterion is maxclust, t=3 requests no more than three clusters; it is not a distance cutoff of three.
The hierarchy itself depends on how it was made. SciPy documents linkage methods including single, complete, average, weighted, centroid, median, and Ward, each of which defines cluster distance differently. The choice of metric and linkage method shapes the hierarchy before fcluster applies its cut; changing the cut criterion does not undo those upstream choices. See the SciPy linkage reference.
Choose a criterion, then interpret `t`
The most important distinction is whether you have a meaningful statistic threshold or a desired upper bound on the number of groups. The meaning of t depends on the selected criterion.
criterion |
What t means |
How the cut works |
|---|---|---|
inconsistent (default) |
An inconsistency threshold | Keeps a node and its descendants together when their inconsistency values are no greater than t. If no non-singleton node qualifies, observations remain separate. |
distance |
A cophenetic-distance threshold | Groups observations only when their within-cluster cophenetic distance does not exceed t. |
maxclust |
The maximum number of clusters requested | Finds a distance threshold that produces no more than t clusters; it does not promise exactly t. |
monocrit |
A threshold on a supplied monotonic criterion | Forms clusters according to whether the supplied statistic meets the threshold rule. |
maxclust_monocrit |
The maximum number of clusters requested | Minimizes the monotonic-statistic threshold while producing no more than t clusters. |
Use distance when the desired rule is an interpretable cophenetic-distance ceiling. Use maxclust when the primary requirement is a bound on group count. Choose inconsistent when the cut should depend on inconsistency statistics. The monocrit options are for cases where you have constructed the relevant statistic and can ensure it is monotonic over the hierarchy.
Set a threshold for your own hierarchy
With criterion="distance", raising t generally permits more merges: a cut can move from many singleton clusters through intermediate groupings to one cluster. The threshold’s useful scale depends on the distances and linkage method that produced your particular Z. Values shown in SciPy examples illustrate behavior on their example data; they are not universal recommendations.
Before choosing a cut, decide whether your requirement is a distance ceiling or a maximum group count, identify the statistic the criterion uses, and check that the linkage method and distance representation are appropriate for the data.
Parameters and input requirements
Zmust be a valid linkage matrix produced bylinkageor a compatible representation.depthsets the maximum depth used to calculate inconsistency; it defaults to2and has no meaning for criteria other thaninconsistent.Rsupplies the inconsistency matrix for theinconsistentcriterion. If omitted, SciPy computes it.monocritmust be an array of lengthn - 1, with values monotonic over the hierarchy.
For the full signature, criterion definitions, and parameter details, consult the SciPy v1.18.0 fcluster API reference.
Free tools Windows power users keep installed
One-click scans. No signup required.
Common mistakes to avoid
- Reading every
tas a distance: withmaxclustandmaxclust_monocrit, it is a requested maximum cluster count. - Expecting exactly the requested count:
maxclustguarantees no more thantclusters, not necessarily exactly that many. - Passing a non-monotonic statistic: the
monocritinput must satisfy the monotonicity requirement. - Choosing a cut without regard to how
Zwas built: the distance representation and linkage method have already shaped which merges the hierarchy contains. - Copying an example threshold as a rule: an example value is tied to its example hierarchy, not a general setting for other data.
Version and array-backend note
The SciPy v1.18.0 reference marks Python Array API support as experimental. It lists NumPy on CPU; PyTorch on CPU; JAX on CPU without JIT; and Dask on CPU with graph computation. It lists no GPU support for the CuPy, PyTorch, or JAX combinations covered there. Backend behavior can depend on the installed SciPy version, so check the reference for that version before relying on a backend combination.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
