Flat clustering (fcluster) in SciPy - Step-by-Step Execution

Concept Flow - Flat clustering (fcluster)

Start with hierarchical clustering result

↓

Choose a threshold or criterion

↓

Call fcluster to assign cluster labels

↓

Get flat clusters as output

↓

Use clusters for analysis or visualization

Flat clustering cuts a hierarchical clustering tree at a chosen level to assign cluster labels to data points.

Execution Sample

SciPy

from scipy.cluster.hierarchy import linkage, fcluster
import numpy as np

X = np.array([[1,2],[2,2],[8,7],[8,8]])
Z = linkage(X, 'single')
clusters = fcluster(Z, t=3, criterion='distance')

This code clusters 4 points hierarchically and then cuts the tree at distance 3 to assign flat cluster labels.

Execution Table

Step	Action	Input/Condition	Output/Result
1	Create data points	X = [[1,2],[2,2],[8,7],[8,8]]	X array created
2	Compute linkage	method='single'	Z linkage matrix with merges and distances
3	Call fcluster	Z linkage, t=3, criterion='distance'	Assign cluster labels based on distance threshold
4	Output clusters	clusters array	[1, 1, 2, 2]
5	End	All points assigned clusters	Flat clustering complete

💡 All points assigned to clusters based on distance threshold 3

Variable Tracker

Variable	Start	After linkage	After fcluster	Final
X	[[1,2],[2,2],[8,7],[8,8]]	[[1,2],[2,2],[8,7],[8,8]]	[[1,2],[2,2],[8,7],[8,8]]	[[1,2],[2,2],[8,7],[8,8]]
Z	None	Linkage matrix with shape (3,4)	Same	Same
clusters	None	None	[1,1,2,2]	[1,1,2,2]

Key Moments - 3 Insights

Why do some points get the same cluster label?

Because their distance in the linkage tree is below the threshold t=3, so fcluster groups them together (see execution_table step 4).

What does the 't' parameter control in fcluster?

It sets the maximum distance to cut the hierarchical tree; points joined below this distance share the same cluster label (execution_table step 3).

Why do we need the linkage matrix Z before calling fcluster?

Z contains the hierarchical clustering info (merges and distances) that fcluster uses to assign flat clusters (execution_table step 2 and 3).

Visual Quiz - 3 Questions

Look at the execution_table at step 4, what cluster label is assigned to the point [8,8]?

A 3

B 1

C 2

D 4

💡 Hint

Check the clusters array in execution_table step 4; the last point corresponds to label 2.

At which step does the hierarchical linkage matrix get created?

A Step 2

B Step 3

C Step 1

D Step 4

💡 Hint

Look at execution_table step 2 where linkage is computed.

If we change t=1 in fcluster, what happens to the clusters output?

A All points get the same cluster label

B Each point gets a unique cluster label

C Clusters remain the same as with t=3

D fcluster raises an error

💡 Hint

With t=1, only points joined at distance <=1 are clustered together; since some points are farther apart, this results in more clusters, possibly unique labels per point.

Concept Snapshot

Flat clustering with fcluster:
- Input: linkage matrix from hierarchical clustering
- Parameter t: distance threshold to cut tree
- Output: cluster labels array
- Points joined below t share cluster
- Use for simple cluster assignment from hierarchy

Full Transcript

Flat clustering with fcluster takes a hierarchical clustering result and cuts it at a chosen distance threshold to assign cluster labels. First, data points are clustered hierarchically using linkage. Then, fcluster uses the linkage matrix and a threshold t to assign flat cluster labels. Points connected below the threshold get the same label. This method helps convert a hierarchical tree into simple clusters for analysis or visualization.

Practice

1. What is the main purpose of the fcluster function in scipy's hierarchical clustering?

easy

A. To cut a hierarchical cluster tree into flat clusters based on a threshold

B. To compute the distance matrix between data points

C. To perform dimensionality reduction before clustering

D. To normalize data before clustering

Solution

1. Step 1: Understand hierarchical clustering output

   Hierarchical clustering produces a tree (dendrogram) showing nested clusters.

2. Step 2: Role of fcluster

   fcluster cuts this tree at a chosen threshold to form flat, non-overlapping clusters.

3. Final Answer:

   To cut a hierarchical cluster tree into flat clusters based on a threshold -> Option A

4. Quick Check:

   Flat clustering = cutting tree with threshold [OK]

Hint: Remember: fcluster cuts dendrogram into flat groups [OK]

Common Mistakes:

• Confusing fcluster with distance calculation
• Thinking fcluster normalizes data
• Assuming fcluster reduces dimensions

2. Which of the following is the correct syntax to assign flat clusters using fcluster with a distance threshold of 1.5 from a linkage matrix Z?

easy

A. clusters = fcluster(Z, threshold=1.5, criterion='distance')

B. clusters = fcluster(Z, 1.5, method='distance')

C. clusters = fcluster(Z, 1.5, criterion='distance')

D. clusters = fcluster(Z, 1.5, criterion='maxclust')

Solution

1. Step 1: Check fcluster parameters

   The function signature is fcluster(Z, t, criterion='distance') where t is the threshold.

2. Step 2: Identify correct usage

   clusters = fcluster(Z, 1.5, criterion='distance') uses t=1.5 and criterion='distance', which is correct syntax.

3. Final Answer:

   clusters = fcluster(Z, 1.5, criterion='distance') -> Option C

4. Quick Check:

   Threshold = 1.5, criterion = 'distance' [OK]

Hint: Use t for threshold and criterion='distance' in fcluster [OK]

Common Mistakes:

• Using 'method' instead of 'criterion'
• Passing threshold as keyword 'threshold'
• Using wrong criterion like 'maxclust' for distance cut

3. Given the linkage matrix Z = [[0, 1, 0.5, 2], [2, 3, 1.5, 2], [4, 5, 2.5, 4]], what is the output of fcluster(Z, 1.0, criterion='distance')?

medium

A. [1 1 1 1]

B. [1 2 3 4]

C. [1 2 2 3]

D. [1 1 2 3]

Solution

1. Step 1: Understand linkage matrix and threshold

   The linkage matrix Z shows merges with distances: 0.5, 1.5, 2.5. Threshold is 1.0.

2. Step 2: Assign clusters by cutting at distance 1.0

   Clusters merge if distance ≤ 1.0. The first merge (0.5) joins points 0 and 1 into cluster 1. The second merge (1.5 > 1.0) does not merge points 2 and 3, so point 2 gets cluster 2 and point 3 gets cluster 3.

3. Final Answer:

   [1 1 2 3] -> Option D

4. Quick Check:

   Distance ≤ 1.0 merges points 0 and 1 only [OK]

Hint: Cut dendrogram at threshold; merges below threshold cluster together [OK]

Common Mistakes:

• Merging clusters above threshold
• Assigning all points to one cluster
• Misreading linkage matrix format

4. You run the code clusters = fcluster(Z, 2, criterion='maxclust') but get an error. What is the likely cause?

medium

A. The linkage matrix Z is not defined or invalid

B. The criterion 'maxclust' requires an integer number of clusters, but 2 is passed as a float

C. The threshold parameter must be a float when using 'maxclust'

D. The criterion 'maxclust' expects the threshold to be the maximum cluster distance

Solution

1. Step 1: Check parameter types for 'maxclust'

   When using criterion='maxclust', the threshold t must be an integer specifying the number of clusters.

2. Step 2: Identify common error

   If Z is not defined or invalid, fcluster raises an error unrelated to parameter types.

3. Step 3: Analyze options

   The criterion 'maxclust' requires an integer number of clusters, but 2 is passed as a float is incorrect because 2 as an integer or float is accepted; The threshold parameter must be a float when using 'maxclust' is wrong because threshold can be int; The criterion 'maxclust' expects the threshold to be the maximum cluster distance is false because 'maxclust' uses number of clusters, not distance.

4. Final Answer:

   The linkage matrix Z is not defined or invalid -> Option A

5. Quick Check:

   Undefined Z causes error, not threshold type [OK]

Hint: Ensure linkage matrix Z is valid before calling fcluster [OK]

Common Mistakes:

• Passing float instead of int for maxclust threshold
• Misunderstanding criterion parameter
• Ignoring linkage matrix validity

5. You have a dataset with 10 points clustered hierarchically. You want exactly 3 clusters. Which fcluster call correctly achieves this?

hard

A. fcluster(Z, 0.5, criterion='inconsistent')

B. fcluster(Z, 3, criterion='maxclust')

C. fcluster(Z, 0.5, criterion='maxclust')

D. fcluster(Z, 3, criterion='distance')

Solution

1. Step 1: Understand criteria for exact cluster count

   To get exactly 3 clusters, use criterion='maxclust' with t=3 specifying number of clusters.

2. Step 2: Analyze options

   fcluster(Z, 3, criterion='maxclust') correctly uses maxclust with 3 clusters. fcluster(Z, 3, criterion='distance') uses distance criterion which does not guarantee exact cluster count. Options A and C use incorrect thresholds or criteria.

3. Final Answer:

   fcluster(Z, 3, criterion='maxclust') -> Option B

4. Quick Check:

   maxclust + t=number of clusters = exact clusters [OK]

Hint: Use criterion='maxclust' with t = desired cluster count [OK]

Common Mistakes:

• Using distance criterion to get exact cluster count
• Passing float threshold for maxclust
• Confusing inconsistent criterion with maxclust