%pip install openpyxl

from __future__ import annotations

# Core stack
import numpy as np
import pandas as pd

# Visualisation
import matplotlib.pyplot as plt
import matplotlib.ticker as mtick
import seaborn as sns

# ML utilities used only for imputation diagnostics in this milestone
from sklearn.impute import KNNImputer

# Hygiene
import warnings
warnings.filterwarnings("ignore")

# ------------------------------------------------------------------
# Global config
# ------------------------------------------------------------------
SEED = 7
np.random.seed(SEED)

PALETTE = {
    "primary":   "#1F4E79",   # corporate blue
    "accent":    "#ED7D31",   # amber
    "muted":     "#7F7F7F",   # grey
    "positive":  "#2E7D32",   # green (retained)
    "negative":  "#C0392B",   # red   (churn)
}
BINARY_CMAP = [PALETTE["positive"], PALETTE["negative"]]

sns.set_theme(style="whitegrid", context="talk")
plt.rcParams.update({
    "figure.figsize":   (10, 5),
    "axes.titlesize":   13,
    "axes.titleweight": "bold",
    "axes.labelsize":   11,
    "axes.spines.top":     False,
    "axes.spines.right":   False,
})
pd.set_option("display.max_columns",   None)
pd.set_option("display.float_format",  "{:,.3f}".format)

def profile_columns(frame: pd.DataFrame) -> pd.DataFrame:
    """One-row-per-column diagnostic: dtype, non-null, unique, missing %."""
    return pd.DataFrame({
        "dtype":        frame.dtypes.astype(str),
        "n_non_null":   frame.notna().sum(),
        "n_unique":     frame.nunique(dropna=True),
        "missing_pct":  (frame.isna().mean() * 100).round(2),
    }).sort_values("missing_pct", ascending=False)


def churn_rate_by(frame: pd.DataFrame, column: str, target: str = "Churn") -> pd.Series:
    """Churn rate (%) per category of `column`, ordered descending."""
    return (frame.groupby(column)[target].mean() * 100).round(2).sort_values(ascending=False)


def winsorize_pct(series: pd.Series, lower: float = 0.01, upper: float = 0.99) -> pd.Series:
    """Percentile-based capping. Preserves order, neutralises extremes."""
    lo, hi = series.quantile([lower, upper])
    return series.clip(lower=lo, upper=hi)


def bar_rate(rate: pd.Series, title: str, xlabel: str = "Churn rate (%)") -> None:
    """Horizontal bar plot for a churn-rate Series."""
    fig, ax = plt.subplots(figsize=(8, max(3, 0.55 * len(rate))))
    sns.barplot(x=rate.values, y=rate.index.astype(str),
                color=PALETTE["primary"], ax=ax)
    ax.set_title(title)
    ax.set_xlabel(xlabel); ax.set_ylabel("")
    ax.xaxis.set_major_formatter(mtick.FormatStrFormatter("%.0f"))
    for i, v in enumerate(rate.values):
        ax.text(v + 0.3, i, f"{v:.1f}", va="center", fontsize=10,
                color=PALETTE["muted"])
    plt.tight_layout(); plt.show()

SOURCE_FILE  = "Customer_Churn_Data.xlsx"
SOURCE_SHEET = "Data for DSBA"

raw = pd.read_excel(SOURCE_FILE, sheet_name=SOURCE_SHEET)
df  = raw.copy()
df.head()

n_rows, n_cols = df.shape
print(f"Accounts (rows): {n_rows:,}")
print(f"Variables (cols): {n_cols}")
print(f"Unique AccountID: {df['AccountID'].nunique():,}  (should equal rows)")
print(f"Duplicated rows: {df.duplicated().sum()}")

Accounts (rows): 11,260
Variables (cols): 19
Unique AccountID: 11,260  (should equal rows)
Duplicated rows: 0

profile_columns(df)

# Explicit inventory of non-numeric tokens in pseudo-numeric columns
pseudo_numeric = ["Tenure", "Account_user_count", "rev_per_month", "rev_growth_yoy",
                  "coupon_used_for_payment", "Day_Since_CC_connect", "cashback"]

tokens_found = {
    c: sorted({v for v in df[c].unique()
               if isinstance(v, str) and not v.replace(".", "", 1).lstrip("-").isdigit()})
    for c in pseudo_numeric
}
pd.Series(tokens_found, name="placeholders")

Tenure                           [#]
Account_user_count               [@]
rev_per_month                    [+]
rev_growth_yoy                   [$]
coupon_used_for_payment    [#, $, *]
Day_Since_CC_connect             [$]
cashback                         [$]
Name: placeholders, dtype: object

# Explicit inventory of categorical labels
for col in ["Payment", "Gender", "account_segment", "Marital_Status", "Login_device"]:
    print(f"— {col}")
    print(df[col].value_counts(dropna=False).to_string())
    print()

— Payment
Payment
Debit Card          4587
Credit Card         3511
E wallet            1217
Cash on Delivery    1014
UPI                  822
NaN                  109

— Gender
Gender
Male      6328
Female    4178
M          376
F          270
NaN        108

— account_segment
account_segment
Super           4062
Regular Plus    3862
HNI             1639
Super Plus       771
Regular          520
Regular +        262
NaN               97
Super +           47

— Marital_Status
Marital_Status
Married     5860
Single      3520
Divorced    1668
NaN          212

— Login_device
Login_device
Mobile      7482
Computer    3018
&&&&         539
NaN          221

GENDER_MAP  = {"M": "Male", "F": "Female"}
SEGMENT_MAP = {"Regular +": "Regular Plus", "Super +": "Super Plus"}
DEVICE_BAD  = ["&&&&"]

def drop_identifier(frame: pd.DataFrame) -> pd.DataFrame:
    return frame.drop(columns=[c for c in ["AccountID"] if c in frame.columns])

def coerce_numeric(frame: pd.DataFrame, cols: list[str]) -> pd.DataFrame:
    out = frame.copy()
    for c in cols:
        out[c] = pd.to_numeric(out[c], errors="coerce")
    return out

def canonicalise_categoricals(frame: pd.DataFrame) -> pd.DataFrame:
    return frame.assign(
        Gender          = frame["Gender"].replace(GENDER_MAP),
        account_segment = frame["account_segment"].replace(SEGMENT_MAP),
        Login_device    = frame["Login_device"].replace({t: np.nan for t in DEVICE_BAD}),
    )

df = (raw
      .pipe(drop_identifier)
      .pipe(coerce_numeric, pseudo_numeric)
      .pipe(canonicalise_categoricals))

# Quick post-cleaning profile
profile_columns(df).head(10)

numeric_cols     = [c for c in df.select_dtypes(include=[np.number]).columns if c != "Churn"]
categorical_cols = df.select_dtypes(include=["object"]).columns.tolist()

# Categorical — mode
for c in categorical_cols:
    df[c] = df[c].fillna(df[c].mode().iloc[0])

# Numeric — KNN (k=5)
knn = KNNImputer(n_neighbors=5, weights="distance")
df[numeric_cols] = knn.fit_transform(df[numeric_cols])

# Ordinal-like columns (originally integer-valued) must be rounded back
# to preserve their categorical nature after KNN imputation.
ordinal_like = ["City_Tier", "Service_Score", "CC_Agent_Score",
                "Complain_ly", "Account_user_count"]
for c in ordinal_like:
    df[c] = df[c].round().astype(int)

# Sanity
assert df.isna().sum().sum() == 0
df.isna().sum().sum()

np.int64(0)

df.describe().T

target_share = (df["Churn"].value_counts(normalize=True) * 100).round(2)
print(target_share.rename({0: "Retained", 1: "Churned"}).to_string())

fig, ax = plt.subplots(figsize=(6, 4))
sns.countplot(x="Churn", data=df, palette=BINARY_CMAP, ax=ax)
for p in ax.patches:
    ax.annotate(f"{int(p.get_height()):,}",
                (p.get_x() + p.get_width() / 2, p.get_height()),
                ha="center", va="bottom", fontsize=10)
ax.set_xticklabels(["Retained (0)", "Churned (1)"])
ax.set_title("Accounts by retention status")
ax.set_xlabel(""); ax.set_ylabel("Accounts")
plt.tight_layout(); plt.show()

Churn
Retained   83.160
Churned    16.840

fig, axes = plt.subplots(1, 2, figsize=(13, 4))

# Left — distribution, coloured by churn
sns.histplot(data=df, x="Tenure", hue="Churn", bins=30, kde=True,
             palette=BINARY_CMAP, ax=axes[0], multiple="stack")
axes[0].set_title("Tenure distribution by retention status")
axes[0].set_xlabel("Tenure (months)"); axes[0].set_ylabel("Accounts")

# Right — violin + strip
sns.violinplot(x="Churn", y="Tenure", data=df,
               palette=BINARY_CMAP, inner=None, ax=axes[1])
sns.stripplot(x="Churn", y="Tenure", data=df,
              color="white", alpha=0.15, size=1.5, ax=axes[1])
axes[1].set_title("Tenure vs. churn")
axes[1].set_xticklabels(["Retained", "Churned"])
axes[1].set_xlabel(""); axes[1].set_ylabel("Tenure (months)")
plt.tight_layout(); plt.show()

df.groupby("Churn")["Tenure"].agg(["mean", "median", "std"]).round(2)

complain_rate = (df.groupby("Complain_ly")["Churn"].mean() * 100).round(2)
complain_rate.index = ["No complaint", "≥ 1 complaint"]
bar_rate(complain_rate, "Churn rate by complaint history")
complain_rate

No complaint    10.960
≥ 1 complaint   31.700
Name: Churn, dtype: float64

seg_rate  = churn_rate_by(df, "account_segment")
tier_rate = churn_rate_by(df, "City_Tier")

fig, axes = plt.subplots(1, 2, figsize=(14, 4))
sns.barplot(x=seg_rate.values, y=seg_rate.index,
            color=PALETTE["accent"], ax=axes[0])
axes[0].set_title("Churn rate by account segment"); axes[0].set_xlabel("%")
axes[0].set_ylabel("")

sns.barplot(x=tier_rate.index.astype(str), y=tier_rate.values,
            color=PALETTE["primary"], ax=axes[1])
axes[1].set_title("Churn rate by city tier")
axes[1].set_xlabel("City tier"); axes[1].set_ylabel("%")
plt.tight_layout(); plt.show()

pd.concat([seg_rate.rename("segment_churn_%"), tier_rate.rename("tier_churn_%")], axis=1)

pay_rate = churn_rate_by(df, "Payment")
bar_rate(pay_rate, "Churn rate by payment method")
pay_rate

Payment
Cash on Delivery   25.050
E wallet           22.680
UPI                17.400
Debit Card         15.420
Credit Card        14.210
Name: Churn, dtype: float64

marital_rate = churn_rate_by(df, "Marital_Status")
gender_rate  = churn_rate_by(df, "Gender")
device_rate  = churn_rate_by(df, "Login_device")

fig, axes = plt.subplots(1, 3, figsize=(15, 3.5))
for ax, rate, title in zip(
    axes, [marital_rate, gender_rate, device_rate],
    ["Marital status", "Gender", "Login device"]):
    sns.barplot(x=rate.values, y=rate.index.astype(str),
                color=PALETTE["primary"], ax=ax)
    ax.set_title(title); ax.set_xlabel("Churn rate (%)"); ax.set_ylabel("")
plt.tight_layout(); plt.show()

pd.concat([marital_rate.rename("marital"), gender_rate.rename("gender"),
           device_rate.rename("device")], axis=1)

fig, axes = plt.subplots(2, 2, figsize=(13, 8))
for ax, col in zip(axes.ravel(),
                   ["Day_Since_CC_connect", "CC_Contacted_LY",
                    "rev_per_month", "cashback"]):
    sns.violinplot(x="Churn", y=col, data=df,
                   palette=BINARY_CMAP, inner="quartile", ax=ax)
    ax.set_title(f"{col} vs. churn")
    ax.set_xticklabels(["Retained", "Churned"])
    ax.set_xlabel("")
plt.tight_layout(); plt.show()

numeric_df = df.select_dtypes(include=[np.number])
corr = numeric_df.corr()

fig, ax = plt.subplots(figsize=(11, 8))
mask = np.triu(np.ones_like(corr, dtype=bool), k=1)
sns.heatmap(corr, mask=mask, cmap="RdBu_r", center=0,
            annot=True, fmt=".2f", annot_kws={"size": 8}, ax=ax)
ax.set_title("Correlation matrix — numeric features")
plt.tight_layout(); plt.show()

corr["Churn"].sort_values().round(3)

Tenure                    -0.233
Day_Since_CC_connect      -0.147
cashback                  -0.032
coupon_used_for_payment   -0.015
rev_growth_yoy            -0.014
Service_Score              0.008
rev_per_month              0.022
CC_Contacted_LY            0.072
City_Tier                  0.084
CC_Agent_Score             0.105
Account_user_count         0.107
Complain_ly                0.250
Churn                      1.000
Name: Churn, dtype: float64

cap_cols = ["Tenure", "CC_Contacted_LY", "rev_per_month", "rev_growth_yoy",
            "coupon_used_for_payment", "Day_Since_CC_connect", "cashback",
            "Account_user_count"]

before = df[cap_cols].agg(["min", "max"]).T.add_suffix("_pre")
df[cap_cols] = df[cap_cols].apply(winsorize_pct, lower=0.01, upper=0.99)
after = df[cap_cols].agg(["min", "max"]).T.add_suffix("_post")

pd.concat([before, after], axis=1)

fig, axes = plt.subplots(2, 4, figsize=(16, 7))
for ax, col in zip(axes.ravel(), cap_cols):
    sns.violinplot(y=df[col], color=PALETTE["primary"],
                   inner="quartile", ax=ax)
    ax.set_title(col); ax.set_xlabel("")
plt.tight_layout(); plt.show()

def bucket_tenure(t: float) -> str:
    if t < 6:  return "New (<6m)"
    if t < 12: return "Growing (6-12m)"
    if t < 24: return "Established (12-24m)"
    return "Loyal (>24m)"

df = df.assign(
    rev_per_user              = lambda d: d["rev_per_month"] /
                                           d["Account_user_count"].replace(0, np.nan),
    cashback_to_revenue_ratio = lambda d: d["cashback"] / (d["rev_per_month"] + 1),
    coupon_intensity          = lambda d: d["coupon_used_for_payment"] /
                                           (d["Tenure"] + 1),
    engagement_gap            = lambda d: d["Day_Since_CC_connect"] - d["CC_Contacted_LY"],
    tenure_bucket             = lambda d: d["Tenure"].apply(bucket_tenure),
)

# Replace any division-by-zero with the median of the column
for c in ["rev_per_user", "cashback_to_revenue_ratio",
          "coupon_intensity", "engagement_gap"]:
    df[c] = df[c].fillna(df[c].median())

df[["rev_per_user", "cashback_to_revenue_ratio",
    "coupon_intensity", "engagement_gap", "tenure_bucket"]].head()

BUCKET_ORDER = ["New (<6m)", "Growing (6-12m)", "Established (12-24m)", "Loyal (>24m)"]
bucket_rate = (df.groupby("tenure_bucket")["Churn"].mean() * 100).round(2).reindex(BUCKET_ORDER)

fig, ax = plt.subplots(figsize=(9, 4))
sns.barplot(x=bucket_rate.index, y=bucket_rate.values,
            palette=[PALETTE["negative"], PALETTE["accent"],
                     PALETTE["muted"], PALETTE["positive"]], ax=ax)
for i, v in enumerate(bucket_rate.values):
    ax.text(i, v + 0.4, f"{v:.1f}%", ha="center", fontsize=10)
ax.set_title("Churn rate by tenure bucket")
ax.set_xlabel(""); ax.set_ylabel("Churn rate (%)")
plt.tight_layout(); plt.show()
bucket_rate

tenure_bucket
New (<6m)              35.860
Growing (6-12m)         5.750
Established (12-24m)    6.330
Loyal (>24m)            2.100
Name: Churn, dtype: float64

skewed = ["rev_per_month", "cashback", "CC_Contacted_LY",
          "Day_Since_CC_connect", "coupon_used_for_payment"]

for c in skewed:
    df[f"{c}_log"] = np.log1p(df[c])

pd.DataFrame({
    "skew_raw": {c: df[c].skew() for c in skewed},
    "skew_log": {c: df[f"{c}_log"].skew() for c in skewed},
}).round(3)

#%pip install -q xgboost imbalanced-learn shap

# Model selection & pipeline
from sklearn.compose         import ColumnTransformer
from sklearn.pipeline        import Pipeline
from sklearn.preprocessing   import StandardScaler, OneHotEncoder
from sklearn.model_selection import (
    StratifiedKFold, train_test_split,
    cross_validate, GridSearchCV, RandomizedSearchCV
)

# Candidate estimators (rubric: KNN, NB, SVM mandatory; LR + ensembles for completeness)
from sklearn.linear_model import LogisticRegression
from sklearn.neighbors    import KNeighborsClassifier
from sklearn.naive_bayes  import GaussianNB
from sklearn.svm          import SVC
from sklearn.ensemble     import RandomForestClassifier, GradientBoostingClassifier
from xgboost              import XGBClassifier

# Metric panel
from sklearn.metrics import (
    recall_score, f1_score, precision_score, accuracy_score,
    roc_auc_score, average_precision_score,
    classification_report, confusion_matrix,
    roc_curve, precision_recall_curve, ConfusionMatrixDisplay
)

# Imbalance sensitivity test (§13.4 declared SMOTE as an alternative to class-weight)
from imblearn.pipeline      import Pipeline as ImbPipeline
from imblearn.over_sampling import SMOTE

import time

def cv_summary(estimator, X, y, cv, scoring) -> dict:
    """5-fold CV mean for every metric in the scoring dict — single call per model."""
    out = cross_validate(estimator, X, y, cv=cv, scoring=scoring, n_jobs=-1)
    return {m: float(np.mean(out[f"test_{m}"])) for m in scoring}

RAW_DUPLICATES = ["rev_per_month", "cashback", "CC_Contacted_LY",
                  "Day_Since_CC_connect", "coupon_used_for_payment"]

y = df["Churn"].astype(int)
X = df.drop(columns=["Churn", *RAW_DUPLICATES])

categorical = X.select_dtypes(include=["object"]).columns.tolist()
numeric     = [c for c in X.columns if c not in categorical]

print(f"Numeric features    ({len(numeric):>2}): {numeric}")
print(f"Categorical features ({len(categorical):>2}): {categorical}")
print(f"Total features       : {len(numeric) + len(categorical)}")

Numeric features    (16): ['Tenure', 'City_Tier', 'Service_Score', 'Account_user_count', 'CC_Agent_Score', 'Complain_ly', 'rev_growth_yoy', 'rev_per_user', 'cashback_to_revenue_ratio', 'coupon_intensity', 'engagement_gap', 'rev_per_month_log', 'cashback_log', 'CC_Contacted_LY_log', 'Day_Since_CC_connect_log', 'coupon_used_for_payment_log']
Categorical features ( 6): ['Payment', 'Gender', 'account_segment', 'Marital_Status', 'Login_device', 'tenure_bucket']
Total features       : 22

X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.20, stratify=y, random_state=SEED
)

print(f"Train: {X_train.shape}  | churn rate = {y_train.mean():.4f}")
print(f"Test : {X_test.shape}   | churn rate = {y_test.mean():.4f}")

Train: (9008, 22)  | churn rate = 0.1684
Test : (2252, 22)   | churn rate = 0.1683

preprocessor = ColumnTransformer(
    transformers=[
        ("num", StandardScaler(),                                            numeric),
        ("cat", OneHotEncoder(handle_unknown="ignore", sparse_output=False), categorical),
    ]
)
preprocessor

ColumnTransformer(transformers=[('num', StandardScaler(),
                                 ['Tenure', 'City_Tier', 'Service_Score',
                                  'Account_user_count', 'CC_Agent_Score',
                                  'Complain_ly', 'rev_growth_yoy',
                                  'rev_per_user', 'cashback_to_revenue_ratio',
                                  'coupon_intensity', 'engagement_gap',
                                  'rev_per_month_log', 'cashback_log',
                                  'CC_Contacted_LY_log',
                                  'Day_Since_CC_connect_log',
                                  'coupon_used_for_payment_log']),
                                ('cat',
                                 OneHotEncoder(handle_unknown='ignore',
                                               sparse_output=False),
                                 ['Payment', 'Gender', 'account_segment',
                                  'Marital_Status', 'Login_device',
                                  'tenure_bucket'])])

['Tenure', 'City_Tier', 'Service_Score', 'Account_user_count', 'CC_Agent_Score', 'Complain_ly', 'rev_growth_yoy', 'rev_per_user', 'cashback_to_revenue_ratio', 'coupon_intensity', 'engagement_gap', 'rev_per_month_log', 'cashback_log', 'CC_Contacted_LY_log', 'Day_Since_CC_connect_log', 'coupon_used_for_payment_log']

['Payment', 'Gender', 'account_segment', 'Marital_Status', 'Login_device', 'tenure_bucket']

cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=SEED)
neg_pos_ratio = (y_train == 0).sum() / (y_train == 1).sum()

scoring = {
    "recall":    "recall",
    "f1":        "f1",
    "precision": "precision",
    "roc_auc":   "roc_auc",
    "pr_auc":    "average_precision",
    "accuracy":  "accuracy",
}

print(f"CV: 5-fold stratified, shuffle=True, seed={SEED}")
print(f"neg/pos ratio in training fold: {neg_pos_ratio:.3f}  ->  used as scale_pos_weight for XGBoost")

CV: 5-fold stratified, shuffle=True, seed=7
neg/pos ratio in training fold: 4.938  ->  used as scale_pos_weight for XGBoost

models_baseline = {
    "Logistic Regression":  LogisticRegression(class_weight="balanced", max_iter=2000, random_state=SEED),
    "KNN":                  KNeighborsClassifier(),
    "Gaussian Naive Bayes": GaussianNB(),
    "SVM (RBF)":            SVC(class_weight="balanced", probability=True, random_state=SEED),
    "Random Forest":        RandomForestClassifier(class_weight="balanced", n_estimators=300,
                                                   random_state=SEED, n_jobs=-1),
    "Gradient Boosting":    GradientBoostingClassifier(random_state=SEED),
    "XGBoost":              XGBClassifier(scale_pos_weight=neg_pos_ratio,
                                          eval_metric="logloss",
                                          random_state=SEED, n_jobs=-1, use_label_encoder=False),
}

baseline_rows = []
for name, est in models_baseline.items():
    pipe = Pipeline([("prep", preprocessor), ("clf", est)])
    t0 = time.time()
    summary = cv_summary(pipe, X_train, y_train, cv, scoring)
    elapsed = time.time() - t0

    summary["model"] = name
    summary["fit_seconds"] = round(elapsed, 1)
    baseline_rows.append(summary)
    print(f"  {name:25s} | recall={summary['recall']:.4f}  f1={summary['f1']:.4f}  "
          f"pr_auc={summary['pr_auc']:.4f}  ({elapsed:.1f}s)")

baseline_df = (pd.DataFrame(baseline_rows)
                 .set_index("model")
                 [["recall", "f1", "precision", "pr_auc", "roc_auc", "accuracy", "fit_seconds"]])
baseline_df.style.background_gradient(cmap="Blues", subset=["recall", "f1", "pr_auc", "roc_auc"]) \
                  .format("{:.4f}", subset=["recall", "f1", "precision", "pr_auc", "roc_auc", "accuracy"])

  Logistic Regression       | recall=0.8154  f1=0.5919  pr_auc=0.6985  (1.3s)
  KNN                       | recall=0.8082  f1=0.8548  pr_auc=0.9069  (0.9s)
  Gaussian Naive Bayes      | recall=0.7680  f1=0.5222  pr_auc=0.5935  (0.8s)
  SVM (RBF)                 | recall=0.9170  f1=0.7690  pr_auc=0.8480  (3.7s)
  Random Forest             | recall=0.8009  f1=0.8645  pr_auc=0.9529  (1.5s)
  Gradient Boosting         | recall=0.6216  f1=0.7072  pr_auc=0.8164  (1.8s)
  XGBoost                   | recall=0.9156  f1=0.9043  pr_auc=0.9647  (0.9s)

fig, ax = plt.subplots(figsize=(11, 5.5))
plot_df = baseline_df[["recall", "f1", "pr_auc"]].sort_values("recall")
plot_df.plot(kind="barh", ax=ax,
             color=[PALETTE["primary"], PALETTE["accent"], PALETTE["muted"]])
ax.set_title("Baseline 5-fold CV - Recall, F1, PR-AUC by model")
ax.set_xlabel("Score"); ax.set_ylabel("")
ax.set_xlim(0, 1.0)
ax.legend(loc="lower right", frameon=True)
plt.tight_layout(); plt.show()

search_specs = {
    # ---- Linear baseline ----
    "Logistic Regression": {
        "estimator": LogisticRegression(class_weight="balanced", max_iter=2000, random_state=SEED),
        "kind": "grid",
        "params": {"clf__C": [0.01, 0.1, 1, 10]},
    },
    # ---- Rubric-mandatory ----
    "KNN": {
        "estimator": KNeighborsClassifier(),
        "kind": "grid",
        "params": {
            "clf__n_neighbors": [3, 5, 7, 11, 15, 21],
            "clf__weights":     ["uniform", "distance"],
            "clf__p":           [1, 2],
        },
    },
    "Gaussian Naive Bayes": {
        "estimator": GaussianNB(),
        "kind": "grid",
        "params": {"clf__var_smoothing": np.logspace(-12, -6, 7)},
    },
    "SVM (RBF)": {
        "estimator": SVC(class_weight="balanced", probability=True, random_state=SEED),
        "kind": "grid",
        "params": {
            "clf__C":     [0.5, 1, 5],
            "clf__gamma": ["scale", 0.01, 0.1],
        },
    },
    # ---- Tree ensembles ----
    "Random Forest": {
        "estimator": RandomForestClassifier(class_weight="balanced", random_state=SEED, n_jobs=-1),
        "kind": "random", "n_iter": 30,
        "params": {
            "clf__n_estimators":      [200, 300, 500, 800],
            "clf__max_depth":         [None, 6, 10, 16, 24],
            "clf__min_samples_split": [2, 5, 10],
            "clf__min_samples_leaf":  [1, 2, 4],
            "clf__max_features":      ["sqrt", "log2"],
        },
    },
    "Gradient Boosting": {
        "estimator": GradientBoostingClassifier(random_state=SEED),
        "kind": "grid",
        "params": {
            "clf__n_estimators":  [200, 300],
            "clf__learning_rate": [0.05, 0.1],
            "clf__max_depth":     [3, 5],
        },
    },
    "XGBoost": {
        "estimator": XGBClassifier(scale_pos_weight=neg_pos_ratio,
                                   eval_metric="logloss",
                                   random_state=SEED, n_jobs=-1, use_label_encoder=False),
        "kind": "random", "n_iter": 30,
        "params": {
            "clf__n_estimators":     [200, 400, 600, 800],
            "clf__max_depth":        [3, 5, 7, 9],
            "clf__learning_rate":    [0.03, 0.05, 0.1, 0.2],
            "clf__subsample":        [0.7, 0.85, 1.0],
            "clf__colsample_bytree": [0.7, 0.85, 1.0],
            "clf__reg_lambda":       [0.5, 1.0, 2.0],
            "clf__min_child_weight": [1, 3, 5],
        },
    },
}

tuned_estimators = {}
tuning_rows      = []

for name, spec in search_specs.items():
    print(f"--- Tuning: {name} ---")
    pipe = Pipeline([("prep", preprocessor), ("clf", spec["estimator"])])
    t0 = time.time()

    if spec["kind"] == "grid":
        search = GridSearchCV(pipe, spec["params"],
                              scoring="recall", cv=cv, n_jobs=-1, refit=True)
    else:
        search = RandomizedSearchCV(pipe, spec["params"], n_iter=spec["n_iter"],
                                    scoring="recall", cv=cv, n_jobs=-1, refit=True,
                                    random_state=SEED)

    search.fit(X_train, y_train)
    elapsed = time.time() - t0

    tuned_estimators[name] = search.best_estimator_
    tuning_rows.append({
        "model":          name,
        "cv_best_recall": float(search.best_score_),
        "best_params":    {k: (v.item() if isinstance(v, np.generic) else v)
                           for k, v in search.best_params_.items()},
        "fit_seconds":    round(elapsed, 1),
    })
    print(f"  cv_best_recall = {search.best_score_:.4f}  ({elapsed:.1f}s)")
    print(f"  best params: {search.best_params_}\n")

tuning_df = (pd.DataFrame(tuning_rows)
               .set_index("model")
               .sort_values("cv_best_recall", ascending=False))
tuning_df

--- Tuning: Logistic Regression ---
  cv_best_recall = 0.8181  (1.0s)
  best params: {'clf__C': 0.1}

--- Tuning: KNN ---
  cv_best_recall = 0.9130  (1.3s)
  best params: {'clf__n_neighbors': 3, 'clf__p': 1, 'clf__weights': 'distance'}

--- Tuning: Gaussian Naive Bayes ---
  cv_best_recall = 0.7680  (0.1s)
  best params: {'clf__var_smoothing': np.float64(1e-12)}

--- Tuning: SVM (RBF) ---
  cv_best_recall = 0.9321  (22.2s)
  best params: {'clf__C': 5, 'clf__gamma': 'scale'}

--- Tuning: Random Forest ---
  cv_best_recall = 0.8438  (26.1s)
  best params: {'clf__n_estimators': 200, 'clf__min_samples_split': 10, 'clf__min_samples_leaf': 4, 'clf__max_features': 'sqrt', 'clf__max_depth': 24}

--- Tuning: Gradient Boosting ---
  cv_best_recall = 0.8247  (21.7s)
  best params: {'clf__learning_rate': 0.1, 'clf__max_depth': 5, 'clf__n_estimators': 300}

--- Tuning: XGBoost ---
  cv_best_recall = 0.9209  (7.3s)
  best params: {'clf__subsample': 1.0, 'clf__reg_lambda': 1.0, 'clf__n_estimators': 600, 'clf__min_child_weight': 5, 'clf__max_depth': 9, 'clf__learning_rate': 0.05, 'clf__colsample_bytree': 1.0}

tuned_cv_rows = []
for name, est in tuned_estimators.items():
    summary = cv_summary(est, X_train, y_train, cv, scoring)
    summary["model"] = name
    tuned_cv_rows.append(summary)

tuned_cv_df = (pd.DataFrame(tuned_cv_rows)
                 .set_index("model")
                 [["recall", "f1", "precision", "pr_auc", "roc_auc", "accuracy"]]
                 .sort_values("recall", ascending=False))

tuned_cv_df.style.background_gradient(cmap="Blues", subset=["recall", "f1", "pr_auc", "roc_auc"]) \
                  .format("{:.4f}")

# 19.3.1 — Baseline vs tuned, side-by-side, for the metrics that matter
delta = (tuned_cv_df[["recall", "f1", "pr_auc"]]
         - baseline_df.loc[tuned_cv_df.index, ["recall", "f1", "pr_auc"]]).round(4)
delta.columns = [f"delta {c}" for c in delta.columns]

side_by_side = pd.concat([
    baseline_df.loc[tuned_cv_df.index, ["recall", "f1", "pr_auc"]].add_prefix("baseline_"),
    tuned_cv_df[["recall", "f1", "pr_auc"]].add_prefix("tuned_"),
    delta,
], axis=1)
side_by_side

leaderboard = tuned_cv_df.copy()
leaderboard.style.background_gradient(cmap="Blues",
                                      subset=["recall", "f1", "pr_auc", "roc_auc"]) \
                 .format("{:.4f}")

fig, ax = plt.subplots(figsize=(11, 6))
plot_df = leaderboard[["recall", "f1", "pr_auc"]].sort_values("recall")
plot_df.plot(kind="barh", ax=ax,
             color=[PALETTE["primary"], PALETTE["accent"], PALETTE["muted"]])
ax.set_title("Tuned 5-fold CV - Recall, F1, PR-AUC by model")
ax.set_xlabel("Score"); ax.set_ylabel("")
ax.set_xlim(0, 1.0)
ax.legend(loc="lower right", frameon=True)
plt.tight_layout(); plt.show()

fig, ax = plt.subplots(figsize=(8.5, 6.5))
ax.scatter(leaderboard["precision"], leaderboard["recall"],
           s=160, color=PALETTE["primary"], zorder=3)
for name, row in leaderboard.iterrows():
    ax.annotate(name, (row["precision"], row["recall"]),
                xytext=(8, 4), textcoords="offset points", fontsize=10)
ax.axhline(0.85, color=PALETTE["accent"], linestyle="--", lw=1, alpha=0.7,
           label="Target Recall >= 0.85")
ax.set_xlabel("Precision"); ax.set_ylabel("Recall")
ax.set_title("Recall-Precision frontier (tuned, CV mean)")
ax.set_xlim(0, 1); ax.set_ylim(0, 1.05)
ax.legend(loc="lower left")
plt.tight_layout(); plt.show()

RECALL_FLOOR = 0.85

qualified = leaderboard[leaderboard["recall"] >= RECALL_FLOOR]
if qualified.empty:
    print(f"No model reached Recall >= {RECALL_FLOOR}. Falling back to the highest-recall row.")
    winner = leaderboard.sort_values("recall", ascending=False).index[0]
else:
    winner = qualified.sort_values(["f1", "pr_auc"], ascending=False).index[0]

print(f"Selected model: {winner}\n")
print("CV scores at the selected model:")
print(leaderboard.loc[winner].to_frame("value").round(4))
print("\nTuned hyperparameters of the selected model:")
chosen_pipe = tuned_estimators[winner]
for k, v in chosen_pipe.named_steps["clf"].get_params().items():
    if k in (search_specs[winner]["params"].keys()):
        print(f"  {k:30s} {v}")

Selected model: KNN

CV scores at the selected model:
           value
recall     0.913
f1         0.922
precision  0.931
pr_auc     0.969
roc_auc    0.988
accuracy   0.974

Tuned hyperparameters of the selected model:

y_pred  = chosen_pipe.predict(X_test)
y_proba = chosen_pipe.predict_proba(X_test)[:, 1]

test_metrics = {
    "Recall":    recall_score(y_test, y_pred),
    "F1":        f1_score(y_test, y_pred),
    "Precision": precision_score(y_test, y_pred),
    "PR-AUC":    average_precision_score(y_test, y_proba),
    "ROC-AUC":   roc_auc_score(y_test, y_proba),
    "Accuracy":  accuracy_score(y_test, y_pred),
}
pd.Series(test_metrics).to_frame(f"{winner} - test set").style.format("{:.4f}")

fig, ax = plt.subplots(figsize=(5.5, 5))
ConfusionMatrixDisplay.from_predictions(
    y_test, y_pred,
    display_labels=["Retained", "Churned"],
    cmap="Blues", colorbar=False, ax=ax
)
ax.set_title(f"Confusion matrix - {winner} (test set)")
plt.tight_layout(); plt.show()

print(classification_report(y_test, y_pred, target_names=["Retained", "Churned"], digits=4))

              precision    recall  f1-score   support

    Retained     0.9893    0.9915    0.9904      1873
     Churned     0.9573    0.9472    0.9523       379

    accuracy                         0.9840      2252
   macro avg     0.9733    0.9693    0.9713      2252
weighted avg     0.9840    0.9840    0.9840      2252

fpr, tpr, _      = roc_curve(y_test, y_proba)
prc_p, prc_r, _  = precision_recall_curve(y_test, y_proba)

fig, axes = plt.subplots(1, 2, figsize=(13, 5))

axes[0].plot(fpr, tpr, color=PALETTE["primary"], lw=2,
             label=f"AUC = {test_metrics['ROC-AUC']:.3f}")
axes[0].plot([0, 1], [0, 1], color=PALETTE["muted"], linestyle="--", lw=1)
axes[0].set_title("ROC curve - test set")
axes[0].set_xlabel("False Positive Rate"); axes[0].set_ylabel("True Positive Rate")
axes[0].legend(loc="lower right")

axes[1].plot(prc_r, prc_p, color=PALETTE["accent"], lw=2,
             label=f"PR-AUC = {test_metrics['PR-AUC']:.3f}")
axes[1].axhline(y_test.mean(), color=PALETTE["muted"], linestyle="--", lw=1,
                label=f"Prevalence = {y_test.mean():.3f}")
axes[1].set_title("Precision-Recall curve - test set")
axes[1].set_xlabel("Recall"); axes[1].set_ylabel("Precision")
axes[1].legend(loc="lower left")

plt.tight_layout(); plt.show()

thresholds = np.linspace(0.05, 0.95, 19)
sweep = []
for t in thresholds:
    y_t = (y_proba >= t).astype(int)
    if y_t.sum() == 0:
        continue
    sweep.append({
        "threshold": round(t, 2),
        "recall":    recall_score(y_test, y_t),
        "precision": precision_score(y_test, y_t),
        "f1":        f1_score(y_test, y_t),
        "flagged":   int(y_t.sum()),
    })
sweep_df = pd.DataFrame(sweep)

fig, ax = plt.subplots(figsize=(11, 5))
ax.plot(sweep_df["threshold"], sweep_df["recall"],    color=PALETTE["primary"],  lw=2, label="Recall")
ax.plot(sweep_df["threshold"], sweep_df["precision"], color=PALETTE["accent"],   lw=2, label="Precision")
ax.plot(sweep_df["threshold"], sweep_df["f1"],        color=PALETTE["positive"], lw=2, label="F1")
ax.axvline(0.5, color=PALETTE["muted"], linestyle="--", lw=1, label="Default = 0.50")
ax.set_title("Threshold sweep - Recall, Precision, F1 (test set)")
ax.set_xlabel("Decision threshold"); ax.set_ylabel("Score")
ax.legend(loc="center right")
plt.tight_layout(); plt.show()
sweep_df.round(4)

test_scored = pd.DataFrame({"y_true": y_test.values, "score": y_proba})

# qcut on the scores; some models (e.g. KNN with weights="distance") produce
# many tied probabilities, so we drop duplicate bin edges and re-label the
# resulting buckets in score order.
buckets = pd.qcut(-test_scored["score"], 10, labels=False, duplicates="drop")
n_buckets = int(buckets.max() + 1)
test_scored["decile"] = pd.Categorical(
    [f"D{int(b)+1}" for b in buckets],
    categories=[f"D{i}" for i in range(1, n_buckets + 1)],
    ordered=True,
)

decile = (test_scored.groupby("decile", observed=True)
          .agg(accounts=("y_true", "size"),
               churners=("y_true", "sum"),
               churn_rate=("y_true", "mean"))
          .reset_index())
decile["lift_vs_base"] = (decile["churn_rate"] / y_test.mean()).round(2)
decile["cum_capture"]  = (decile["churners"].cumsum() / decile["churners"].sum()).round(3)

if n_buckets < 10:
    print(f"NOTE: only {n_buckets} distinct score buckets (model has many tied probabilities). "
          f"Lift table is still meaningful, just coarser.")

decile

NOTE: only 2 distinct score buckets (model has many tied probabilities). Lift table is still meaningful, just coarser.

fig, ax = plt.subplots(figsize=(9, 5))
n = len(decile)
x = (np.arange(1, n + 1) / n) * 100
ax.plot(x, decile["cum_capture"] * 100, marker="o", color=PALETTE["primary"], lw=2,
        label="Cumulative churn capture")
ax.plot([0, 100], [0, 100], color=PALETTE["muted"], lw=1, linestyle="--",
        label="Random targeting")
ax.set_title("Top-N targeting - cumulative churners captured")
ax.set_xlabel("Top % of accounts targeted (by score)")
ax.set_ylabel("% of total churners captured")
ax.set_xlim(0, 100); ax.set_ylim(0, 105)
ax.legend(loc="lower right")
plt.tight_layout(); plt.show()

feature_names = chosen_pipe.named_steps["prep"].get_feature_names_out().tolist()
clf = chosen_pipe.named_steps["clf"]

if hasattr(clf, "feature_importances_"):
    importance = pd.Series(clf.feature_importances_, index=feature_names) \
                   .sort_values(ascending=False).head(15)
    title = f"Top-15 feature importance - {winner}"
elif hasattr(clf, "coef_"):
    importance = pd.Series(np.abs(clf.coef_[0]), index=feature_names) \
                   .sort_values(ascending=False).head(15)
    title = f"Top-15 |coefficient| - {winner}"
else:
    importance = None
    title = None

if importance is not None:
    fig, ax = plt.subplots(figsize=(10, 6))
    sns.barplot(x=importance.values, y=importance.index,
                color=PALETTE["primary"], ax=ax)
    ax.set_title(title); ax.set_xlabel("Importance"); ax.set_ylabel("")
    plt.tight_layout(); plt.show()
    importance.to_frame("importance")
else:
    print(f"{winner} does not expose model-native feature importance - see SHAP cell below.")

KNN does not expose model-native feature importance - see SHAP cell below.

import shap
shap.initjs()

prep      = chosen_pipe.named_steps["prep"]
clf       = chosen_pipe.named_steps["clf"]
X_test_t  = prep.transform(X_test)
X_train_t = prep.transform(X_train)

rng       = np.random.RandomState(SEED)
test_idx  = rng.choice(len(X_test_t), size=min(500, len(X_test_t)), replace=False)
X_sample  = X_test_t[test_idx]

try:
    # Tree-based models -> fast TreeExplainer
    if hasattr(clf, "estimators_") or clf.__class__.__name__.startswith("XGB"):
        explainer = shap.TreeExplainer(clf, feature_names=feature_names)
        shap_vals = explainer(X_sample)
        shap.plots.beeswarm(shap_vals, max_display=15, show=True)

    # Linear models -> LinearExplainer
    elif hasattr(clf, "coef_"):
        back_idx  = rng.choice(len(X_train_t), size=min(100, len(X_train_t)), replace=False)
        explainer = shap.LinearExplainer(clf, X_train_t[back_idx], feature_names=feature_names)
        shap_vals = explainer(X_sample)
        shap.plots.beeswarm(shap_vals, max_display=15, show=True)

    # Distance / margin models (KNN, SVM) -> KernelExplainer is much slower.
    # We summarise the background to 25 rows and limit the explained sample to 100
    # to keep this cell tractable (~1-2 minutes).
    else:
        print("KernelExplainer route - slower than TreeExplainer; "
              "using a 25-row summarised background and 100-row sample.")
        back_idx   = rng.choice(len(X_train_t), size=min(50, len(X_train_t)), replace=False)
        background = shap.sample(X_train_t[back_idx], 25, random_state=SEED)
        small      = X_sample[:100]

        f = lambda x: clf.predict_proba(x)[:, 1]
        explainer = shap.KernelExplainer(f, background)
        sv_raw = explainer.shap_values(small, nsamples=100)

        shap_exp = shap.Explanation(values=sv_raw, data=small, feature_names=feature_names)
        shap.plots.beeswarm(shap_exp, max_display=15, show=True)

except Exception as e:
    print(f"SHAP explainer not available for {winner}: {e}")
    print("Falling back to global importance only - the §23.1 ranking is the interpretability layer.")

KernelExplainer route - slower than TreeExplainer; using a 25-row summarised background and 100-row sample.

  0%|          | 0/100 [00:00<?, ?it/s]

# Same chosen-model class, but swap weighting for SMOTE inside the pipe
clf_class  = chosen_pipe.named_steps["clf"].__class__
clf_kwargs = {k: v for k, v in chosen_pipe.named_steps["clf"].get_params().items()
              if k not in ("class_weight", "scale_pos_weight")}

imb_pipe = ImbPipeline([
    ("prep",  preprocessor),
    ("smote", SMOTE(random_state=SEED)),
    ("clf",   clf_class(**clf_kwargs)),
])

smote_summary = cv_summary(imb_pipe, X_train, y_train, cv, scoring)
compare = pd.DataFrame({
    "Tuned (class-weight)": tuned_cv_df.loc[winner, ["recall", "f1", "precision", "pr_auc", "roc_auc"]],
    "Tuned + SMOTE":        pd.Series(smote_summary)[["recall", "f1", "precision", "pr_auc", "roc_auc"]],
}).round(4)
compare["delta (SMOTE - weight)"] = (compare["Tuned + SMOTE"] - compare["Tuned (class-weight)"]).round(4)
compare

Field	Business meaning
`AccountID`	Unique account key (not predictive).
`Churn`	Target. 1 = account churned, 0 = retained.
`Tenure`	Months the account has been active.
`City_Tier`	Tier of the primary customer's city (1 = metro, 3 = smaller city).
`CC_Contacted_LY`	Customer-care contacts initiated by the account's users in the last 12 months.
`Payment`	Preferred payment method.
`Gender`	Primary customer gender.
`Service_Score`	Satisfaction rating on the service itself.
`Account_user_count`	End customers tagged to the account.
`account_segment`	Commercial segment based on spend.
`CC_Agent_Score`	Satisfaction rating on the CC agent experience.
`Marital_Status`	Primary customer marital status.
`rev_per_month`	Monthly revenue generated by the account (trailing 12m).
`Complain_ly`	At least one complaint in the last 12 months (0/1).
`rev_growth_yoy`	Revenue growth (last 12m vs prior 12m), %.
`coupon_used_for_payment`	Coupon redemptions in the last 12 months.
`Day_Since_CC_connect`	Days since the last customer-care contact.
`cashback`	Monthly average cashback earned.
`Login_device`	Preferred login device.

Issue	Where	Treatment
Non-numeric placeholders (`#`, `@`, `+`, `$`, `*`)	7 numeric columns	Coerce to `NaN`, then impute.
`Gender` inconsistency (`M` vs `Male`, `F` vs `Female`)	Profile	Canonicalise to `Male` / `Female`.
`account_segment` duplicated labels (`Regular +` / `Regular Plus`, `Super +` / `Super Plus`)	Profile	Collapse `+` variants into `Plus`.
`Login_device` placeholder (`&&&&`)	Behavioural	Convert to `NaN`, then impute.
Missing values (all <5%)	14 columns	Median (numeric) / Mode (categorical), or KNN where we want a richer signal.

	count	mean	std	min	25%	50%	75%	max
Churn	11,260.000	0.168	0.374	0.000	0.000	0.000	0.000	1.000
Tenure	11,260.000	10.989	12.785	0.000	2.000	9.000	16.000	99.000
City_Tier	11,260.000	1.654	0.913	1.000	1.000	1.000	3.000	3.000
CC_Contacted_LY	11,260.000	17.859	8.829	4.000	11.000	16.000	23.000	132.000
Service_Score	11,260.000	2.903	0.724	0.000	2.000	3.000	3.000	5.000
Account_user_count	11,260.000	3.690	1.013	1.000	3.000	4.000	4.000	6.000
CC_Agent_Score	11,260.000	3.066	1.376	1.000	2.000	3.000	4.000	5.000
rev_per_month	11,260.000	6.339	11.609	1.000	3.000	5.000	7.000	140.000
Complain_ly	11,260.000	0.283	0.451	0.000	0.000	0.000	1.000	1.000
rev_growth_yoy	11,260.000	16.193	3.757	4.000	13.000	15.000	19.000	28.000
coupon_used_for_payment	11,260.000	1.791	1.969	0.000	1.000	1.000	2.000	16.000
Day_Since_CC_connect	11,260.000	4.624	3.663	0.000	2.000	3.000	7.705	47.000
cashback	11,260.000	196.198	176.389	0.000	147.358	165.395	200.100	1,997.000

Dimension	High-risk side	Bivariate churn rate
Tenure bucket	New (< 6 months)	35.8%
Complaint flag	At least one complaint	31.8%
Account segment	Regular Plus	27.1%
Marital status	Single	26.9%
Payment method	Cash on Delivery / E-Wallet	22.7–25.1%
Login device	Desktop-first	19.8%

	min_pre	max_pre	min_post	max_post
Tenure	0.000	99.000	0.000	99.000
CC_Contacted_LY	4.000	132.000	6.000	40.000
rev_per_month	1.000	140.000	1.000	30.898
rev_growth_yoy	4.000	28.000	11.000	26.000
coupon_used_for_payment	0.000	16.000	0.000	10.000
Day_Since_CC_connect	0.000	47.000	0.000	15.000
cashback	0.000	1,997.000	118.590	569.900
Account_user_count	1.000	6.000	1.000	6.000

	AccountID	Churn	Tenure	City_Tier	CC_Contacted_LY	Payment	Gender	Service_Score	Account_user_count	account_segment	CC_Agent_Score	Marital_Status	rev_per_month	Complain_ly	rev_growth_yoy	coupon_used_for_payment	Day_Since_CC_connect	cashback	Login_device
0	20000	1	4	3.000	6.000	Debit Card	Female	3.000	3	Super	2.000	Single	9	1.000	11	1	5	159.930	Mobile
1	20001	1	0	1.000	8.000	UPI	Male	3.000	4	Regular Plus	3.000	Single	7	1.000	15	0	0	120.900	Mobile
2	20002	1	0	1.000	30.000	Debit Card	Male	2.000	4	Regular Plus	3.000	Single	6	1.000	14	0	3	NaN	Mobile
3	20003	1	0	3.000	15.000	Debit Card	Male	2.000	4	Super	5.000	Single	8	0.000	23	0	3	134.070	Mobile
4	20004	1	0	1.000	12.000	Credit Card	Male	2.000	3	Regular Plus	5.000	Single	3	0.000	11	1	3	129.600	Mobile

	dtype	n_non_null	n_unique	missing_pct
cashback	object	10789	5693	4.180
Day_Since_CC_connect	object	10903	24	3.170
Complain_ly	float64	10903	2	3.170
Login_device	object	11039	3	1.960
Marital_Status	object	11048	3	1.880
CC_Agent_Score	float64	11144	5	1.030
City_Tier	float64	11148	3	0.990
Account_user_count	object	11148	7	0.990
Payment	object	11151	5	0.970
Gender	object	11152	4	0.960
Tenure	object	11158	38	0.910
CC_Contacted_LY	float64	11158	44	0.910
rev_per_month	object	11158	59	0.910
Service_Score	float64	11162	6	0.870
account_segment	object	11163	7	0.860
coupon_used_for_payment	object	11260	20	0.000
rev_growth_yoy	object	11260	20	0.000
Churn	int64	11260	2	0.000
AccountID	int64	11260	11260	0.000

	dtype	n_non_null	n_unique	missing_pct
rev_per_month	float64	10469	58	7.020
Login_device	object	10500	2	6.750
cashback	float64	10787	5692	4.200
Account_user_count	float64	10816	6	3.940
Day_Since_CC_connect	float64	10902	23	3.180
Complain_ly	float64	10903	2	3.170
Tenure	float64	11042	37	1.940
Marital_Status	object	11048	3	1.880
CC_Agent_Score	float64	11144	5	1.030
City_Tier	float64	11148	3	0.990

	segment_churn_%	tier_churn_%
Regular Plus	27.130	NaN
HNI	15.560	NaN
Super	10.240	NaN
Regular	7.690	NaN
Super Plus	4.890	NaN
3	NaN	21.370
2	NaN	19.390
1	NaN	14.540

	marital	gender	device
Single	26.900	NaN	NaN
Divorced	14.630	NaN	NaN
Married	11.610	NaN	NaN
Male	NaN	17.720	NaN
Female	NaN	15.490	NaN
Computer	NaN	NaN	19.780
Mobile	NaN	NaN	15.760

Feature	Logic	Business meaning
`rev_per_user`	`rev_per_month / Account_user_count`	Revenue intensity per end customer. Distinguishes genuinely high-value multi-user accounts from "busy but low-yield" ones.
`cashback_to_revenue_ratio`	`cashback / (rev_per_month + 1)`	Effective retention cost per unit of revenue. Central to Revenue-Assurance approval — accounts with high ratio are expensive to keep.
`coupon_intensity`	`coupon_used_for_payment / (Tenure + 1)`	Discount reliance normalised by account age.
`engagement_gap`	`Day_Since_CC_connect − CC_Contacted_LY`	Positive values = account going silent; negative = recently engaged.
`tenure_bucket`	Categorical: New / Growing / Established / Loyal	Ready-to-use segmentation key for campaign design.

	rev_per_user	cashback_to_revenue_ratio	coupon_intensity	engagement_gap	tenure_bucket
0	3.000	15.993	0.200	-1.000	New (<6m)
1	1.750	15.113	0.000	-8.000	New (<6m)
2	1.500	17.183	0.000	-27.000	New (<6m)
3	2.000	14.897	0.000	-12.000	New (<6m)
4	1.000	32.400	1.000	-9.000	New (<6m)

	skew_raw	skew_log
rev_per_month	3.158	0.281
cashback	2.933	1.290
CC_Contacted_LY	0.791	0.040
Day_Since_CC_connect	0.742	-0.441
coupon_used_for_payment	2.119	0.352

Risk factor	Low-risk side	High-risk side	Delta
Tenure bucket	Loyal (>24m)	New (<6m)	2.1% → 35.8%
Complaint in last 12m	No	Yes	11.1% → 31.8%
Account segment	Super Plus	Regular Plus	4.9% → 27.1%
Marital status	Married	Single	11.6% → 26.9%
Payment mode	Credit Card	Cash on Delivery	14.2% → 25.1%
City tier	1	3	14.6% → 21.4%
Login device	Mobile	Computer	15.8% → 19.8%

Decision	Rationale	Source
Stratified 80 / 20 train-test split	Preserve the 16.84% churn prevalence in both folds — guards every metric against split-luck.	§13.1
Stratified `k = 5` CV inside the training fold	All hyperparameter search is done on training folds only; test set is held out until final selection.	§13.1
Single `Pipeline` + `ColumnTransformer`	Imputation, scaling, encoding fit on the training fold only — eliminates leakage by construction.	§13.1
Primary metric = Recall on class 1 (churners)	The cost of a missed churner (lost LTV, multiple end customers per account) materially exceeds the cost of a false alarm (a retention call).	§12.1, §13.3
Guardrail metrics = F1, PR-AUC, Precision	Prevent the optimiser from collapsing onto a "predict everyone churns" degenerate solution.	§13.3
`class_weight="balanced"` (or `scale_pos_weight`) on every supporting model	Imbalance handled in-pipeline, never by resampling the master dataset upfront.	§13.4
Model zoo: LR, KNN, NB, SVM (RBF), RF, GB, XGBoost	Span the full bias-variance spectrum: linear / instance-based / probabilistic / margin / bagging / boosting.	§13.2

Transformer	Applies to	Why
`StandardScaler`	Every numeric feature	Mandatory for distance-based (KNN), margin-based (SVM) and gradient-based (LR) models. Tree ensembles are scale-invariant; standardising them is harmless and keeps the pipeline uniform across models.
`OneHotEncoder(handle_unknown="ignore")`	Every categorical feature	The `handle_unknown` setting lets the test fold encounter a level the train fold did not see — rare here, but a free safety guarantee.
(no imputation step)	—	§6 imputed all NaN on the full dataset before the split. The pipeline does not re-impute because there is nothing left to impute.

	transformers	[('num', ...), ('cat', ...)]
	remainder	'drop'
	sparse_threshold	0.3
	n_jobs	None
	transformer_weights	None
	verbose	False
	verbose_feature_names_out	True
	force_int_remainder_cols	'deprecated'

	copy	True
	with_mean	True
	with_std	True

	categories	'auto'
	drop	None
	sparse_output	False
	dtype	<class 'numpy.float64'>
	handle_unknown	'ignore'
	min_frequency	None
	max_categories	None
	feature_name_combiner	'concat'

Error	Operational consequence	Cost shape
False Negative (missed churner)	Account leaves silently. Multiple end customers leave with it (§1.1). Recurring revenue, cross-sell options and referral surface vanish.	High and recurring
False Positive (false alarm)	A retention call is placed to a stable account. Most produce a small upsell or do nothing. The account-level expected revenue × probability filter (§24) further damps the cost.	Low and one-time

Tier	Metric	Why it is here
Primary	Recall on class 1 (churners)	Minimises missed churners — the dominant business cost.
Secondary (guardrails)	F1, PR-AUC	Prevent the optimiser from drifting to a "predict everyone churns" degenerate solution.
Cost discipline	Precision	Tracks how many flagged accounts actually churn — feeds directly into the campaign cost case.
Audit	ROC-AUC, Accuracy	Reported for completeness, not used for selection.

#	Model	Why it earns its slot
1	Logistic Regression	Transparent baseline. Coefficients map directly to retention narrative (a complaint multiplies the log-odds of churn by …). Sets the bar every non-linear model must clear.
2	K-Nearest Neighbors (rubric)	The high-risk archetype of §12.4 ("new + Single + Regular Plus + complainer + non-card payer + desktop") is a co-occurrence pattern of traits — exactly the geometry KNN captures by construction. Stress-tests whether an instance-based view beats a parametric one.
3	Gaussian Naive Bayes (rubric)	A weak but principled lower bound. Its conditional-independence assumption is known to be violated (`Tenure` and `tenure_bucket` are deterministically related; `rev_per_month` and `rev_per_user` share signal). If it is competitive, that diagnoses a signal dominated by a few near-marginal features.
4	SVM (RBF) (rubric)	Non-linear margin model. Compares the kernel approach against tree ensembles on the same scaled feature space.
5	Random Forest	Bagging ensemble — robust to noise, mixed-scale features and the documented mild multicollinearity. Native feature importance feeds the interpretability layer.
6	Gradient Boosting	Sequential boosting with shallow trees. Often dominates Random Forest on structured tabular data with mixed categorical / continuous features — exactly the shape of this dataset.
7	XGBoost	Industry default for tabular classification: regularised boosting, native imbalance handling via `scale_pos_weight`, fast on this data size. The strongest expected non-linear contender.

	recall	f1	precision	pr_auc	roc_auc	accuracy	fit_seconds
model
Logistic Regression	0.8154	0.5919	0.4652	0.6985	0.8953	0.8104	1.300000
KNN	0.8082	0.8548	0.9075	0.9069	0.9811	0.9538	0.900000
Gaussian Naive Bayes	0.7680	0.5222	0.3960	0.5935	0.8404	0.7630	0.800000
SVM (RBF)	0.9170	0.7690	0.6627	0.8480	0.9674	0.9071	3.700000
Random Forest	0.8009	0.8645	0.9402	0.9529	0.9887	0.9578	1.500000
Gradient Boosting	0.6216	0.7072	0.8214	0.8164	0.9401	0.9134	1.800000
XGBoost	0.9156	0.9043	0.8934	0.9647	0.9893	0.9674	0.900000

Search strategy	When	Why
GridSearchCV	Logistic Regression, KNN, Naive Bayes, SVM, Gradient Boosting	Small, well-understood grids — exhaustive search is cheap and the global optimum is recoverable.
RandomizedSearchCV (30 iterations)	Random Forest, XGBoost	High-dimensional grids (5+ hyperparameters). At fixed budget, random search beats grid search when ≥ 3 hyperparameters meaningfully affect the loss surface — both ensembles qualify.

	cv_best_recall	best_params	fit_seconds
model
SVM (RBF)	0.932	{'clf__C': 5, 'clf__gamma': 'scale'}	22.200
XGBoost	0.921	{'clf__subsample': 1.0, 'clf__reg_lambda': 1.0...	7.300
KNN	0.913	{'clf__n_neighbors': 3, 'clf__p': 1, 'clf__wei...	1.300
Random Forest	0.844	{'clf__n_estimators': 200, 'clf__min_samples_s...	26.100
Gradient Boosting	0.825	{'clf__learning_rate': 0.1, 'clf__max_depth': ...	21.700
Logistic Regression	0.818	{'clf__C': 0.1}	1.000
Gaussian Naive Bayes	0.768	{'clf__var_smoothing': 1e-12}	0.100

	recall	f1	precision	pr_auc	roc_auc	accuracy
model
SVM (RBF)	0.9321	0.8613	0.8008	0.9277	0.9846	0.9494
XGBoost	0.9209	0.9101	0.8997	0.9660	0.9897	0.9694
KNN	0.9130	0.9221	0.9315	0.9686	0.9883	0.9740
Random Forest	0.8438	0.8037	0.7684	0.8999	0.9755	0.9305
Gradient Boosting	0.8247	0.8666	0.9135	0.9468	0.9845	0.9573
Logistic Regression	0.8181	0.5960	0.4692	0.7024	0.8944	0.8129
Gaussian Naive Bayes	0.7680	0.5222	0.3960	0.5935	0.8404	0.7630

	baseline_recall	baseline_f1	baseline_pr_auc	tuned_recall	tuned_f1	tuned_pr_auc	delta recall	delta f1	delta pr_auc
model
SVM (RBF)	0.917	0.769	0.848	0.932	0.861	0.928	0.015	0.092	0.080
XGBoost	0.916	0.904	0.965	0.921	0.910	0.966	0.005	0.006	0.001
KNN	0.808	0.855	0.907	0.913	0.922	0.969	0.105	0.067	0.062
Random Forest	0.801	0.864	0.953	0.844	0.804	0.900	0.043	-0.061	-0.053
Gradient Boosting	0.622	0.707	0.816	0.825	0.867	0.947	0.203	0.159	0.130
Logistic Regression	0.815	0.592	0.698	0.818	0.596	0.702	0.003	0.004	0.004
Gaussian Naive Bayes	0.768	0.522	0.593	0.768	0.522	0.593	0.000	0.000	0.000

Model	ΔRecall	ΔF1	ΔPR-AUC	What happened
Gradient Boosting	+0.203	+0.159	+0.130	Largest lift in the panel — defaults were clearly wrong, deeper trees rescued real performance.
KNN	+0.105	+0.067	+0.062	The §8 hypothesis holds: distance weighting + `k=3` move KNN from middle to top of the leaderboard.
Random Forest	+0.043	−0.061	−0.053	Recall improved but F1 fell — the deeper trees over-flag churn. Net loss in business terms.
SVM (RBF)	+0.015	+0.092	+0.080	Recall already near ceiling; tuning bought Precision and PR-AUC instead — a clean trade.
XGBoost	+0.005	+0.006	+0.001	Already at the loss-surface plateau. Tuning confirmed the defaults — useful information.
Logistic Regression	+0.003	+0.004	+0.004	Linear ceiling reached. The model's job is interpretability, not winning.
Gaussian Naive Bayes	0.000	0.000	0.000	`var_smoothing` is a numerical guard, not a real hyperparameter. As expected.

Model	Recall	F1	PR-AUC	Rule outcome
KNN	0.913	0.922	0.969	Selected — highest F1, highest PR-AUC.
XGBoost	0.921	0.910	0.966	Runner-up.
SVM (RBF)	0.932	0.861	0.928	Highest Recall, but F1 lags by ~6 points → over-flags.

Capstone Project — AIML

Account-Level Churn Prediction for an E-Commerce / DTH Operator

1 — Strategic framing¶

1.1 Why this project exists¶

1.2 What this milestone delivers¶

1.3 What success looks like after Milestone 2¶

1.4 Dataset dictionary (as provided)¶

2 — Analytical environment¶

2.1 Reusable helpers¶

3 — Data ingestion and initial landscape¶

4 — Data overview and quality diagnostic¶

5 — Cleaning pipeline¶

6 — Missing value strategy¶

7 — Target profile¶

8 — Exploratory findings (Univariate, Bivariate and Multivariate)¶

8.1 Tenure — the dominant protective factor¶

8.2 Complaints — an operational early-warning signal¶

8.3 Commercial segment and geography¶

8.4 Payment method — a proxy for platform commitment¶

8.5 Customer profile — marital status, gender, device¶

8.6 Engagement decay — the composite signal¶

8.7 Correlation structure¶

8.8 Multivariate analysis — the high-risk archetype¶

9 — Outlier handling¶

10 — Feature synthesis¶

11 — Variable transformation¶

12 — Business insights from EDA¶

12.1 Class imbalance and what it implies¶

12.2 Univariate observations worth acting on¶

12.3 Bivariate — who churns and why¶

12.4 What the combination tells us¶

13 — Modelling roadmap¶

13.1 Data contracts¶

13.2 Candidate models¶

13.3 Evaluation metrics¶

13.4 Imbalance handling¶

13.5 Interpretability¶

13.6 Final business outputs¶

Milestone 2 — Model building, hyperparameter tuning, comparison and final selection¶

14 — Modelling contract carried forward from Milestone 1¶

15 — Supervised-learning stack¶

15.1 One small helper¶

16 — Feature contract and stratified split¶

16.1 Drop the raw versions of the log-transformed columns¶

16.2 Stratified 80 / 20 split — the test set is locked¶

16.3 Single preprocessing pipeline — the leakage guard¶

16.4 Cross-validation protocol¶

17 — Why Recall, and what travels with it¶

17.1 The asymmetry of error costs¶

17.2 The metric framework¶

18 — Baseline modelling pass¶

18.1 Why these seven models — defended one by one¶

18.2 Run the baseline pass¶

18.3 Visual leaderboard — Recall, F1, PR-AUC¶

18.4 Reading the baseline pass¶

19 — Hyperparameter tuning¶

19.1 Search specifications¶

19.2 Run the tuning loop¶

19.3 Re-evaluate the tuned pipelines on the full scoring panel¶

20 — Model comparison and final selection¶

20.1 Leaderboard (training CV, tuned models)¶

20.2 Visual comparison — leaderboard and the recall-precision frontier¶

20.3 Selection rule — declared before reading the leaderboard¶

21 — Held-out evaluation of the chosen model¶

21.1 Test-set metrics — full panel¶

21.2 Confusion matrix and classification report¶

21.3 ROC and Precision-Recall curves¶

22 — Threshold and lift — translating the model to a campaign list¶

22.1 Threshold sweep on the test set¶

22.2 Decile lift — top-N targeting¶

23 — Interpretability of the chosen model¶

23.1 Global feature importance¶

23.2 SHAP — per-account explanations¶

24 — Sensitivity test — SMOTE inside the pipeline¶

25 — Milestone 2 closing¶

25.1 What was delivered¶

25.2 What feeds Milestone 3¶

25.3 Honest limitations (carried into the model card)¶

26 — Business recommendations and campaign blueprint¶

26.1 The campaign blueprint — score, segment, act¶

	KNN - test set
Recall	0.9472
F1	0.9523
Precision	0.9573
PR-AUC	0.9787
ROC-AUC	0.9894
Accuracy	0.9840

Metric	CV (5-fold, train)	Test (held out)	Gap
Recall	0.913	0.947	+0.034
F1	0.922	0.952	+0.030
Precision	0.931	0.957	+0.026
PR-AUC	0.969	0.979	+0.010
ROC-AUC	0.988	0.989	+0.001

	threshold	recall	precision	f1	flagged
0	0.050	0.982	0.770	0.863	483
1	0.100	0.982	0.775	0.866	480
2	0.150	0.982	0.786	0.873	473
3	0.200	0.982	0.803	0.884	463
4	0.250	0.982	0.832	0.901	447
5	0.300	0.982	0.877	0.926	424
6	0.350	0.971	0.939	0.955	392
7	0.400	0.963	0.951	0.957	384
8	0.450	0.953	0.955	0.954	378
9	0.500	0.947	0.957	0.952	375
10	0.550	0.945	0.957	0.951	374
11	0.600	0.942	0.962	0.952	371
12	0.650	0.934	0.981	0.957	361
13	0.700	0.910	0.989	0.948	349
14	0.750	0.855	0.997	0.920	325
15	0.800	0.815	0.997	0.897	310
16	0.850	0.781	0.997	0.876	297
17	0.900	0.755	0.997	0.859	287
18	0.950	0.752	0.997	0.857	286

Bucket	Accounts	Churners	Churn rate	Lift vs base	Cumulative capture
D1 (high score)	451	372	82.5%	4.9×	98.2%
D2 (low score)	1,801	7	0.4%	0.02×	100.0%

	Tuned (class-weight)	Tuned + SMOTE	delta (SMOTE - weight)
recall	0.913	0.968	0.055
f1	0.922	0.916	-0.006
precision	0.931	0.870	-0.062
pr_auc	0.969	0.940	-0.029
roc_auc	0.988	0.987	-0.001

Metric	Tuned KNN	Tuned KNN + SMOTE	Δ
Recall	0.913	0.968	+0.055
F1	0.922	0.916	−0.006
Precision	0.931	0.870	−0.062
PR-AUC	0.969	0.940	−0.029
ROC-AUC	0.988	0.987	−0.001

Step	Action	Output
1. Score	Run the trained pipeline on every active account every Monday.	A churn probability per account + a top-N priority list ranked by probability × expected revenue.
2. Segment	Group at-risk accounts by the multivariate archetype: tenure bucket × complaint history × payment method.	Three operational segments, each with a dedicated retention play (§26.2).
3. Act	Each segment receives a specific offer. Outreach handled by the existing CRM team. Outcomes logged.	A closed-loop dataset that feeds the next quarterly retraining (§26.4).


Trigger	Tenure < 6 months AND no complaint history
Logic	This is the highest-volume churn pocket (35.8% bivariate rate, §8.1). The accounts have not had a service issue — they are leaving because value has not landed yet.
Offer	Free onboarding session with a Customer Success Manager + a service-feature walkthrough. No price discount.
Cost per account	$15–30 (CSM time only — zero product subsidy)
Saved revenue	~$200 ARPU × multiple end users per account
Revenue Assurance hook	The cost is internal labour, not subsidy. The walkthrough is also a soft upsell channel — net cost can be negative on a fraction of cases.


Trigger	Has filed at least one complaint in the last 12 months
Logic	Complaint is the second-strongest bivariate signal (31.8%, §8.2) and the only one that is observable before the model score is computed. This play should fire on every complainer, regardless of model score — it is a quick win independent of the model rollout (§26.3).
Offer	Senior support callback + complaint resolution audit + small service credit only if the SLA was missed.
Cost per account	$25–50 (credit conditional on verified service failure)
Saved revenue	Account retention + reputation lift on social channels
Revenue Assurance hook	Credit is contingent on verified failure, not granted by default. Reputation lift is a real but unbookable benefit — the cost case stands on retention alone.


Trigger	Pays Cash on Delivery / E-Wallet AND tenure 6–24 months
Logic	The bivariate gap is large (~25% churn on Cash-on-Delivery vs ~14% on Credit Card, §8.4). Card-on-file customers face administrative friction to leave — they do not "shop around" weekly. This play converts the friction asymmetry itself into a retention lever.
Offer	One-time $5–10 cashback for setting up auto-pay on a Credit/Debit card.
Cost per account	$5–10 one-time
Saved revenue	Card-on-file customers churn at ~14% vs ~25% on cash — a ~11-point lift, against ARPU of ~$200/yr
Revenue Assurance hook	The cost is one-time and fixed; the saved revenue is recurring. Break-even is reached in <1 month per saved account.