Hierarchical clustering organizes data into a tiered tree structure by repeatedly merging the most similar items. Use this method when you want to explore the natural groupings in your dataset without pre-defining the number of groups, or when you need to see how smaller clusters combine into larger ones.
Understanding the Hierarchy
This method functions by grouping data points from the bottom up. It begins by treating each individual data point as its own cluster and then repeatedly joins the two most similar clusters together. This process continues until every data point is combined into one single, all-encompassing group.
The result is a sequence of mergers that can be visualized as a tree. Because the entire history of these combinations is preserved, you can choose to 'cut' the tree at different levels of detail depending on how many groups you need.
Defining Similarity
To group your data, the tool calculates the distance between items. You can choose different methods to define how clusters are linked. For example, using 'ward' linkage creates clusters that are balanced in size by minimizing variance, while 'complete' or 'average' linkage focuses on the distance between the furthest or average points of clusters, respectively.
You can also select different distance metrics to interpret your data. The default 'euclidean' metric measures the straight-line distance, which is ideal for standard numerical inputs. For data that is ranked or ordered, 'manhattan' distance provides an alternative way to calculate gaps between values.
Flexible Cutting Strategies
Once the tree is built, you decide how to group the final output. You can use 'maxclust' to tell the tool the exact number of groups you want to see, or you can use 'distance' to define a specific similarity threshold. If you choose the distance approach, the tool will group everything that falls within that specific proximity, automatically determining the total number of resulting clusters.
When to Choose Another Method
While hierarchical clustering is excellent for discovery, it is computationally intensive. If your dataset contains more than 5,000 rows, the processing time increases significantly. For larger datasets, other methods like K-means are often more efficient and performant.
Additionally, ensure your data is free of missing values before you begin, as the tool uses listwise deletion to ensure consistent comparisons across all features.
1 · Intent → method
An LLM picks cluster_hierarchical from a fixed catalog.
2 · Method → numbers
Deterministic Python engine runs the math. Same input → same output.
3 · Numbers → plain language
A second LLM translates the result into your domain’s vocabulary.
Do I need to decide how many clusters I want before running this?
No. One of the main benefits of hierarchical clustering is that it builds a complete tree of all possible groupings. You can choose to cut this tree at any level after the analysis is complete to see different numbers of clusters.
How is this different from K-means clustering?
K-means requires you to pick the number of groups (k) at the start and assigns points to them once. Hierarchical clustering builds a full hierarchy of relationships, allowing you to see how your data nests together, which is often more useful for exploratory analysis.
Tool input schema
Schema for cluster_hierarchical not exported yet (run pnpm export:registry).