Minimal ML Examples Are Better as Review Maps Than Cheatsheets

The script looked like a cheatsheet until the third demo broke.

That is the best thing about it.

A compact ML examples file should not pretend to be a training platform. It should make the review surface smaller. In 516 lines, this one walks through supervised learning, unsupervised learning, linear regression, logistic regression, KNN, SVMs, naive Bayes, decision trees, voting ensembles, bagging, random forests, boosting, a small neural network, K-means, and PCA.

Every example uses synthetic data. Every split has a random_state. Several models are wrapped in a Pipeline. The optional LightGBM and XGBoost imports fail closed if those libraries are not installed.

That makes the file useful.

It also makes it dangerous if someone reads it as a ladder of models: first logistic regression, then trees, then random forests, then boosting, then neural networks. That is how teams accidentally turn model selection into a prestige sequence. The production question is not "which estimator sounds strongest." The production question is which task, metric, split, preprocessing boundary, and failure mode the team is ready to defend.

I have seen this go wrong in model reviews when the demo code was correct but the conversation drifted. The team compared algorithms before naming the decision. It reported accuracy before pricing false negatives. It clustered customers and forgot that clusters are hypotheses, not labels. It shipped preprocessing logic outside the artifact because the notebook was easier to read that way.

A minimal examples file can prevent those mistakes, but only if it is used as a map.

The Map Hiding In The Script#

The source file has the shape I want from a review aid: generate a small dataset, split it, fit the smallest plausible model, print one metric, and move on. The value is not the individual score. The value is the boundary each demo makes visible.

The first review question is task shape.

make_classification, make_regression, and make_blobs create different promises. A classifier demo asks whether labels can be separated. A regression demo asks how close a continuous prediction lands. A blob-and-clustering demo asks whether structure can be discovered without labels. Those are not interchangeable tasks.

The second review question is preprocessing.

The source uses StandardScaler with logistic regression, KNN, SVM, and the MLP. That is the right instinct because those models are sensitive to feature scale. A distance-based KNN model can change behavior when one feature is measured in dollars and another is measured in counts. An RBF SVM can turn scale into geometry. A neural network can waste training effort when inputs are badly scaled.

Tree models are different. A decision tree split like feature_7 <= 1.42 is usually not helped by standardization in the same way. Random forests and gradient-boosted trees can work on raw numeric scales more naturally. That does not mean they require no preprocessing. It means their preprocessing risk is more often about missing values, categorical encoding, leakage, and feature availability than about unit scale.

The third review question is the metric.

The script prints classification_report, roc_auc_score, RMSE, r2_score, and silhouette_score. That is a healthy spread because it refuses to make one metric carry every task. classification_report gives precision, recall, and F1 by class. AUC checks ranking behavior across thresholds. RMSE punishes large regression misses. R-squared compares against a baseline. Silhouette score measures cluster separation.

None of those metrics decides whether the model is useful. They decide which follow-up question is honest.

The Small Contract I Would Keep#

The most reusable part of the script is the boring part: deterministic synthetic data, an explicit split, and a pipeline where scale-sensitive preprocessing belongs to the model.

from sklearn.datasets import make_classification
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
 
RANDOM_STATE = 42
 
X, y = make_classification(
    n_samples=2000,
    n_features=20,
    n_informative=10,
    n_redundant=5,
    class_sep=1.0,
    random_state=RANDOM_STATE,
)
 
X_train, X_test, y_train, y_test = train_test_split(
    X,
    y,
    test_size=0.25,
    stratify=y,
    random_state=RANDOM_STATE,
)
 
model = Pipeline(
    steps=[
        ("scaler", StandardScaler()),
        ("classifier", LogisticRegression(max_iter=1000)),
    ],
)
 
model.fit(X_train, y_train)
scores = model.predict_proba(X_test)[:, 1]
labels = model.predict(X_test)

This is not production code. It has no schema contract, no feature store boundary, no model registry, no drift monitor, no calibration check, and no threshold policy.

It is still a good contract for a learning file because it forces the right first habits. Split before fit. Keep learned preprocessing inside the pipeline. Make the probability score available separately from the hard label. Set the random seed when reproducibility matters. Use stratify=y when the class balance should survive the split.

The tradeoff is that the example hides real input mess. Synthetic data has no stale categories, no late-arriving facts, no duplicate entities, no timestamp leakage, and no row-level permissions. That is acceptable for a cheatsheet only if the reader knows what was removed.

The Metric Helper Is A Review Tool#

The classification helper is small enough to be worth keeping inline:

def report_classification(name, y_true, y_pred, proba=None):
    print(f"\n[{name}]")
    print(classification_report(y_true, y_pred, digits=3))
    if proba is not None and len(np.unique(y_true)) == 2:
        auc = roc_auc_score(y_true, proba)
        print(f"AUC: {auc:.3f}")

That helper teaches an important separation. y_pred is the operating decision at a threshold. proba is the ranking or score before the threshold is chosen. A review should inspect both.

If the model flags customers for intervention, precision answers "how noisy is the work queue." Recall answers "how many true positives did we miss." AUC answers whether positives tend to rank above negatives across many thresholds. Those are related, but they are not substitutes.

For regression, the script originally used this pattern:

rmse = mean_squared_error(y_true, y_pred, squared=False)

In the local environment I checked, scikit-learn reported 1.7.2, and mean_squared_error no longer accepted squared=False. The signature was mean_squared_error(y_true, y_pred, *, sample_weight=None, multioutput="uniform_average"). The safer current helper is explicit:

from sklearn.metrics import r2_score, root_mean_squared_error
 
 
def report_regression(name, y_true, y_pred):
    rmse = root_mean_squared_error(y_true, y_pred)
    r2 = r2_score(y_true, y_pred)
    print(f"\n[{name}]  RMSE: {rmse:.3f} | R^2: {r2:.3f}")

That failure is not just a nuisance. It is the review value of running tiny examples. A cheatsheet that spans multiple model families also spans library assumptions. If it does not smoke-test under the current environment, it can teach stale syntax with a clean face.

The same risk appears in the bagging demo. Older examples often use BaggingClassifier(base_estimator=...). The local signature I checked expects estimator=....

The Estimator List Is Not A Ladder#

The source file covers many model families. That breadth is useful in a study file and misleading in a decision meeting.

Logistic regression is not the weak baseline because it is simple. It is often the best first classifier when the team needs stable probabilities, readable coefficients, and fast retraining. KNN is not primitive. It teaches the cost of distance, scaling, and prediction-time lookup. SVMs are not magic separators. They force a kernel and margin conversation. Naive Bayes is not naive in the insulting sense. It is a strong text and simple-probability baseline when its assumptions are acceptable enough.

Trees make split logic inspectable. Random forests reduce single-tree instability. Bagging teaches variance reduction. Boosting teaches sequential error correction and its cost: more knobs, more dependency surface, and more ways to overfit the validation loop. A small MLP teaches that neural networks are still estimators with preprocessing, iteration limits, and convergence behavior.

The right model family depends on the failure the team can tolerate.

If the team needs a transparent first pass, start with logistic regression or a shallow tree. If nonlinear interactions dominate and the feature table is reliable, compare forests and boosting. If the dataset is small and the metric is unstable across splits, adding a more powerful learner may only make the uncertainty harder to see. If prediction latency matters, KNN may be a bad fit even when its notebook score is fine.

Unsupervised Demos Need A Human Artifact#

The unsupervised sections use make_blobs, PCA, K-means, and silhouette score. That is the smallest useful path for showing clustering mechanics:

pca = PCA(n_components=2, random_state=RANDOM_STATE)
X_2d = pca.fit_transform(X)
 
km = KMeans(n_clusters=4, n_init=10, random_state=RANDOM_STATE)
labels = km.fit_predict(X_2d)
 
silhouette = silhouette_score(X_2d, labels)

This is a good demo because it makes the artifact visible: transformed coordinates, cluster labels, and one separation score.

It is not enough for a segmentation decision.

Clusters need names, examples, stability checks, and a reason to exist. A cluster is not a persona. A PCA projection is not a causal explanation. A silhouette score can say that points are separated in the chosen feature space, but it cannot say whether the separation is useful, fair, stable, or actionable.

The operational artifact after a clustering demo should be a review sheet: cluster size, top distinguishing features, sample records, stability across seeds or time windows, and the action each cluster would change. Without that, unsupervised learning becomes a nice picture with no decision boundary.

How I Would Use The File#

I would keep the script close to its current shape, with two changes.

First, rename it mentally from "ML concepts cheatsheet" to "ML review smoke tests." That label makes the file harder to misuse. A cheatsheet suggests answers. Smoke tests suggest boundaries.

Second, let each demo end with a question:

That is the actual post-it note I want beside the code.

Minimal examples are worth keeping because they make concepts executable. They are worth distrusting because they remove the mess that production work is made of. The discipline is to keep both thoughts alive at once.

Run the tiny script. Let it fail loudly. Fix the stale API calls. Then use each demo as a doorway into the review question it was small enough to expose.