XGBoost for beginners – from CSV to Trustworthy Model

Posted on September 22, 2025 by

Vitosh Posted in Python

This is what we do with in the YouTube video below:

take a tiny CSV and explore it with plain words
we train a strong model, using the XGBoost python library (eXtreme Gradient Boosting)
pick a practical decision treshold and we explain what matters in the data
add two simple business rules:
- debt_ratio is up should not make risk go down
- tenure_months up should not make risk go up

Why XGBoost matters and what does it mean exactly?

Boosting – adding small decision trees, one after another. Each new tree focuses on the row the earlier trees got wrong and fixes part of these mistakes. The final prediction is the sum of all small trees.
Gradient – we follow the direction that reduces the error the fastest. Somehow greedy. Think of an error hill: the gradient shows the downhill direction
Extreme – it is tuned for speed and accuracy. It runs well on a laptop CPU, can use GPU and can scale up, if needed.

TLDR – many simple trees working tohether, trained in a smart direction, implemented for speed.

What we have build in the YouTube video?

Load a tiny cusomer churn CSV called churn.csv
Do quick, safe checks – missing values and class balance.
Split data into train, validation, test – 60-20-20.
Train XGBoost with early stopping using the Booster API. The model is called bst .
Choose a practical decision treshold from validation – “a line in the sand”.
Explain results on the test set in plain terms – confusion matrix, precision, recall, ROC AUC, PR AUC
See which column mattered most (a hint – if people start calling the call centre a lot, most probably there is a problem and they will quit using your service)
Add two business rules with monotonic constraints and build new model – bst_cons
Compare the quality of bst_cons and bst with a few lines.
Save both models into UBJ (Universal Binary JSON)

The dataset in a glance

These are really human-friendly columns:

tenure_months – how long the customer has been with us
monthly_spend – monthly spend
support_calls – number of support calls
promo_eligible – 1 if they can get a promo
debt_ratio – 0 to 1, higher means more financial stress
age – age in years
is_international – 1 if they are international
churn – 1 means they have already switched to another provider

There are about 2% missing values. XGBoost can handle the missing values quite quickly (especially with such tiny dataset)

Minimal, Complete and Verifyable Example

This is some complete and minimal python. Cheers to all StackOverflow users, remembering [MCVE] and having fun there some 10 years ago.

import numpy as np
import pandas as pd
import xgboost as xgb

from sklearn.model_selection import train_test_split
from sklearn.metrics import (
    confusion_matrix, precision_score, recall_score,
    roc_auc_score, average_precision_score, precision_recall_curve
)

# 1) Load a tiny cusomer churn CSV called churn.csv 
df = pd.read_csv("churn.csv")

# 2) Do quick, safe checks - missing values and class balance.
missing_share = df.isna().mean().sort_values(ascending=False)
class_share = df["churn"].value_counts(normalize=True).rename("share")
print("Missing share (top 5):\n", missing_share.head(5), "\n")
print("Class share:\n", class_share, "\n")

# 3) Split data into train, validation, test - 60-20-20.
X = df.drop(columns=["churn"]); y = df["churn"]
X_tr, X_te, y_tr, y_te = train_test_split(X, y, test_size=0.20, stratify=y, random_state=13)
X_tr, X_va, y_tr, y_va = train_test_split(X_tr, y_tr, test_size=0.25, stratify=y_tr, random_state=13)
neg, pos = int((y_tr==0).sum()), int((y_tr==1).sum())
spw = neg / max(pos, 1)
print(f"Shapes -> train {X_tr.shape}, val {X_va.shape}, test {X_te.shape}")
print(f"Class balance in train -> neg {neg}, pos {pos}, scale_pos_weight {spw:.2f}\n")

# Wrap as DMatrix (fast internal format)
feat_names = list(X.columns)
dtr = xgb.DMatrix(X_tr, label=y_tr, feature_names=feat_names)
dva = xgb.DMatrix(X_va, label=y_va, feature_names=feat_names)
dte = xgb.DMatrix(X_te, label=y_te, feature_names=feat_names)

# 4) Train XGBoost with early stopping using the Booster API.
params = dict(
    objective="binary:logistic",
    eval_metric="aucpr",
    tree_method="hist",
    max_depth=5,
    eta=0.03,
    subsample=0.8,
    colsample_bytree=0.8,
    reg_lambda=1.0,
    scale_pos_weight=spw
)
bst = xgb.train(params, dtr, num_boost_round=4000, evals=[(dva, "val")],
                early_stopping_rounds=200, verbose_eval=False)
print("Best trees (baseline):", bst.best_iteration)

# 6) Choose a practical decision treshold from validation - "a line in the sand".
p_va = bst.predict(dva, iteration_range=(0, bst.best_iteration + 1))
pre, rec, thr = precision_recall_curve(y_va, p_va)
f1 = 2 * pre * rec / np.clip(pre + rec, 1e-9, None)
t_best = float(thr[np.argmax(f1[:-1])])
print("Chosen threshold t_best (validation F1):", round(t_best, 3), "\n")

# 7) Explain results on the test set in plain terms - confusion matrix, precision, recall, ROC AUC, PR AUC
p_te = bst.predict(dte, iteration_range=(0, bst.best_iteration + 1))
pred = (p_te >= t_best).astype(int)
cm = confusion_matrix(y_te, pred)
print("Confusion matrix:\n", cm)
print("Precision:", round(precision_score(y_te, pred), 3))
print("Recall   :", round(recall_score(y_te, pred), 3))
print("ROC AUC  :", round(roc_auc_score(y_te, p_te), 3))
print("PR  AUC  :", round(average_precision_score(y_te, p_te), 3), "\n")

# 8) See which column mattered most
# (a hint - if people start calling the call centre a lot, most probably there is a problem and they will quit using your service)
imp = pd.Series(bst.get_score(importance_type="gain")).sort_values(ascending=False)
print("Top features by importance (gain):\n", imp.head(10), "\n")

# 9) Add two business rules with monotonic constraints
cons = [0]*len(feat_names)
if "debt_ratio" in feat_names: cons[feat_names.index("debt_ratio")] = 1     # non-decreasing
if "tenure_months" in feat_names: cons[feat_names.index("tenure_months")] = -1  # non-increasing
mono = "(" + ",".join(map(str, cons)) + ")"

params_cons = params.copy()
params_cons.update({"monotone_constraints": mono, "max_bin": 512})

bst_cons = xgb.train(params_cons, dtr, num_boost_round=4000, evals=[(dva, "val")],
                     early_stopping_rounds=200, verbose_eval=False)
print("Best trees (constrained):", bst_cons.best_iteration)

# 10) Compare the quality of bst_cons and bst with a few lines.
p_cons = bst_cons.predict(dte, iteration_range=(0, bst_cons.best_iteration + 1))
print("PR AUC  baseline vs constrained:", round(average_precision_score(y_te, p_te), 3),
      "vs", round(average_precision_score(y_te, p_cons), 3))
print("ROC AUC baseline vs constrained:", round(roc_auc_score(y_te, p_te), 3),
      "vs", round(roc_auc_score(y_te, p_cons), 3), "\n")

# 11) Save both models
bst.save_model("easy_xgb_base.ubj")
bst_cons.save_model("easy_xgb_cons.ubj")
print("Saved models: easy_xgb_base.ubj, easy_xgb_cons.ubj")

import numpy as np

import pandas as pd

import xgboost as xgb

from sklearn.model_selection import train_test_split

from sklearn.metrics import (

confusion_matrix, precision_score, recall_score,

roc_auc_score, average_precision_score, precision_recall_curve

)

# 1) Load a tiny cusomer churn CSV called churn.csv

df = pd.read_csv("churn.csv")

# 2) Do quick, safe checks - missing values and class balance.

missing_share = df.isna().mean().sort_values(ascending=False)

class_share = df["churn"].value_counts(normalize=True).rename("share")

print("Missing share (top 5):\n", missing_share.head(5), "\n")

print("Class share:\n", class_share, "\n")

# 3) Split data into train, validation, test - 60-20-20.

X = df.drop(columns=["churn"]); y = df["churn"]

X_tr, X_te, y_tr, y_te = train_test_split(X, y, test_size=0.20, stratify=y, random_state=13)

X_tr, X_va, y_tr, y_va = train_test_split(X_tr, y_tr, test_size=0.25, stratify=y_tr, random_state=13)

neg, pos = int((y_tr==0).sum()), int((y_tr==1).sum())

spw = neg / max(pos, 1)

print(f"Shapes -> train {X_tr.shape}, val {X_va.shape}, test {X_te.shape}")

print(f"Class balance in train -> neg {neg}, pos {pos}, scale_pos_weight {spw:.2f}\n")

# Wrap as DMatrix (fast internal format)

feat_names = list(X.columns)

dtr = xgb.DMatrix(X_tr, label=y_tr, feature_names=feat_names)

dva = xgb.DMatrix(X_va, label=y_va, feature_names=feat_names)

dte = xgb.DMatrix(X_te, label=y_te, feature_names=feat_names)

# 4) Train XGBoost with early stopping using the Booster API.

params = dict(

objective="binary:logistic",

eval_metric="aucpr",

tree_method="hist",

max_depth=5,

eta=0.03,

subsample=0.8,

colsample_bytree=0.8,

reg_lambda=1.0,

scale_pos_weight=spw

)

bst = xgb.train(params, dtr, num_boost_round=4000, evals=[(dva, "val")],

early_stopping_rounds=200, verbose_eval=False)

print("Best trees (baseline):", bst.best_iteration)

# 6) Choose a practical decision treshold from validation - "a line in the sand".

p_va = bst.predict(dva, iteration_range=(0, bst.best_iteration + 1))

pre, rec, thr = precision_recall_curve(y_va, p_va)

f1 = 2 * pre * rec / np.clip(pre + rec, 1e-9, None)

t_best = float(thr[np.argmax(f1[:-1])])

print("Chosen threshold t_best (validation F1):", round(t_best, 3), "\n")

# 7) Explain results on the test set in plain terms - confusion matrix, precision, recall, ROC AUC, PR AUC

p_te = bst.predict(dte, iteration_range=(0, bst.best_iteration + 1))

pred = (p_te >= t_best).astype(int)

cm = confusion_matrix(y_te, pred)

print("Confusion matrix:\n", cm)

print("Precision:", round(precision_score(y_te, pred), 3))

print("Recall :", round(recall_score(y_te, pred), 3))

print("ROC AUC :", round(roc_auc_score(y_te, p_te), 3))

print("PR AUC :", round(average_precision_score(y_te, p_te), 3), "\n")

# 8) See which column mattered most

# (a hint - if people start calling the call centre a lot, most probably there is a problem and they will quit using your service)

imp = pd.Series(bst.get_score(importance_type="gain")).sort_values(ascending=False)

print("Top features by importance (gain):\n", imp.head(10), "\n")

# 9) Add two business rules with monotonic constraints

cons = [0]*len(feat_names)

if "debt_ratio" in feat_names: cons[feat_names.index("debt_ratio")] = 1 # non-decreasing

if "tenure_months" in feat_names: cons[feat_names.index("tenure_months")] = -1 # non-increasing

mono = "(" + ",".join(map(str, cons)) + ")"

params_cons = params.copy()

params_cons.update({"monotone_constraints": mono, "max_bin": 512})

bst_cons = xgb.train(params_cons, dtr, num_boost_round=4000, evals=[(dva, "val")],

early_stopping_rounds=200, verbose_eval=False)

print("Best trees (constrained):", bst_cons.best_iteration)

# 10) Compare the quality of bst_cons and bst with a few lines.

p_cons = bst_cons.predict(dte, iteration_range=(0, bst_cons.best_iteration + 1))

print("PR AUC baseline vs constrained:", round(average_precision_score(y_te, p_te), 3),

"vs", round(average_precision_score(y_te, p_cons), 3))

print("ROC AUC baseline vs constrained:", round(roc_auc_score(y_te, p_te), 3),

"vs", round(roc_auc_score(y_te, p_cons), 3), "\n")

# 11) Save both models

bst.save_model("easy_xgb_base.ubj")

bst_cons.save_model("easy_xgb_cons.ubj")

print("Saved models: easy_xgb_base.ubj, easy_xgb_cons.ubj")

This is what is printed:

What the printed metrics mean? In simple words, as I am also a beginner in XGBoost 🙂

Confusion matrix

This is the simplest to explain. It counts 4 groups:

True negatives (tn) – predicted no churn, had no churn
True positives (tp) – predicted churn, had churn
False positives (fp) – predicted churn, had no churn
False negatives (fn) – predicted no churn, had churn

From these simple numbers we get all the other metrics. Really!

Precision

Of all the values flagged with churn, how many are churn?

Precision = tp / (tp + fp). High precision means few false alarms.

Recall

Of all values who are truly churn, how many we predicted?

Recall = tp / (tp + fn). High recall means fewer churn. In general, if our model simply predicted everything as a churn, our recall would have been 100%. But this is not exactly a useful model.

F1

One number that balances precision and recall. We used F1 on the validation set to choose a practical decision treshold.

ROC AUC (Receiving Operator Characteristic Area Under Curve)

How well the model ranks positives higher than negatives across all tresholds.
It is the area under the ROC curve – tp rate vs fp rate.
Values range from 0.5 (random) to 1.0 (perfect).
ROC AUC is stable when classes are balanced, but can be overly optimistic when positives are very rare.
PR AUC (Precision Recall Area Under Curve)
Area under the precision recall curve. It focuses on the quality of catching positives.
Values range from the positive class share (baseline) up to 1.0.
PR AUC is more informative than ROC AUC when positives are rare, like churn in many datasets. (Ours is an exception.)
This is why eval_metric="aucpr" is used in the code.

Gain

We printed the top features by gain. Gain is the average error reduction when splitting on that feature, during training. Bigger gain means the feature was more useful overall. Use this as a starting point for decisions – which feature drives risk and is this expected. Does it make business sense?

The GitHub repository with both python codes (from YouTube and from this article) is here:

https://github.com/Vitosh/Python_personal/tree/master/YouTube/043_Python-XGBoost

Enjoy it! 🙂

Tagged with: beginners, model, Python, xgboost