CreateHierarchicalClusters — Analysis Tool Box

Introduction

Before committing to a specific number of segments, it helps to see how observations naturally nest together at every level of granularity — which pairs merge first, and at what point merging stops making sense. CreateHierarchicalClusters builds that picture with agglomerative (bottom-up) clustering: it iteratively merges the closest points and clusters using Ward's linkage, producing a dendrogram that shows the full hierarchy of groupings. When you don't specify a cluster count, the dendrogram gives you the visual evidence to choose one, and the function defaults to 3 clusters to get you started.

Teaching Note

Hierarchical clustering is essential for:

Taxonomy creation and classification systems
Gene expression analysis and biological classification
Document clustering and text organization
Social network community detection
Image segmentation with nested structures
Customer segmentation with hierarchical market structures
Anomaly detection through isolation in the hierarchy
Exploratory data analysis to understand data structure at multiple scales

Parameters

Parameter	Default	Description
`dataframe`required	—	A pandas DataFrame containing the data to cluster. Rows with missing values in clustering columns will be excluded from the analysis.
`list_of_value_columns_for_clustering`	`None`	List of numeric column names to use as features for clustering. If None, all numeric columns in the DataFrame will be automatically selected. Defaults to None.
`number_of_clusters`	`None`	Number of clusters to create by cutting the dendrogram. If None, displays a dendrogram for visual inspection and defaults to 3 clusters. Defaults to None.
`column_name_for_clusters`	`'Hierarchical Cluster'`	Name for the new column containing cluster assignments (as strings). Defaults to 'Hierarchical Cluster'.
`random_seed`	`412`	Random seed for reproducibility (currently unused but maintained for API consistency). Defaults to 412.
`maximum_iterations`	`300`	Maximum iterations parameter (currently unused but maintained for API consistency). Defaults to 300.
`scale_clustering_column_values`	`True`	Whether to standardize features to zero mean and unit variance before clustering. Highly recommended for hierarchical clustering when features have different scales. Defaults to True.
`print_peak_to_peak_range_of_each_column`	`False`	Whether to print the peak-to-peak range of each clustering variable, useful for assessing scale differences before standardization. Defaults to False.
`show_cluster_summary_plots`	`True`	Whether to generate kernel density plots for each clustering variable, showing the distribution of values within each cluster. Defaults to True.
`color_palette`	`'Set2'`	Seaborn color palette name for cluster visualization. Options include 'Set1', 'Set2', 'Set3', 'Pastel1', 'Dark2', etc. Defaults to 'Set2'.
`caption_for_plot`	`None`	Optional caption text to display below each density plot. Defaults to None.
`data_source_for_plot`	`None`	Optional data source attribution text, appended to caption. Defaults to None.
`show_y_axis`	`False`	Whether to display the y-axis (density scale) on summary plots. Defaults to False.
`title_y_indent`	`1.1`	Vertical position for plot titles relative to axes. Defaults to 1.1.
`subtitle_y_indent`	`1.05`	Vertical position for plot subtitles relative to axes. Defaults to 1.05.
`caption_y_indent`	`-0.15`	Vertical position for plot captions relative to axes. Defaults to -0.15.
`summary_plot_size`	`(6, 4)`	Figure size for each summary density plot as a tuple of (width, height) in inches. Defaults to (6, 4).

Returns

A pandas DataFrame — the original data with one additional column containing cluster assignments as string labels (e.g., '0', '1', '2'). Rows with missing values in clustering columns are excluded and will have NaN in the cluster column.

Example

python

from analysistoolbox.descriptive_analytics import CreateHierarchicalClusters
import pandas as pd

# Customer segmentation with dendrogram-guided cluster selection
customer_df = pd.DataFrame({
    'customer_id': range(1, 101),
    'purchase_frequency': [5 + i % 20 for i in range(100)],
    'avg_order_value': [50 + i * 2 for i in range(100)],
    'customer_lifetime_value': [500 + i * 50 for i in range(100)]
})
segmented_df = CreateHierarchicalClusters(
    customer_df,
    list_of_value_columns_for_clustering=['purchase_frequency', 'avg_order_value', 'customer_lifetime_value'],
    scale_clustering_column_values=True,
    show_cluster_summary_plots=True
)
# Displays a dendrogram, defaults to 3 clusters, and shows per-cluster density plots