Proyecto final: churn de telecomunicaciones

Objetivo

Resolver de extremo a extremo un problema real de abandono de clientes con documentación, evaluación y despliegue.

Dataset real

• Dataset: iranian_churn
• Fuente: UCI
• Referencia: https://archive.ics.uci.edu/dataset/563/iranian+churn+dataset
• Licencia/condiciones: CC BY 4.0
• Uso: los datos se descargan desde la fuente; no hay ejemplos sintéticos ni archivos inventados.

3.150 clientes recolectados aleatoriamente de la base de una empresa iraní de telecomunicaciones durante 12 meses.

Fundamento matemático

Clasificación, calibración, selección de umbral y costo de errores.

Protocolo experimental

1. Descargar y verificar la procedencia.
2. Conservar o crear una partición reproducible.
3. Ajustar transformaciones únicamente con train.
4. Seleccionar modelo e hiperparámetros usando validation.
5. Evaluar test una sola vez tras congelar la decisión.
6. Comparar con la línea base: Regresión logística y Gradient Boosting.
7. Guardar configuración, entorno, métricas, predicciones, gráficos y modelo.

Ejecución

python labs/24_capstone_real_project/train.py --quick
python labs/24_capstone_real_project/train.py --config improved

Preparar únicamente el dataset:

python -m neural_labs.cli dataset --lab 24_capstone_real_project

Inferencia y exportación:

neural-labs predict --lab 24_capstone_real_project --run latest --input sample.json
neural-labs export --lab 24_capstone_real_project --run latest --format onnx --verify

Métricas

accuracy, balanced_accuracy, precision, recall, f1, roc_auc, pr_auc.

Archivos

• notebook.ipynb: recorrido completo y ejecutable.
• notebook_student.ipynb: actividades evaluables sin soluciones.
• notebook_solution.ipynb: resolución docente y pruebas de referencia.
• train.py: interfaz de terminal que usa el mismo código del cuaderno.
• configs/baseline.yaml: configuración base.
• configs/improved.yaml: configuración ampliada.
• data/dataset.yaml: procedencia, licencia y política de partición.

Ejercicios

• Cambiar una decisión experimental y justificarla.
• Analizar errores por clase o segmento.
• Comparar costo, precisión y latencia.
• Documentar sesgos, limitaciones y usos no recomendados.

Material formativo v3

• theory.md: fundamento, protocolo y riesgos de interpretación.
• experiments.md: hipótesis, variables controladas y tabla multi-semilla.
• assessment.md: preguntas y rúbrica de evaluación.
• lesson.yaml: resultados de aprendizaje, prerrequisitos y entregables.

Comandos profesionales

neural-labs quality --lab 24_capstone_real_project --quick
neural-labs benchmark --lab 24_capstone_real_project --quick --split-seed 42 --training-seeds 41 42 43
neural-labs leaderboard

Sellado del experimento

La partición se controla con split_seed; la inicialización y el entrenamiento con training_seed. El conjunto test se abre solamente después de seleccionar el checkpoint mediante validación y escribir experiment.lock.json.

🧠 Teoría

Teoría — Proyecto final: churn de telecomunicaciones

Propósito

Resolver de extremo a extremo un problema real de abandono de clientes con documentación, evaluación y despliegue.

Idea central

Este laboratorio estudia proyecto integral de churn usando iranian_churn, un dataset público real procedente de UCI.

El churn —abandono de clientes— es un problema de negocio antes que un problema de aprendizaje: una operadora quiere anticipar qué clientes dejarán el servicio para intervenir con retención. Traducirlo a un modelo obliga a recorrer todo el ciclo de vida de un proyecto de ML: entender los datos y su procedencia, definir la métrica que importa, construir líneas base honestas, entrenar y calibrar, elegir un umbral de decisión ligado al costo de los errores, y documentar el resultado para que sea auditable y desplegable. Este capstone integra todo lo aprendido en los laboratorios anteriores sobre un caso real: 3.150 clientes de una empresa iraní de telecomunicaciones seguidos durante 12 meses.

Lo distintivo de un proyecto end-to-end es que la exactitud bruta rara vez es la meta. El churn es un problema desbalanceado (los que se van son minoría) y con costos asimétricos: no cuesta lo mismo dejar escapar a un cliente que se iba (falso negativo, se pierde su valor) que ofrecer una promoción a alguien que se quedaba igual (falso positivo, gasto innecesario). Por eso el laboratorio insiste en métricas sensibles al desbalance, en calibración de probabilidades y en la selección de umbral como decisión de negocio, comparando siempre contra líneas base sólidas: regresión logística y gradient boosting.

Fundamento matemático

Clasificación, calibración, selección de umbral y costo de errores.

El modelo produce una probabilidad de abandono p = P(churn | x) para cada cliente, pero la decisión de actuar requiere un umbral τ: se interviene si p ≥ τ. La elección de τ no es un detalle técnico, sino donde entra la economía del problema. Cada resultado tiene un costo: un verdadero positivo detectado permite una acción de retención; un falso negativo (τ demasiado alto) deja escapar clientes; un falso positivo (τ demasiado bajo) malgasta recursos. Si asignamos costos c_FN y c_FP a cada tipo de error, el umbral óptimo minimiza el costo esperado y, bajo el análisis clásico, satisface una relación de la forma τ* = c_FP / (c_FP + c_FN): cuanto más caro es dejar escapar a un cliente (c_FN grande), más bajo conviene poner el umbral para capturar a más candidatos. Este umbral se elige en validación, nunca en test.

Como el umbral depende de la probabilidad, esa probabilidad debe ser confiable, y aquí reaparece la calibración del laboratorio 22: un modelo sobreconfiado desplaza el punto de operación y distorsiona el análisis de costos. Por eso, antes de fijar τ, conviene recalibrar (p. ej. con temperature scaling o Platt scaling) para que p ≈ frecuencia real de churn. Para evaluar el modelo con independencia del umbral se usan métricas basadas en el ranking: el ROC-AUC mide la probabilidad de ordenar correctamente un par (cliente que abandona, cliente que se queda), mientras que el PR-AUC (precisión–recall) es más informativo en datos desbalanceados porque se centra en la clase positiva minoritaria y no se deja "inflar" por la abundancia de negativos. La balanced accuracy —media de la sensibilidad y la especificidad— corrige el sesgo de la exactitud simple cuando las clases están desequilibradas.

La cadena de razonamiento del capstone es, entonces: entrenar un clasificador → recalibrar sus probabilidades → medir su capacidad de ordenamiento con AUC/PR-AUC de forma independiente del umbral → traducir esa capacidad en una política de decisión eligiendo τ según los costos del negocio en validación → y solo entonces reportar el desempeño una única vez en test. La contribución matemática no está en un algoritmo nuevo, sino en encadenar correctamente clasificación, calibración, coste y umbral para que el número final sea una decisión responsable y no una métrica aislada.

Protocolo científico

• Ajustar transformaciones, vocabulario, normalización y selección de variables solo con train.
• Usar validation para arquitectura, hiperparámetros, checkpoint y umbrales.
• Evaluar test una vez, después de congelar las decisiones.
• Comparar contra Regresión logística y Gradient Boosting.
• Reportar variación entre semillas e intervalos de confianza; una métrica puntual no expresa toda la incertidumbre.

Riesgos de interpretación

3.150 clientes recolectados aleatoriamente de la base de una empresa iraní de telecomunicaciones durante 12 meses.

El dataset refleja su proceso de recolección y no representa automáticamente otros períodos, países o poblaciones. Una asociación predictiva no demuestra causalidad.

Pregunta crítica

¿Cómo convertir resultados en una decisión responsable?

🔗 Referencias

Las referencias apuntan a las obras; no se reproduce su contenido, la redacción es original.

• Géron — Hands-On Machine Learning with Scikit-Learn, Keras & TensorFlow (3.ª ed., O'Reilly, 2022), cap. 2 — recorrido completo de un proyecto de ML de punta a punta, del marco del problema al despliegue.
• Huyen — Designing Machine Learning Systems (O'Reilly, 2022) — diseño de sistemas de ML en producción: métricas de negocio, monitorización y despliegue responsable.
• Kuhn y Johnson — Applied Predictive Modeling (Springer, 2013) — modelado predictivo aplicado: preprocesamiento, evaluación con clases desbalanceadas y selección de umbral.
• Fuente del dataset: https://archive.ics.uci.edu/dataset/563/iranian+churn+dataset
• Consulte docs/experiment-protocol.md, docs/reproducibility.md y docs/ethics-and-licenses.md.

🔬 Experimentos

Plan de experimentos — Proyecto final: churn de telecomunicaciones

Hipótesis principal

Resolver de extremo a extremo un problema real de abandono de clientes con documentación, evaluación y despliegue. La hipótesis debe aceptarse o rechazarse comparando el modelo con Regresión logística y Gradient Boosting y no solo observando que la pérdida disminuye.

Experimento mínimo

1. Ejecutar baseline.yaml con tres semillas.
2. Ejecutar improved.yaml con las mismas semillas.
3. Mantener fija la partición de datos dentro de cada semilla.
4. Elegir la variante con validation.
5. Comparar la variante elegida contra la línea base en test.
6. Revisar intervalos de confianza, errores y costo computacional.

Experimento específico

Formular hipótesis, segmentar errores y documentar riesgos.

Variables controladas

• Dataset y política de partición.
• Semillas declaradas.
• Presupuesto de épocas y criterio de parada.
• Métrica de selección: accuracy o la especificada en la configuración.
• Hardware y versiones registradas en environment.json.

Tabla que debe completarse

Criterio de conclusión

La conclusión debe declarar magnitud de la mejora, incertidumbre, costo adicional, errores relevantes y condiciones bajo las cuales el resultado podría no repetirse.

📝 Evaluación

Evaluación — Proyecto final: churn de telecomunicaciones

Evidencias obligatorias

• Dataset preparado y auditoría sin solapamientos.
• Notebook ejecutado sin celdas omitidas.
• Línea base y modelo neuronal comparados.
• Resultados de al menos tres semillas o justificación del costo.
• Análisis de errores y limitaciones.
• Model card actualizada.

Preguntas

1. Explique con sus palabras: Clasificación, calibración, selección de umbral y costo de errores.
2. ¿Qué información del dataset solo puede utilizarse durante entrenamiento?
3. ¿Por qué la línea base Regresión logística y Gradient Boosting es una comparación razonable?
4. ¿Cómo convertir resultados en una decisión responsable?
5. ¿Qué cambiaría antes de usar este modelo fuera del laboratorio?

Rúbrica

La aprobación exige al menos 70% y cero errores críticos de fuga de datos.