You have customers, products, or transactions — and you suspect there are distinct groups hiding in the data, but you do not have labels telling you what those groups are. K-Means clustering finds them automatically. Upload a CSV with numeric features, and the algorithm partitions your data into coherent segments with cluster profiles, visualizations, and silhouette scores. No statistics degree required, no labels needed.
What Is K-Means Clustering?
K-Means is an unsupervised machine learning algorithm that groups similar data points together — without you telling it what the groups should look like. You give it data and a number of clusters (k), and it iteratively assigns each data point to the nearest cluster center, then recalculates the centers based on the assignments. After a few rounds, the clusters stabilize and you have k groups where the members within each group are as similar to each other as possible.
The classic example is customer segmentation. Suppose you have an e-commerce dataset with thousands of customers and you want to know: who are my best customers, who is at risk of leaving, and who only bought once? You could slice the data manually by revenue thresholds, but those cutoffs would be arbitrary. K-Means looks at the actual patterns — recency of last purchase, how often someone buys, how much they spend — and finds natural breakpoints. You might discover four segments: Champions who buy frequently and spend heavily, Loyal customers with steady mid-range spending, At-Risk customers who used to buy often but have gone quiet, and Lost customers who bought once a year ago and never returned.
The algorithm works by minimizing the total within-cluster variance. Think of it as finding k points in the feature space (the centroids) such that every data point is as close to its assigned centroid as possible. The result is compact, spherical clusters where each centroid represents the "average member" of that group. This makes interpretation straightforward — you can describe each cluster by looking at the centroid values and immediately understand what makes that group different.
When to Use K-Means Clustering
K-Means is the right tool when you want to discover structure in data where no predefined categories exist. The most common business applications include customer segmentation (grouping buyers by purchasing behavior for targeted marketing), product categorization (grouping SKUs by sales velocity, margin, and seasonality), market research (identifying audience segments from survey responses), and inventory management (grouping products by demand patterns to optimize stocking).
Use K-Means when your goal is exploratory — you are not predicting a specific outcome, you are trying to understand what natural groupings exist in your data. This is fundamentally different from classification, where you already have labeled examples and want to predict the label for new cases. With clustering, the labels do not exist yet. You are asking the data to tell you what the groups are.
K-Means is also valuable as a preprocessing step before building predictive models. Once you have identified customer segments, you can build separate churn models for each segment, or tailor pricing strategies per cluster. The segments become a new feature that captures complex multi-dimensional patterns in a single categorical variable.
In practice, K-Means works best when your clusters are roughly spherical and similar in size. If you suspect your groups have irregular shapes — say, a dense core of loyal customers surrounded by a scattered ring of occasional buyers — consider DBSCAN instead, which handles non-spherical clusters naturally.
What Data Do You Need?
You need a CSV with numeric columns — the features you want to cluster on. The module accepts one or more feature columns (mapped as feature_1, feature_2, and so on). Common setups include RFM features (recency, frequency, monetary value) for customer segmentation, or any set of numeric measurements that describe the entities you want to group.
Feature scaling matters. If one column is measured in dollars (range 0-10,000) and another in number of purchases (range 1-50), the dollar column will dominate the distance calculations and effectively ignore the purchase count. The module includes a scale_features parameter that standardizes all columns to the same scale before clustering. Leave this enabled unless your features are already on comparable scales.
The key decision is choosing k — how many clusters to create. If you do not know the right number, set k_clusters to auto (or leave it unset) and the module will evaluate a range from k_min to k_max, using the elbow method and silhouette analysis to recommend the best k. The elbow chart shows how the total within-cluster variance drops as k increases — the "elbow" where adding more clusters stops helping much is usually a good choice. The silhouette score measures how well-separated the clusters are, with higher scores indicating cleaner separation.
If you already know you want exactly four segments (say, based on business requirements), set k_clusters to 4 and the module will skip the search and cluster directly. The n_start parameter controls how many random starting configurations the algorithm tries — more starts reduce the chance of landing on a poor local solution. The default is usually sufficient, but increase it for critical analyses.
For reliable clustering, aim for at least 50 observations. K-Means can handle thousands or tens of thousands of rows efficiently. Very small datasets (under 30 rows) may not have enough variation to form meaningful clusters.
How to Read the Report
The report opens with an executive summary that names and describes each cluster in plain language — not just "Cluster 1" and "Cluster 2," but labels like "High-Value Champions" or "Dormant Buyers" based on the feature profiles. This gives you an immediate, actionable understanding of what the algorithm found.
The Elbow Curve shows total within-cluster sum of squares (WSS) on the y-axis and number of clusters on the x-axis. As k increases, WSS always decreases — more clusters means tighter groups. The useful signal is where the curve bends sharply. Before the elbow, each additional cluster captures meaningful structure. After the elbow, you are splitting natural groups into arbitrary pieces. The recommended k is marked on the chart.
The Silhouette Analysis measures cluster quality. Each data point gets a silhouette coefficient between -1 and 1. A value near 1 means the point fits its cluster well and is far from neighboring clusters. A value near 0 means the point sits on the boundary between clusters. A negative value means the point may be assigned to the wrong cluster. The average silhouette score across all points summarizes overall cluster quality — above 0.5 is strong, 0.25 to 0.5 is reasonable, below 0.25 suggests the clusters are not well separated.
The Customer Clusters (PCA) card is the most visual section. Since your data may have many features, the report uses Principal Component Analysis to project everything down to two dimensions for plotting. Each point is a data record, colored by cluster assignment. Well-separated clusters appear as distinct clouds with minimal overlap. Overlapping clusters suggest the groups share many characteristics and may be hard to treat differently in practice.
The Cluster Profiles card is where interpretation happens. It shows the average value of each feature within each cluster, often as a heatmap or table. This is how you understand what makes each cluster different — Cluster A has high recency and low frequency (lapsed customers), Cluster B has low recency and high monetary value (active big spenders), and so on. The Cluster Summary provides the size of each cluster (number and percentage of data points), and the Top Customers by Segment card lists specific examples from each group so you can validate the clustering against real records you recognize.
When to Use Something Else
If your clusters are not roughly spherical — for example, you have a dense core of normal transactions surrounded by scattered outliers — DBSCAN is a better fit. DBSCAN finds clusters of arbitrary shape and automatically identifies noise points (outliers) without requiring you to specify k upfront. It discovers the number of clusters from the data itself.
If you want a hierarchy of clusters — understanding not just "there are four segments" but how those segments relate to each other (are segments A and B more similar to each other than to C?) — hierarchical clustering with a dendrogram gives you that tree structure. You can cut the tree at different levels to get different numbers of clusters.
If your data has many features (dozens or hundreds of columns), consider running PCA first to reduce dimensionality, then clustering on the principal components. This removes noise from redundant features and often produces cleaner clusters. The K-Means report already uses PCA for visualization, but running PCA as a preprocessing step and clustering on fewer components can improve results with high-dimensional data.
If you want "soft" cluster assignments — where each data point gets a probability of belonging to each cluster rather than a hard assignment — Gaussian Mixture Models (GMM) are the natural extension. GMM treats each cluster as a Gaussian distribution and returns membership probabilities, which is useful when boundaries between groups are genuinely fuzzy.
For anomaly detection specifically, consider Isolation Forest instead. While K-Means can surface outliers (points far from any centroid), Isolation Forest is purpose-built for finding anomalies and handles them more robustly.
The R Code Behind the Analysis
Every report includes the exact R code used to produce the results — reproducible, auditable, and citable. This is not AI-generated code that changes every run. The same data produces the same analysis every time.
The analysis uses kmeans() from base R for the core clustering, with scale() for feature normalization. Optimal k selection uses the elbow method (within-cluster sum of squares) and silhouette() from the cluster package. The PCA visualization is built with prcomp() from base R, and cluster profile plots use factoextra for publication-quality graphics. These are the same functions used in peer-reviewed machine learning research and industry data science — no custom implementations, no black boxes. The n_start parameter runs the algorithm multiple times with different random seeds and keeps the best result, ensuring stability. Every step is visible in the code tab of your report, so you or a data scientist can verify exactly what was done.