Churn con valor económico

"""#1 Modelo de churn con valor económico.

Pregunta de negocio: ¿a quién contactamos en la campaña de retención y cuánto dinero
genera hacerlo?  Datos: IBM Telco Customer Churn (7,043 clientes, público).
"""
import numpy as np
import pandas as pd
from lightgbm import LGBMClassifier
from sklearn.compose import ColumnTransformer
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import roc_auc_score
from sklearn.model_selection import train_test_split
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler

from common import (SEED, bars, cumulative_gain_curve, download, export, gains_table, line,
                    table)
from validacion import (bootstrap_ci, calibracion_lineal, cv_clasificacion, explicacion_local,
                        graficas_validacion, model_card, resumen_cv, t_test_corregido)

URL = "https://raw.githubusercontent.com/IBM/telco-customer-churn-on-icp4d/master/data/Telco-Customer-Churn.csv"

# Supuestos de la campaña (editables en la página del portafolio)
COSTO_CONTACTO = 15.0      # USD por cliente contactado (llamada + incentivo)
TASA_RETENCION = 0.30      # % de los que se iban y se quedan gracias a la campaña
MESES_VALOR = 12           # meses de ingreso que se preservan al retener
MARGEN = 0.40              # margen sobre el ingreso mensual (no todo el ingreso es utilidad)


def load() -> pd.DataFrame:
    df = pd.read_csv(download(URL, "telco_churn.csv"))
    df["TotalCharges"] = pd.to_numeric(df["TotalCharges"], errors="coerce").fillna(0)
    df["Churn"] = (df["Churn"] == "Yes").astype(int)
    # Feature engineering con sentido de negocio
    servicios = ["PhoneService", "OnlineSecurity", "OnlineBackup", "DeviceProtection",
                 "TechSupport", "StreamingTV", "StreamingMovies"]
    df["n_servicios"] = (df[servicios] == "Yes").sum(axis=1)
    df["cargo_promedio"] = np.where(df["tenure"] > 0, df["TotalCharges"] / df["tenure"],
                                    df["MonthlyCharges"])
    df["autopago"] = df["PaymentMethod"].str.contains("automatic").astype(int)
    return df.drop(columns=["customerID"])


def profit_curve(y, score, monthly, steps=40):
    """Utilidad neta de contactar al top-k % según el score."""
    order = np.argsort(-score)
    y, monthly = y[order], monthly[order]
    valor = y * monthly * MESES_VALOR * MARGEN * TASA_RETENCION - COSTO_CONTACTO
    acum = np.cumsum(valor)
    pts = [[0.0, 0.0]]
    for k in np.linspace(len(y) / steps, len(y), steps).astype(int):
        pts.append([round(k / len(y) * 100, 1), round(float(acum[k - 1]), 0)])
    best_k = int(np.argmax(acum)) + 1
    return pts, best_k / len(y), float(acum[best_k - 1])


def modelos(num, cat):
    """Mismo preprocesamiento para todos (pipeline: sin fuga de información entre folds)."""
    pre = ColumnTransformer([("num", StandardScaler(), num),
                             ("cat", OneHotEncoder(handle_unknown="ignore", sparse_output=False), cat)],
                            verbose_feature_names_out=False)
    gbm = LGBMClassifier(n_estimators=300, learning_rate=0.03, num_leaves=8, min_child_samples=40,
                         subsample=0.8, subsample_freq=1, colsample_bytree=0.8, reg_lambda=1.0,
                         random_state=SEED, verbose=-1)
    return {
        "Regresión logística": make_pipeline(pre, LogisticRegression(max_iter=2000)),
        "Logística balanceada": make_pipeline(pre, LogisticRegression(max_iter=2000, class_weight="balanced")),
        "LightGBM": make_pipeline(pre, gbm),
    }


def run():
    df = load()
    y = df.pop("Churn").values
    cat = df.select_dtypes("object").columns.tolist()
    num = [c for c in df.columns if c not in cat]
    X_tr, X_te, y_tr, y_te = train_test_split(df, y, test_size=0.3, stratify=y, random_state=SEED)
    mods = modelos(num, cat)

    # 1) Validación cruzada 5×2 en entrenamiento: misma partición para los tres modelos
    cv = cv_clasificacion(mods, X_tr, y_tr, folds=5, repeticiones=2)
    a, b = cv[cv.modelo == "Regresión logística"].AUC, cv[cv.modelo == "LightGBM"].AUC
    dif, p_val = t_test_corregido(a.values, b.values, n_train=int(len(X_tr) * 0.8), n_test=int(len(X_tr) * 0.2))

    # 2) Ajuste final y evaluación en el set de prueba (nunca visto durante la CV)
    fit = {k: m.fit(X_tr, y_tr) for k, m in mods.items()}
    p = {k: m.predict_proba(X_te)[:, 1] for k, m in fit.items()}
    auc_log, lo_log, hi_log = bootstrap_ci(y_te, p["Regresión logística"])
    auc_gbm, lo_gbm, hi_gbm = bootstrap_ci(y_te, p["LightGBM"])
    best_name = "Regresión logística"   # elegido por CV (empate estadístico → el más explicable)
    p_best = p[best_name]
    pend, interc = calibracion_lineal(y_te, p_best)
    pend_bal, _ = calibracion_lineal(y_te, p["Logística balanceada"])
    media_bal = p["Logística balanceada"].mean()

    # 3) Explicabilidad: SHAP de LightGBM (global agregado por variable original + local)
    pre, gbm = fit["LightGBM"][0], fit["LightGBM"][-1]
    Xte_t = pd.DataFrame(pre.transform(X_te), columns=pre.get_feature_names_out())
    contrib = gbm.predict(Xte_t, pred_contrib=True)[:, :-1]
    origen = [next(c for c in num + cat if f == c or f.startswith(c + "_")) for f in Xte_t.columns]
    shap_var = pd.DataFrame(np.abs(contrib), columns=origen).T.groupby(level=0).sum().T.mean()
    shap_var = shap_var.sort_values(ascending=False)
    contrib_var = pd.DataFrame(contrib, columns=origen).T.groupby(level=0).sum().T
    i_top = int(np.argmax(p["LightGBM"]))
    etiquetas, valores = explicacion_local(contrib_var.iloc[i_top].values, list(contrib_var.columns),
                                           X_te.iloc[i_top])
    # Coeficientes de la logística como razones de momios (variables numéricas estandarizadas)
    lr = fit["Regresión logística"][-1]
    coefs = pd.Series(lr.coef_[0], index=fit["Regresión logística"][0].get_feature_names_out())
    coefs = coefs.sort_values()
    coefs = pd.concat([coefs.head(6), coefs.tail(6)])

    # 4) Valor económico con incertidumbre (bootstrap de la curva de utilidad)
    monthly = X_te["MonthlyCharges"].values
    curve_model, best_frac, best_profit = profit_curve(y_te, p_best, monthly)
    rng = np.random.default_rng(SEED)
    curve_rand, _, _ = profit_curve(y_te, rng.random(len(y_te)), monthly)
    boot = []
    for _ in range(300):
        idx = rng.integers(0, len(y_te), len(y_te))
        boot.append([v for _, v in profit_curve(y_te[idx], p_best[idx], monthly[idx])[0]])
    lo_b, hi_b = np.percentile(boot, [5, 95], axis=0)
    banda = [[x, float(l), float(h)] for (x, _), l, h in zip(curve_model, lo_b, hi_b)]
    optimos = np.array([max(b) for b in boot])

    order = np.argsort(-p_best)
    captura_top20 = y_te[order[: int(len(y_te) * 0.2)]].sum() / y_te.sum()
    g = gains_table(y_te, p_best)
    g_tbl = g.assign(tasa=lambda d: (d.tasa * 100).round(1), captura_acum=lambda d: (d.captura_acum * 100).round(1),
                     lift=lambda d: d.lift.round(2), score_min=lambda d: d.score_min.round(3))
    g_tbl.columns = ["Decil", "Clientes", "Churners", "Score mínimo", "Tasa churn %", "Captura acum. %", "Lift"]
    cv_tbl = resumen_cv(cv)
    cv_auc = cv.groupby("modelo", sort=False).AUC

    escala = 1 / 0.3  # el set de prueba es 30 % de la cartera
    result = {
        "title": "Churn con valor económico",
        "summary": [
            f"Validación cruzada 5×2: logística AUC {a.mean():.3f} ± {a.std():.3f} vs. LightGBM {b.mean():.3f} ± "
            f"{b.std():.3f}; la diferencia ({dif:+.3f}) no es significativa (t corregido, p = {p_val:.2f}). "
            "Ante empate se elige el modelo explicable.",
            f"En prueba: AUC {auc_log:.3f} (IC 95 % {lo_log:.3f}–{hi_log:.3f}); contactar al 20 % con mayor riesgo "
            f"captura el {captura_top20:.0%} de las cancelaciones.",
            f"Óptimo económico: contactar al {best_frac:.0%} de la cartera, utilidad ≈ ${best_profit * escala:,.0f}/año "
            f"(IC 90 % ${np.percentile(optimos, 5) * escala:,.0f}–${np.percentile(optimos, 95) * escala:,.0f}).",
            f"Buena práctica: NO usar class_weight='balanced' cuando el score alimenta un cálculo de dinero; infla "
            f"la probabilidad media a {media_bal:.0%} vs. {y_te.mean():.0%} real. La logística sin ponderar está "
            f"calibrada (pendiente {pend:.2f}, intercepto {interc:+.2f}).",
            "Impulsores (SHAP): contrato mes a mes, baja antigüedad y fibra óptica. Palanca de retención: "
            "migrar a contratos de plazo en los primeros meses.",
        ],
        "metrics": [
            {"label": "AUC CV logística", "value": f"{a.mean():.3f} ± {a.std():.3f}"},
            {"label": "AUC prueba (IC 95 %)", "value": f"{auc_log:.3f} [{lo_log:.2f}–{hi_log:.2f}]"},
            {"label": "Captura top 20 %", "value": f"{captura_top20:.0%}"},
            {"label": "Utilidad anual óptima", "value": f"${best_profit * escala:,.0f}"},
        ],
        "charts": [
            line("profit", "Utilidad neta de la campaña según % de cartera contactada",
                 {"Modelo": curve_model, "Al azar": curve_rand},
                 x_label="% de clientes contactados (ordenados por riesgo)", y_label="USD (set de prueba)",
                 fmt="usd", bands={"Modelo": banda},
                 subtitle=f"Banda: IC 90 % bootstrap · costo ${COSTO_CONTACTO:.0f} · retención {TASA_RETENCION:.0%} · margen {MARGEN:.0%}"),
            bars("cv", "AUC por modelo en validación cruzada 5×2 (media)", cv_auc.mean().index,
                 cv_auc.mean().round(4).values, fmt="dec",
                 subtitle="Detalle ± desviación en la tabla de validación"),
            *graficas_validacion(y_te, {"Logística": p_best, "LightGBM": p["LightGBM"],
                                        "Logística balanceada": p["Logística balanceada"]}),
            line("gain", "Curva de ganancia acumulada",
                 {best_name: cumulative_gain_curve(y_te, p_best), "Al azar": [[0, 0], [100, 100]]},
                 x_label="% de clientes contactados", y_label="% de churners capturados", fmt="pct"),
            bars("shap", "Explicabilidad global: |SHAP| promedio por variable (LightGBM)", shap_var.index[:12],
                 shap_var.values[:12].round(3), fmt="dec"),
            bars("local", "Explicabilidad local: ¿por qué el cliente de mayor riesgo?", etiquetas, valores,
                 fmt="dec", subtitle=f"Contribución SHAP en log-odds · prob. de churn {p['LightGBM'][i_top]:.0%}"),
            bars("coef", "Coeficientes de la logística (log-odds): positivo sube el riesgo, negativo lo baja", coefs.index,
                 coefs.round(3).values, fmt="dec",
                 subtitle="Razón de momios = e^coef · numéricas estandarizadas · one-hot con regularización L2"),
        ],
        "tables": [table("Validación cruzada 5×2 (media ± desviación)", cv_tbl),
                   table("Tabla de ganancia por decil", g_tbl)],
        "card": model_card(
            "Regresión logística sobre variables escaladas y one-hot, comparada con LightGBM y con una logística "
            "balanceada. Selección por validación cruzada; decisión por curva de utilidad.",
            ["Split 70/30 estratificado; la CV 5×2 usa solo el 70 % de entrenamiento.",
             "Comparación de modelos con t-test corregido de Nadeau-Bengio (folds no independientes).",
             "IC bootstrap (500 réplicas) para AUC y (300) para la curva de utilidad.",
             "Calibración: curva por deciles + pendiente/intercepto de calibración."],
            [f"Costo por contacto ${COSTO_CONTACTO:.0f}, retención {TASA_RETENCION:.0%}, margen {MARGEN:.0%}, "
             f"{MESES_VALOR} meses de valor (editables en el simulador).",
             "La campaña tiene el mismo efecto en todos los clientes en riesgo (ver uplift, proyecto #3)."],
            ["Datos de telecomunicaciones (proxy de un portafolio de crédito); corte transversal sin fechas, "
             "por lo que no hay validación fuera de tiempo.",
             "SHAP explica el modelo, no causalidad: un impulsor no garantiza que moverlo reduzca el churn."]),
        "assumptions": {"costo_contacto": COSTO_CONTACTO, "tasa_retencion": TASA_RETENCION,
                        "meses_valor": MESES_VALOR, "margen": MARGEN},
    }
    sample = pd.DataFrame({"score": p_best.round(4), "churn": y_te, "monthly": monthly})
    export("p01-churn", result, sample)
    return result


if __name__ == "__main__":
    run()