CreateGaussianMixtureClusters — Analysis Tool Box

Introduction

Hard clustering forces every observation into exactly one group, but real segments often overlap — a customer can be 60% "bargain hunter" and 40% "loyal regular." CreateGaussianMixtureClusters models the data as a mixture of Gaussian distributions and returns, for every observation, a probability of belonging to each cluster rather than a single rigid label. When the number of clusters isn't specified, it uses BIC/AIC criteria to find the count that best balances fit against complexity, so you don't have to guess.

Teaching Note

Gaussian Mixture Model clustering is essential for:

Customer segmentation with overlapping behavioral patterns
Anomaly detection and outlier identification
Market segmentation with fuzzy boundaries between segments
Image segmentation and computer vision applications
Density estimation and generative modeling
Bioinformatics and gene expression analysis
Financial risk profiling with probabilistic group membership
Natural language processing and topic modeling

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_numeric_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 used. Defaults to None.
`number_of_clusters`	`None`	Number of Gaussian components (clusters) to fit. If None, the function automatically determines the optimal number (1-12) using BIC minimization. Defaults to None.
`column_name_for_clusters`	`'Gaussian Mixture Cluster'`	Name for the new column containing cluster assignments (as strings). Defaults to 'Gaussian Mixture Cluster'.
`scale_clustering_column_values`	`False`	Whether to standardize features to zero mean and unit variance before clustering. Recommended when features have different scales. Defaults to False.
`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. Defaults to False.
`show_cluster_summary_plots`	`True`	Whether to generate pair plots showing the relationship between clustering variables, color-coded by cluster assignment. Defaults to True.
`sns_color_palette`	`'Set1'`	Seaborn color palette name for cluster visualization. Options include 'Set1', 'Set2', 'husl', 'colorblind', etc. Defaults to 'Set1'.
`summary_plot_size`	`(20, 20)`	Figure size for the summary pair plots as a tuple of (width, height) in inches. Defaults to (20, 20).
`random_seed`	`412`	Random seed for reproducibility of the GMM algorithm. Defaults to 412.
`maximum_iterations`	`300`	Maximum number of expectation-maximization iterations for model convergence. Defaults to 300.

Returns

A pandas DataFrame — the original data with a cluster assignment column (string labels for the most likely cluster) plus one probability column per cluster (0–1 membership score, named [column_name_for_clusters]_[i] Probability). Rows with missing values in clustering columns are excluded and will have NaN in the new columns.

Example

python

from analysistoolbox.descriptive_analytics import CreateGaussianMixtureClusters
import pandas as pd

# Customer segmentation with automatic cluster selection
customer_df = pd.DataFrame({
    'customer_id': range(1, 201),
    'annual_spend': [1000 + i * 50 for i in range(200)],
    'visit_frequency': [5 + i % 30 for i in range(200)],
    'avg_basket_size': [50 + i % 100 for i in range(200)]
})
segmented_df = CreateGaussianMixtureClusters(
    customer_df,
    list_of_numeric_columns_for_clustering=['annual_spend', 'visit_frequency', 'avg_basket_size'],
    scale_clustering_column_values=True,
    show_cluster_summary_plots=True
)
# Automatically determines optimal clusters and shows membership probabilities