Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteiTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
scipy.cluster.hierarchy.fcluster turns an existing hierarchical clustering into one flat cluster label per observation. The key decision is criterion: it determines what t means, whether that is a statistical threshold or a maximum number of clusters.
What fcluster does
SciPy’s v1.18.0 API reference describes fcluster as forming flat clusters from a linkage matrix. The function takes the hierarchy encoded in Z and returns an array T with one label for each original observation; T[i] is the flat-cluster number assigned to observation i. See the SciPy fcluster reference.
How the linkage matrix fits into the workflow
fcluster does not build the hierarchy. First, scipy.cluster.hierarchy.linkage creates a linkage matrix, conventionally named Z. It accepts either observation vectors or a condensed pairwise-distance vector and returns an (n-1) × 4 matrix. Each row records the two clusters merged, the distance between them, and the number of original observations in the resulting cluster. The SciPy linkage reference documents single, complete, average, weighted, centroid, median, and Ward methods.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Think of the task as two stages: the distance representation and linkage method determine the hierarchy; fcluster then cuts that hierarchy according to a selected rule. Changing the cut criterion does not undo the choices used to create Z.
#1 Best Overall
Choose a criterion before interpreting t
The value of t is not always a distance. Its meaning comes from criterion, whose default is 'inconsistent'.
| Criterion | What t means |
How the cut works |
|---|---|---|
'inconsistent' (default) |
Inconsistency threshold | Keeps a node and its descendants together when their inconsistency values meet the threshold; if no non-singleton node qualifies, observations remain separate. |
'distance' |
Cophenetic-distance threshold | Groups observations only when their within-cluster cophenetic distance does not exceed t. |
'maxclust' |
Maximum cluster count requested | Finds a distance threshold that produces no more than t clusters; it does not promise exactly that many. |
'monocrit' |
Threshold on a supplied monotonic criterion | Forms clusters according to the threshold rule for the supplied statistic. |
'maxclust_monocrit' |
Maximum cluster count requested | Minimizes the monotonic-statistic threshold while producing no more than t clusters. |
Use 'distance' when you have a meaningful cophenetic-distance ceiling, 'maxclust' when you need an upper bound on the number of groups, and 'inconsistent' when the cut should depend on inconsistency statistics. The two monocrit options are for cases where you have constructed the relevant statistic and can meet its monotonicity requirement.
Build a hierarchy and assign labels
This example builds a Ward hierarchy from pairwise distances, then asks for no more than three flat clusters:
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, t=3 is a requested maximum cluster count, not a distance cutoff of three. The returned labels array has one cluster identifier per row in X. For an example using a distance criterion, SciPy’s API reference illustrates how increasing t can move from many singleton clusters through intermediate groupings to one cluster. That example demonstrates behavior on its data; it is not a general recommendation for a threshold value.
Parameters and input requirements
Zmust be a valid linkage matrix, normally returned bylinkageor an equivalent compatible representation.tis interpreted according tocriterion; it is a cluster-count bound only for'maxclust'and'maxclust_monocrit'.criterionselects the cutting rule and defaults to'inconsistent'.depthsets the maximum depth used to calculate inconsistency, defaults to2, and has no meaning for the other criteria.Rsupplies the inconsistency matrix for'inconsistent'; SciPy computes it if omitted.monocritmust containn-1values and be monotonic over the hierarchy when used with amonocritcriterion.
The full signatures and parameter details are in the SciPy API reference.
Common mistakes to avoid
- Reading
tas a distance for every criterion. For eithermaxclustcriterion, it requests an upper bound on the cluster count. - Expecting exactly the requested count from
'maxclust'. Its documented result is no more thantclusters. - Passing a non-monotonic
monocritarray. The monotonicity condition is part of the input contract. - Tuning the cut without checking how
Zwas built. The distance representation and linkage method shape the hierarchy beforefclusterapplies its rule. - Copying an example threshold as a universal setting. A useful distance threshold depends on the distances and linkage in your own data.
Version and array-backend considerations
The SciPy v1.18.0 reference labels its Python Array API support experimental. It lists NumPy on CPU, PyTorch on CPU, JAX on CPU without JIT, and Dask on CPU with graph computation; the listed CuPy, PyTorch, and JAX GPU combinations are unsupported. Check the reference for your installed SciPy version and backend before relying on this support, since these details are version-sensitive.
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.
