Clustering in Python: profile wines by chemistry¶
Use a predictive clustering tree to group wines by measurements a lab can inspect. The output is a leaf ID, a rule and a profile. A lab could investigate an unexpected shift in the size of a segment across production batches.
1. Get the data and choose the features¶
Save OpenML Wine Quality 46964 to datasets/wine_quality.parquet. The 6,497 records come from the UCI Wine Quality collection. Use four numeric measurements. Keep median_wine_quality and wine_color out of fitting. Those columns can help interpret groups later.
PCT splits to reduce the variation of numeric features inside its leaves. The measurements have different units, so give them comparable scales using training means and standard deviations. Keep the original units for the report. Scaling is an explicit choice for this similarity objective.
2. Fit, assign and profile¶
Run this from the repository root. The second split supports a refit check. Assign the review records with both models before comparing them.
import pandas as pd
from mltreelib import ClusterTree
df = pd.read_parquet("datasets/wine_quality.parquet").sample(frac=1, random_state=2026)
features = ["residual_sugar", "volatile_acidity", "alcohol", "chlorides"]
train, review = df.iloc[:2500], df.iloc[5000:].copy()
center = train[features].mean()
scale = train[features].std()
def design(frame):
return ((frame[features] - center) / scale).to_numpy().tolist()
tree = ClusterTree(kind="pct", max_depth=2, min_rows=150)
tree.fit(design(train), col_names=features)
review["segment"] = tree.predict(design(review))
print(review.groupby("segment")[features].median().round(3))
print(review["segment"].value_counts().sort_index())
print(tree.rules())
The full script refits on the other 2,500 wines and draws the figure.
3. Read the profiles and check stability¶
| Leaf | Review rows | Median residual sugar (g/L) | Median volatile acidity (g/L) | Median alcohol (%) |
|---|---|---|---|---|
| 0 | 715 | 2.1 | 0.260 | 10.9 |
| 1 | 303 | 2.2 | 0.580 | 10.0 |
| 2 | 350 | 12.0 | 0.265 | 9.3 |
| 3 | 129 | 9.7 | 0.280 | 11.0 |
The two lower-sugar groups differ on acidity. The higher-sugar groups differ on alcohol. Pairwise Jaccard agreement on the 1,497 review wines was 0.841 after refitting at depth two on the second training sample. This is one check with a shared training scale.
A scatter plot only shows two of the four input features. Use the profile panel to see how the segments differ across the full feature list. It displays each segment's median in units of the training standard deviation. For a rule review, convert a standardized threshold back to lab units using threshold * scale + center.
Report pairwise Jaccard agreement after refitting. It counts pairs assigned together in both fits as a fraction of pairs assigned together in either fit. It avoids matching arbitrary leaf IDs and excludes the usually large number of pairs separated by both fits. This tests the stability of one partition with fixed scaling. Before using the groups operationally, repeat with independent batches and compare against a simpler lab rule.
4. Choose an engine through ClusterTree¶
The following observations are from a small numeric, two-group synthetic check. They establish the interface paths exercised, not comparative model quality.
kind |
Training and prediction output checked | rules() in that check |
|---|---|---|
pct |
Training labels and new-row labels | Conditions, prototypes and support |
cltree |
Labels can include None for unassigned rows |
Bounding boxes and support |
hdbscan |
Training and new-row labels | Empty list |
urf |
Training and new-row labels | Empty list |
The sample check returned 8 PCT leaves, 3 CLTree groups plus unassigned points, 2 HDBSCAN groups, and a highly imbalanced URF assignment. These results depend on the data and settings. They do not rank the engines. Check whether a segment is stable and useful before assigning an action to it.
Missing values and categories: product gaps¶
The wrapper currently converts None to 0.0 for cltree, hdbscan and urf during fitting and prediction. This is implicit imputation and conflicts with the package's missing-data goal. Track it as a product gap. Do not assume those engines distinguish missing from a real zero. They also reject raw strings in the checked inputs.
PCT accepted raw categorical labels and missing numeric entries in a separate check. Its returned rules displayed category codes rather than the original labels. In that check, an unseen category and a missing category went to different leaves. Category-label rendering and unseen-category routing need further investigation before those rules become a business handoff.
For density and proximity methods, check scaling, distance choice and the meaning of an unassigned or noise label. For all kinds, test the actual new-row behavior and input schema that your workflow uses.
5. Run the controlled stability example¶
The synthetic clustering workflow lets you change the overlap between known generating groups. It uses 1,000 independent review rows and illustrates how a tree can split a single generating group into several leaves.
See Blockeel et al. on predictive clustering and the engine comparison.