Neurona con NumPy

Antes de tocar el código

Imagina una frontera que empieza equivocándose al azar y se mueve un poco después de cada error. En esta clase podrás ver y calcular cada uno de esos movimientos.

Pregunta esencial: ¿Cómo aprende una neurona si no existe autograd?

Haz una predicción antes de ejecutar el notebook. Al final volverás a ella y tendrás que decir qué evidencia la confirmó, la corrigió o la dejó abierta.

Mapa de esta clase: Del error al movimiento de la frontera. La figura no es decorativa; úsala para explicar el mecanismo con tus propias palabras.

🎯 Qué vas a aprender y construir

Implementar propagación, entropía cruzada y descenso de gradiente sin autograd.

Práctica propia de esta clase: Derivar el gradiente, comprobarlo con diferencias finitas y observar cómo la escala de las variables cambia el descenso.

Es la clase 01 de 31 del programa y pertenece a 🟢 el módulo 1, Fundamentos: de la derivada a la primera red. Es el punto de partida; después viene Perceptrón con PyTorch.

Trabajarás con el dataset breast_cancer_wisconsin (UCI, licencia: CC BY 4.0), y tendrás que superar la línea base DummyClassifier y regresión logística de scikit-learn, decidiendo con la métrica f1 medida sobre validation. Nivel fundamentos, unas 4 horas de dedicación.

Lo que conviene traer resuelto de las clases anteriores: Python básico, NumPy, álgebra lineal elemental.

Al terminar deberías ser capaz de:

• Implementar propagación, entropía cruzada y descenso de gradiente sin autograd.
• Preparar y auditar el dataset real breast_cancer_wisconsin sin fuga de datos.
• Entrenar y evaluar regresión logística implementada sin autograd.
• Comparar contra la línea base: DummyClassifier y regresión logística de scikit-learn.
• Interpretar intervalos de confianza, errores y limitaciones.

Una idea que conviene desmontar

El gradiente no indica dónde está el mínimo; indica la pendiente local y cuánto cambia la pérdida en ese punto.

🧠 Comprender antes de entrenar

Esta sección es la explicación completa del tema. No hace falta abrir otro archivo para entender lo que viene después: aquí está la idea, la matemática que la sostiene y sus límites. (El mismo texto vive en theory.md, que es la fuente desde la que se genera esta guía, junto con la bibliografía del final.)

De qué trata

Este laboratorio estudia regresión logística implementada sin autograd usando breast_cancer_wisconsin, un dataset público real procedente de UCI.

La regresión logística es la unidad de construcción más simple del aprendizaje profundo: una sola neurona que combina linealmente sus entradas y las pasa por una no linealidad suave. Aquí no delegamos nada en un motor de diferenciación automática; escribimos a mano la propagación hacia adelante, la pérdida y las derivadas. El objetivo pedagógico es doble: entender de dónde salen los gradientes (no aparecen por magia) y comprobar que una neurona bien planteada resuelve un problema clínico real de diagnóstico binario (tumor benigno frente a maligno) a partir de 30 medidas morfológicas del núcleo celular.

Al forzar la derivación explícita, el laboratorio hace visible la cadena completa: cada peso wⱼ tiene una responsabilidad concreta sobre el error, y esa responsabilidad es exactamente lo que el gradiente cuantifica. Cuando en los laboratorios siguientes deleguemos esto en autograd, sabremos qué está calculando la máquina por debajo.

La matemática, paso a paso

El modelo predice la probabilidad de que la clase sea positiva combinando las entradas de forma lineal y aplastando el resultado al intervalo (0, 1) con la función logística (sigmoide):

p(y=1 | x) = σ(z), con z = x·w + b = Σⱼ xⱼwⱼ + b, y σ(z) = 1 / (1 + e⁻ᶻ)

La sigmoide convierte una puntuación real ilimitada z en una probabilidad. Su forma en "S" comprime valores muy negativos hacia 0 y muy positivos hacia 1, dejando la mayor sensibilidad alrededor de z = 0, donde σ(0) = 0.5 marca la frontera de decisión. El sesgo b desplaza esa frontera y los pesos w orientan el hiperplano separador en el espacio de las 30 características.

Para ajustar los parámetros medimos el desacuerdo con la entropía cruzada binaria (equivalente a la log-verosimilitud negativa de un modelo Bernoulli). Para un conjunto de N ejemplos:

L = −(1/N) Σᵢ [ yᵢ·ln(pᵢ) + (1 − yᵢ)·ln(1 − pᵢ) ]

Esta pérdida penaliza con fuerza creciente la confianza equivocada: si el modelo asigna pᵢ ≈ 0 a un caso realmente positivo, ln(pᵢ) → −∞. Elegir entropía cruzada en lugar del error cuadrático no es arbitrario: al combinarla con la sigmoide, el gradiente se simplifica de forma notable y evita las mesetas de aprendizaje que produciría σ′(z) elevada al cuadrado.

El resultado clave, que este laboratorio deriva a mano, es que el gradiente de la pérdida respecto a los parámetros depende solo del error de predicción (pᵢ − yᵢ):

∂L/∂wⱼ = (1/N) Σᵢ (pᵢ − yᵢ)·xᵢⱼ y ∂L/∂b = (1/N) Σᵢ (pᵢ − yᵢ)

La intuición es transparente: si el modelo predice de más (pᵢ > yᵢ), el gradiente empuja los pesos en dirección contraria a las entradas activas; si predice de menos, los empuja a favor. La magnitud del ajuste es proporcional tanto al error como al valor de la característica, por eso la escala de las variables importa: una variable con valores muy grandes domina el gradiente y desestabiliza la convergencia si no se normaliza.

Finalmente, el descenso de gradiente actualiza los parámetros iterativamente con una tasa de aprendizaje η:

w ← w − η·∇_w L ; b ← b − η·∂L/∂b

La formulación debe conectarse con cuatro elementos: representación de entrada, función del modelo, función de pérdida y regla de actualización. El notebook muestra las dimensiones de los tensores y conserva la misma implementación que el script de terminal.

La derivación completa, sin saltarse pasos

El resultado ∂L/∂wⱼ = (1/N)·Σᵢ (pᵢ − yᵢ)·xᵢⱼ es tan limpio que parece una coincidencia. No lo es, y verlo salir paso a paso es el objetivo de este laboratorio. Se aplica la regla de la cadena en tres tramos, ∂L/∂w = (∂L/∂p)·(∂p/∂z)·(∂z/∂w).

Primero, la derivada de la pérdida respecto de la probabilidad predicha. Derivando L = −[y·ln p + (1 − y)·ln(1 − p)]:

∂L/∂p = −y/p + (1 − y)/(1 − p) = (p − y) / (p·(1 − p)).

Segundo, la derivada de la sigmoide, que tiene una forma notable: como σ(z) = 1/(1 + e^(−z)),

σ′(z) = e^(−z) / (1 + e^(−z))² = σ(z)·(1 − σ(z)) = p·(1 − p).

Tercero, la parte lineal: ∂z/∂wⱼ = xⱼ.

Al multiplicar los tres, el factor p·(1 − p) del denominador de la primera derivada se cancela exactamente con el mismo factor que aporta σ′(z):

∂L/∂wⱼ = [ (p − y) / (p·(1 − p)) ] · [ p·(1 − p) ] · xⱼ = (p − y)·xⱼ.

Esa cancelación es la razón de fondo por la que la entropía cruzada es la pérdida correcta para la sigmoide, y no una preferencia estética. Si se usara error cuadrático, L = ½(p − y)², la derivada sería ∂L/∂z = (p − y)·σ′(z) = (p − y)·p·(1 − p), y el factor p·(1 − p) sobreviviría. Ese factor vale como máximo 0,25 en z = 0 y tiende a cero cuando el modelo está muy seguro: exactamente en los casos donde el modelo se equivoca con confianza —p ≈ 0 con y = 1— el gradiente se anularía y el aprendizaje se detendría justo donde más falta hace. Es el fenómeno de saturación, y la entropía cruzada lo evita por construcción.

Por qué aquí hay una única solución, y después no

Esta pérdida tiene una propiedad que ningún laboratorio posterior volverá a tener: es convexa en los parámetros. Su matriz hessiana es

H = (1/N)·Xᵀ·S·X, con S = diag(pᵢ·(1 − pᵢ)),

y como cada pᵢ·(1 − pᵢ) > 0, la matriz S es definida positiva y H resulta semidefinida positiva para cualquier X. Una función convexa no tiene mínimos locales distintos del global: cualquier punto donde el gradiente se anule es la solución óptima. Por eso aquí el descenso de gradiente converge al mismo sitio venga de donde venga la inicialización, y la única semilla que importa es la de la partición de datos.

Conviene guardar esa observación, porque explica un contraste que se vuelve central a partir de la clase 03: en cuanto se añade una capa oculta con no linealidad, la superficie de pérdida deja de ser convexa, aparecen múltiples mínimos y puntos de silla, y la inicialización empieza a cambiar el resultado. Ese es el momento exacto en que training_seed se convierte en una variable experimental que hay que controlar y reportar, y no en un detalle.

Un caso límite conviene conocerlo: si las clases son linealmente separables, la verosimilitud no tiene máximo finito —los pesos crecen sin cota empujando las probabilidades hacia 0 y 1— y el entrenamiento diverge lentamente. La regularización L2 lo resuelve añadiendo (λ/2)·‖w‖², que vuelve la pérdida estrictamente convexa y garantiza un óptimo finito.

Estabilidad numérica y comprobación del gradiente

Implementar estas fórmulas en punto flotante exige dos cuidados que el laboratorio hace visibles.

El primero es que ln(0) es −∞. Con z ≈ −40, σ(z) se redondea a 0,0 en float64 y la pérdida se vuelve infinita o NaN. La solución robusta no es recortar p a [ε, 1−ε], que sesga el resultado, sino no calcular σ por separado: se usa la forma estable

L = mean( max(z, 0) − z·y + ln(1 + e^(−|z|)) ),

algebraicamente idéntica a la entropía cruzada pero cuyo exponente nunca es positivo, de modo que e^(−|z|) ∈ (0, 1] y no desborda. Es exactamente lo que hace BCEWithLogitsLoss en la ruta siguiente, y aquí se escribe a mano para saber qué hay dentro.

El segundo es cómo saber que la derivada está bien programada. La comprobación estándar es contrastarla contra una diferencia finita central:

∂L/∂θ ≈ ( L(θ + ε) − L(θ − ε) ) / (2ε),

cuyo error es O(ε²) frente al O(ε) de la diferencia hacia adelante. Con ε ≈ 10⁻⁵ en float64, el error relativo entre el gradiente analítico y el numérico debería quedar por debajo de 10⁻⁷; por encima de 10⁻⁴ hay un fallo real en la derivación. Esta técnica es la que la clase 17 aplica capa por capa a una red completa.

Sobre la escala de las variables: como el gradiente es proporcional a xᵢⱼ, una característica medida en miles produce gradientes miles de veces mayores que una medida en unidades. Con una tasa de aprendizaje única, la dirección de descenso queda dominada por la variable de mayor escala y el resto avanza a paso de tortuga. En términos de la hessiana, la relación entre su mayor y su menor autovalor —el número de condición— se dispara, y la convergencia del descenso de gradiente se degrada en la misma proporción. Estandarizar las 30 características de este dataset no es cosmética: es lo que hace que el problema sea resoluble en un número razonable de épocas. Y se ajusta solo con train, porque usar la media y la desviación del conjunto completo filtraría información de test al preprocesamiento.

La pregunta que deberías poder responder al terminar: ¿Cómo cambia la convergencia al modificar la escala de las variables?

Qué se mide y con qué se decide

La clase reporta accuracy, balanced_accuracy, precision, recall, f1, roc_auc, pr_auc. De todas ellas, la que decide qué modelo se conserva es f1, y se mide siempre sobre validation: es la única forma de que test siga siendo una estimación honesta de lo que pasará con datos nuevos.

📓 Los tres cuadernos

La clase se puede recorrer en Jupyter y trae tres cuadernos con papeles distintos. Los tres siguen el mismo camino —descargar el dataset real, auditar la partición, entrenar, sellar el experimento y evaluar test una vez—; lo que cambia es qué te toca escribir a ti:

Qué se practica en los ejercicios

Cinco de ellos cubren el contrato experimental común: auditar la partición, decidir con validation, compararse con la línea base, sellar antes de abrir test y dejar el plan por escrito. Se resuelven con Python estándar —sin descargar el dataset ni entrenar—, así que se corrigen en segundos y sin GPU, y cada uno está parametrizado con los valores de este laboratorio: su métrica de selección, su línea base y su experimento propio.

Cómo abrirlos

Los cuadernos necesitan el extra notebooks, que instala Jupyter junto con el paquete:

pip install -e ".[dev,notebooks]"
jupyter lab labs/00_numpy_neuron/notebook.ipynb

También se abren desde VS Code —con la extensión de Jupyter— haciendo doble clic en el archivo, o desde la interfaz clásica con jupyter notebook. El primer arranque descarga el dataset real desde su proveedor, así que la primera ejecución tarda más y requiere conexión.

Si prefieres ejecutar sin abrir un cuaderno, train.py hace exactamente lo mismo desde la terminal, y la sección de comandos de arriba explica cada opción.

🖥️ Los comandos, explicados

Todo el laboratorio se maneja con una sola herramienta de terminal, neural-labs, que se instala junto con el paquete (pip install -e ".[dev,notebooks]"). Cada subcomando hace una cosa del protocolo, y por eso se pueden ejecutar por separado: preparar datos, auditar la partición, entrenar, repetir con varias semillas.

La forma general es siempre la misma:

neural-labs <subcomando> --lab <identificador> [opciones]

El script del laboratorio

labs/00_numpy_neuron/train.py no es un programa distinto: fija el --lab y delega en la misma herramienta, de modo que estas dos líneas hacen exactamente lo mismo.

python labs/00_numpy_neuron/train.py --quick
neural-labs train --lab 00_numpy_neuron --quick

Lo mismo desde Python

Si prefieres trabajar en un cuaderno o llamar al laboratorio desde tu propio código, la misma ejecución se lanza así. La función devuelve un objeto con el directorio de la ejecución, las métricas y el historial ya cargados:

from neural_labs.experiments import run_lab

resultado = run_lab(
    "00_numpy_neuron",
    quick=True,          # False para la ejecución completa
    config_name="baseline",
    split_seed=42,       # fija la partición
    training_seed=43,    # varía la inicialización
)

print(resultado.run_dir)   # dónde quedaron los archivos
print(resultado.metrics)   # el diccionario de métricas finales

Y para preparar el dataset sin entrenar —útil para inspeccionarlo antes—:

from neural_labs.datasets import prepare_dataset

datos = prepare_dataset("00_numpy_neuron", quick=True, seed=42)
print(datos.summary)       # tamaño de cada partición y metadatos de la fuente

🪜 Laboratorio guiado

Cada paso dice qué ocurre por dentro, por qué se hace en ese orden y cómo comprobar que salió bien. El orden no es una convención de estilo: es el que ejecuta el código, y alterarlo invalida el resultado.

Paso 1 — Traer el dataset real y partirlo

Qué ocurre. Descarga breast_cancer_wisconsin desde su proveedor y construye las tres particiones —train, validation y test— con la semilla de partición que le pases.

Por qué. La partición se fija antes de entrenar y su semilla (--split-seed) es independiente de la del entrenamiento (--training-seed). Si ambas fueran la misma, no podrías distinguir si un cambio en el resultado viene de haber repartido los datos de otro modo o de haber inicializado los pesos de otro modo.

neural-labs dataset --lab 00_numpy_neuron --quick --split-seed 42

Cómo sabes que salió bien. El comando termina sin error y deja el dataset en caché. Si no hay red, falla: no se rellena con datos inventados (data/dataset.yaml declara fallback_to_generated_data: false).

Paso 2 — Comprobar que las particiones no se tocan

Qué ocurre. Recorre los identificadores de las tres particiones y verifica que ninguno aparece en dos de ellas.

Por qué. Una sola fila compartida entre train y test basta para que la métrica final quede inflada. Es el error más caro del oficio porque no produce ningún síntoma visible: el modelo simplemente «parece» mejor de lo que es.

neural-labs audit --lab 00_numpy_neuron --quick --split-seed 42

Cómo sabes que salió bien. La auditoría reporta cero solapamientos. Si reporta alguno, no sigas: el resto del laboratorio no significaría nada.

Paso 3 — Mirar los datos antes de modelarlos

Qué ocurre. Genera el informe de calidad (valores faltantes, balance de clases, rangos) y el de deriva entre particiones.

Por qué. Un desbalance fuerte o una diferencia de distribución entre train y test cambia qué métrica tiene sentido leer. Descubrirlo después de entrenar obliga a repetirlo todo.

neural-labs quality --lab 00_numpy_neuron --quick --split-seed 42

Cómo sabes que salió bien. Obtienes data_quality.json y drift_report.json; ábrelos antes de decidir la configuración.

Paso 4 — Estudiar la teoría del laboratorio

Qué ocurre. Leer theory.md: la idea central, el desarrollo matemático, los riesgos de interpretación y la bibliografía de la que sale todo eso.

Por qué. Sin esto, el entrenamiento es una caja que devuelve números. La teoría es lo que te permite decidir qué mirar y reconocer cuándo un resultado es sospechoso.

Cómo sabes que salió bien. Puedes responder, con tus palabras, qué calcula el modelo y por qué esa arquitectura encaja con la tarea binary_classification.

Paso 5 — Entrenar y seleccionar con validation

Qué ocurre. El entrenamiento recorre las épocas midiendo en validation después de cada una, y conserva el checkpoint con el mejor valor de f1.

Por qué. El conjunto de validación existe para tomar decisiones —arquitectura, hiperparámetros, cuándo parar—. Si esas decisiones se tomaran mirando test, test dejaría de ser una estimación de lo que pasará con datos nuevos y pasaría a ser parte del entrenamiento.

python labs/00_numpy_neuron/train.py --quick
# o, con control explícito de las dos semillas:
neural-labs train --lab 00_numpy_neuron --config baseline --split-seed 42 --training-seed 43

Cómo sabes que salió bien. En runs/00_numpy_neuron/<ejecución>/ aparecen history.csv y best_model.npz; la métrica de validación mejora respecto de la primera época.

Paso 6 — Compararte con la línea base

Qué ocurre. El repositorio entrena por su cuenta DummyClassifier y regresión logística de scikit-learn y guarda su resultado, primero sobre validation y —solo al final— sobre test.

Por qué. Una métrica sola no dice si el modelo aporta algo. Puede que un método mucho más simple llegue igual de lejos, y entonces la complejidad añadida no está justificada. Esta comparación es la que convierte un número en un argumento.

Cómo sabes que salió bien. Comparas metrics.json con baseline_metrics.json. Si tu modelo no supera la línea base, el resultado del laboratorio es exactamente ese, y hay que reportarlo.

Paso 7 — El sellado: experiment.lock.json

Qué ocurre. Antes de tocar test, el código escribe un archivo que fija el laboratorio, las dos semillas, la configuración, la métrica de selección, el checkpoint elegido y el hash del dataset.

Por qué. Es la frontera del experimento. A partir de ahí, cualquier ajuste que hagas mirando test queda a la vista: el sello dice qué habías decidido antes de ver el resultado final. Sin ese archivo, nadie —incluido tú dentro de un mes— puede distinguir una predicción de una racionalización.

Cómo sabes que salió bien. El archivo existe y su contenido coincide con lo que creías haber ejecutado.

Paso 8 — Evaluar test una sola vez y medir la incertidumbre

Qué ocurre. Con el checkpoint congelado se evalúa test, se calculan intervalos de confianza por bootstrap y se desglosan las métricas por subgrupo.

Por qué. Un número puntual esconde cuánto podría moverse. Los intervalos dicen si la diferencia con la línea base es real o cabe dentro del ruido; el desglose por subgrupo revela si el promedio está tapando un grupo donde el modelo funciona mucho peor.

Cómo sabes que salió bien. Tienes metrics.json, confidence_intervals.json y subgroup_metrics.json, y puedes decir la magnitud de la mejora y su incertidumbre.

Paso 9 — Repetir con varias semillas de entrenamiento

Qué ocurre. Se repite el entrenamiento manteniendo fija la partición y cambiando solo la semilla de entrenamiento.

Por qué. Dos ejecuciones idénticas salvo por la inicialización pueden diferir bastante. Si no mides esa dispersión, corres el riesgo de celebrar una mejora que era una semilla afortunada.

neural-labs benchmark --lab 00_numpy_neuron --quick --split-seed 42 --training-seeds 41 42 43

Cómo sabes que salió bien. Obtienes media y dispersión entre semillas, no un único número.

Paso 10 — Documentar y cerrar

Qué ocurre. Cada ejecución deja model_card.md y report.md; el plan de experimentos vive en experiments.md y la rúbrica en assessment.md.

Por qué. Un resultado sin su contexto —qué datos, qué decisiones, qué límites— no es reutilizable. La model card es lo que permite que otra persona sepa cuándo no debería usar tu modelo.

Cómo sabes que salió bien. Completaste la tabla multi-semilla de experiments.md y respondiste las preguntas de assessment.md.

🔍 Cómo leer lo que produce la ejecución

Cada ejecución escribe su propio directorio con nombre único, de modo que dos corridas nunca se pisan. Esto es lo que encontrarás dentro:

⚠️ Dónde suele perderse la gente

• --quick no es una versión pequeña del resultado, es una prueba de que todo corre. En esta ruta recorta a 1024 ejemplos de entrenamiento · 256 de validación · 256 de test · 2 épocas. Sirve para comprobar la instalación y la descarga; cualquier conclusión sobre el modelo exige la ejecución completa.
• Cambiar algo después de ver test invalida la comparación. Si al mirar el resultado final se te ocurre una mejora, la ruta correcta es volver a validation, decidir allí, y sellar de nuevo.
• Las dos semillas no son intercambiables. --split-seed cambia qué datos caen en cada partición; --training-seed cambia cómo se inicializa y baraja el entrenamiento. Para comparar modelos se fija la primera y se varía la segunda.
• Límite declarado de este dataset. Datos clínicos reales derivados de imágenes digitalizadas de aspirados de masas mamarias.

Riesgos al interpretar los resultados

Datos clínicos reales derivados de imágenes digitalizadas de aspirados de masas mamarias.

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.

✅ Antes de darlo por terminado

La clase está aprobada cuando se cumplen estos criterios:

• [ ] cero solapamiento entre train, validation y test
• [ ] selección basada únicamente en validation
• [ ] métricas finales acompañadas por incertidumbre
• [ ] conclusiones que distinguen evidencia de suposición

Y cuando tienes estos entregables:

• [ ] notebook ejecutado
• [ ] reporte experimental
• [ ] model card
• [ ] comparación con línea base
• [ ] respuesta a preguntas críticas

El plan experimental con la tabla que hay que completar está en experiments.md, y las preguntas con su rúbrica, en assessment.md. Ambos documentos se abren desde la barra de navegación de arriba.

Para ir más lejos

• Cambia una decisión experimental y justifícala con el resultado en validation, no con la intuición.
• Analiza los errores por clase o por segmento: casi siempre se concentran en un subconjunto reconocible.
• Compara costo, precisión y latencia; el mejor modelo no siempre es el que gana por décimas.
• Documenta sesgos, limitaciones y usos para los que no recomendarías este modelo.

📚 Fuentes

La teoría de arriba no es original de este repositorio: se apoya en la literatura de referencia del área y en los papers originales de cada arquitectura. Estas son las obras concretas, y lo que aporta cada una:

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

• Bishop — Pattern Recognition and Machine Learning (1.ª ed., Springer 2006), cap. 4 (modelos lineales para clasificación) — deriva la regresión logística y su verosimilitud.
• Goodfellow, Bengio & Courville — Deep Learning (MIT Press 2016), cap. 5–6 — fundamentos de aprendizaje y redes hacia adelante, entropía cruzada y gradientes.
• Géron — Hands-On Machine Learning (3.ª ed., O'Reilly 2022), cap. 4 y 10 — regresión logística práctica y la neurona como base de las redes.
• Nielsen — Neural Networks and Deep Learning (online, 2015), cap. 1–2 — intuición de la neurona sigmoide y la retropropagación derivada a mano.
• Rosenblatt (1958), The perceptron: a probabilistic model for information storage and organization in the brain, Psychological Review — origen histórico de la neurona artificial entrenable.
• Fuente del dataset: https://archive.ics.uci.edu/dataset/17/breast+cancer+wisconsin+diagnostic — Breast Cancer Wisconsin (Diagnostic) (UCI Machine Learning Repository, CC BY 4.0); procedencia, versión y SHA-256 en el registro de fuentes, entrada uci-breast-cancer-wisconsin-diagnostic — esta clase la usa para implementar propagación, entropía cruzada y descenso de gradiente sin autograd sobre mediciones clínicas reales de núcleos celulares.
• Consulte docs/experiment-protocol.md, docs/reproducibility.md y docs/ethics-and-licenses.md.

Los archivos de este laboratorio

Todo lo que necesitas está en esta carpeta. Cada enlace abre el archivo directamente:

Y fuera de la carpeta, tres referencias que esta guía usa: el catálogo configs/labs.yaml —de donde salen el objetivo, la línea base y las métricas—, el código src/neural_labs/experiments.py —que define el orden de los pasos y los archivos que escribe cada ejecución— y docs/experiment-protocol.md, con la regla general del protocolo.

Los datasets se descargan de su proveedor original y conservan su licencia; este repositorio no los redistribuye ni sustituye una descarga fallida por datos generados.

🔬 Experimentos

Plan de experimentos — Neurona con NumPy

Qué significa «experimentar» aquí

Entrenar un modelo y mirar el número que sale no es un experimento: es una observación. Un experimento empieza por una afirmación que podría resultar falsa, sigue fijando todo lo que no se está poniendo a prueba, y termina midiendo si la afirmación se sostiene cuando se repite.

La diferencia importa porque el entrenamiento de una red tiene azar por dentro: la inicialización de los pesos y el orden en que se barajan los lotes cambian el resultado aunque no cambies nada más. Si comparas una sola corrida contra otra sola corrida, no sabes si la diferencia viene de tu idea o de la semilla. Por eso todo lo que sigue está organizado para separar la señal (el efecto de lo que cambiaste) del ruido (la variabilidad propia del entrenamiento).

La hipótesis de este laboratorio

Implementar propagación, entropía cruzada y descenso de gradiente sin autograd.

Formulada como algo que se puede refutar: el modelo de este laboratorio supera a DummyClassifier y regresión logística de scikit-learn en f1, y la diferencia es mayor que la dispersión entre semillas.

Qué la haría falsa —y esto también es un resultado que hay que reportar—:

• El modelo no supera a DummyClassifier y regresión logística de scikit-learn.
• Lo supera, pero por menos de lo que varía el propio modelo al cambiar la semilla de entrenamiento.
• Lo supera solo con una semilla concreta y no con las demás.
• Lo supera a costa de un tiempo o un tamaño que el problema no justifica.

El experimento propio de esta clase

Además de la comparación con la línea base, aquí interesa una pregunta específica: Comparar el gradiente analítico con diferencias finitas. Es la comparación que da sentido al tema de este laboratorio; la de la línea base solo dice si el modelo sirve, mientras que esta dice qué parte del diseño es la que aporta.

Qué se varía y qué se mantiene fijo

Un experimento es interpretable cuando cambia una cosa a la vez. Esta tabla dice qué papel juega cada elemento y, sobre todo, por qué:

Las dos configuraciones que vas a comparar

El laboratorio trae dos configuraciones ya escritas. Estos son los parámetros en los que difieren —el resto es idéntico, que es justamente lo que hace legible la comparación—:

Elegir entre ellas es una decisión de validation. Si improved gana en validación, se queda; si no, la configuración base es la respuesta y hay que decirlo así.

Cómo ejecutar la serie

El comando benchmark hace exactamente esto: repite el entrenamiento manteniendo la partición fija y cambiando solo la semilla de entrenamiento.

neural-labs benchmark --lab 00_numpy_neuron \
  --config baseline --split-seed 42 --training-seeds 41 42 43

neural-labs benchmark --lab 00_numpy_neuron \
  --config improved --split-seed 42 --training-seeds 41 42 43

Por dentro, benchmark no hace magia: llama a run_lab una vez por semilla con la misma partición y resume los resultados. Desde Python es literalmente eso:

from neural_labs.experiments import run_lab
from neural_labs.benchmarking import summarize_benchmark

registros = []
for semilla in (41, 42, 43):
    resultado = run_lab(
        "00_numpy_neuron",
        config_name="baseline",
        split_seed=42,          # la partición NO cambia
        training_seed=semilla,  # solo cambia la inicialización
    )
    registros.append({"training_seed": semilla, "metrics": resultado.metrics})

print(summarize_benchmark(registros))   # media y dispersión entre semillas

Empieza con --quick para comprobar que la serie corre entera; los números que se reportan salen de la ejecución completa.

La tabla que debes completar

De dónde sale cada columna, para que no haya que adivinarlo:

• Métrica en validation: el mejor valor de f1 durante el entrenamiento; está en history.csv y resumido en metrics.json.
• Métrica en test: el valor final, en metrics.json, ya con el modelo congelado.
• Tiempo: wall_time_seconds de metrics.json.
• Parámetros: parameters de metrics.json; es la medida honesta del tamaño del modelo.
• Observación: lo que viste y los números no dicen —una curva que se dispara, una clase que concentra los errores, una corrida que no convergió—.

Cómo decidir con esos números

1. Compara medias, pero decide con la dispersión. Calcula media y desviación entre las tres semillas de cada variante. Una mejora de 0,3 puntos entre variantes cuya dispersión interna es de 1,2 puntos no es una mejora: es ruido con buena suerte.
2. Si los rangos se solapan, dilo. «No se observó una diferencia distinguible del ruido con tres semillas» es una conclusión legítima y mucho más útil que un número inventado de confianza.
3. Decide con validation. La columna de test sirve para reportar el resultado final una vez, no para elegir la variante ganadora.
4. El costo forma parte del resultado. Si improved gana por poco y cuesta el triple de tiempo, la conclusión honesta menciona ambas cosas.
5. Vuelve a la línea base. La comparación contra DummyClassifier y regresión logística de scikit-learn es la que dice si todo el aparato de la red neuronal estaba justificado para este problema.

Qué debe decir tu conclusión

Una conclusión completa contiene cinco cosas, y se puede escribir en un párrafo:

• Magnitud: cuánto mejoró, en qué métrica y sobre qué conjunto.
• Incertidumbre: cuánto varió entre semillas, y si la mejora sobrevive a esa variación.
• Costo: tiempo, memoria o tamaño adicional que hubo que pagar.
• Errores: dónde falla el modelo, no solo cuánto acierta.
• Condiciones: en qué circunstancias no esperarías que este resultado se repitiera.

Errores de diseño que invalidan el experimento

• Cambiar dos cosas a la vez. Si tocas la arquitectura y la tasa de aprendizaje en la misma corrida, el resultado no atribuye el efecto a ninguna de las dos.
• Comparar con particiones distintas. Es el error más frecuente y el más difícil de detectar después: parece una mejora del modelo y es un reparto distinto de los datos.
• Quedarse con la mejor semilla. Elegir la corrida más favorable y reportar solo esa es seleccionar el ruido. Se reportan todas.
• Ajustar mirando test. En cuanto una decisión se toma con el resultado de test, ese conjunto deja de estimar el rendimiento con datos nuevos.
• No registrar el entorno. Sin versiones ni hardware, una diferencia de tiempo o de resultado se vuelve inexplicable meses después.

📝 Evaluación

Evaluación — Neurona con NumPy

Cómo se evalúa esta clase

No se evalúa el número final. Un modelo con una métrica alta obtenida mirando test, o sin compararse con nada, vale menos que uno modesto cuyo resultado se puede auditar. Lo que se califica es el proceso: si las particiones están limpias, si la decisión se tomó donde debía, si la conclusión distingue lo que se midió de lo que se supone.

Evidencias que debes entregar

Las preguntas, y qué se busca en tu respuesta

No se corrige la longitud de la respuesta, sino si demuestra comprensión. Debajo de cada pregunta está lo que una buena respuesta debería contener.

1. ¿Cómo aprende una neurona si no existe autograd?

Qué se busca: Comienza con la predicción que hiciste al abrir la clase y contrástala con una gráfica, una medida o una observación concreta de tu ejecución.

2. Explica con tus palabras: p(y=1|x)=σ(xw+b); gradiente de la entropía cruzada.

Qué se busca: Una buena respuesta conecta cuatro cosas —cómo se representa la entrada, qué calcula el modelo, qué mide la función de pérdida y cómo se actualizan los pesos— en vez de repetir la definición del libro. Si puedes explicarlo sin la fórmula delante, lo entendiste.

3. ¿Qué información del dataset solo puede usarse durante el entrenamiento?

Qué se busca: Se espera que nombres casos concretos: las estadísticas de normalización, el vocabulario, la selección de variables, los umbrales. Todo eso se ajusta solo con train; calcularlo sobre el conjunto completo es una fuga silenciosa que infla el resultado sin dar ningún aviso.

4. ¿Por qué DummyClassifier y regresión logística de scikit-learn es una comparación razonable para este problema?

Qué se busca: Una buena respuesta explica qué captura la línea base y qué no, y por qué superarla —o no superarla— es informativo aquí. Si la línea base ya resuelve el problema, la conclusión correcta es que la red no estaba justificada.

5. ¿Cómo cambia la convergencia al modificar la escala de las variables?

Qué se busca: Esta es la pregunta propia del tema. Responde con evidencia de tu ejecución —predicciones, matriz de confusión, curvas, artefactos del directorio de la corrida—, no con una impresión general.

6. ¿Qué aprendiste al realizar esta práctica: Derivar el gradiente, comprobarlo con diferencias finitas y observar cómo la escala de las variables cambia el descenso.?

Qué se busca: No basta con relatar los pasos. Explica qué cambió, por qué cambió y qué resultado te haría rechazar tu interpretación inicial.

7. Refuta con evidencia esta idea frecuente: «El gradiente no indica dónde está el mínimo; indica la pendiente local y cuánto cambia la pérdida en ese punto.»

Qué se busca: Se busca una refutación situada en esta materia, apoyada en el mecanismo estudiado y en los resultados obtenidos, no una negación genérica.

8. ¿Qué te dice f1 que no te dirían las otras métricas?

Qué se busca: Cada métrica pondera distinto los errores. Se espera que expliques por qué esa es la que decide aquí y en qué situación sería una mala elección.

9. ¿Qué cambiarías antes de usar este modelo fuera del laboratorio?

Qué se busca: Aquí se evalúa el criterio, no la técnica: licencias y condiciones de uso de breast_cancer_wisconsin, representatividad de la población, calibración de las probabilidades, vigilancia de la deriva, desempeño por subgrupo y supervisión humana. Un «funcionaría bien» sin condiciones se corrige como respuesta incompleta.

La rúbrica, explicada

La diferencia entre adecuado y excelente casi nunca está en la métrica: está en si el trabajo permite que otra persona llegue a la misma conclusión con los artefactos que dejaste. Un resultado peor, bien medido y bien explicado, se califica por encima de uno mejor que no se puede auditar.

La aprobación exige al menos 70 % y cero errores críticos de fuga de datos. La fuga es eliminatoria por sí sola porque invalida todas las demás cifras del trabajo, por buenas que parezcan.

Autoevaluación antes de entregar

• [ ] Puedo explicar la idea central de la clase a alguien que no la cursó, sin leer el código.
• [ ] Sé qué decisión tomé en cada paso y con qué evidencia la tomé.
• [ ] Miré test una sola vez, después de que existiera experiment.lock.json.
• [ ] Mi conclusión dice magnitud, incertidumbre, costo, errores y condiciones.

• [ ] Puedo señalar al menos una limitación real de mi resultado.

• [ ] cero solapamiento entre train, validation y test

• [ ] selección basada únicamente en validation
• [ ] métricas finales acompañadas por incertidumbre
• [ ] conclusiones que distinguen evidencia de suposición

🧑‍🏫 Guía docente

Guía docente — Clase 01: Neurona con NumPy

Módulo 1: Fundamentos · Esta guía acompaña a quien facilita la clase; no es un guion que deba leerse literalmente.

La conversación que abre la clase

Imagina una frontera que empieza equivocándose al azar y se mueve un poco después de cada error. En esta clase podrás ver y calcular cada uno de esos movimientos.

Plantee primero esta pregunta y permita que el grupo formule una predicción antes de mostrar código:

¿Cómo aprende una neurona si no existe autograd?

Qué debe quedar comprendido

• Implementar propagación, entropía cruzada y descenso de gradiente sin autograd.
• Preparar y auditar el dataset real breast_cancer_wisconsin sin fuga de datos.
• Entrenar y evaluar regresión logística implementada sin autograd.
• Comparar contra la línea base: DummyClassifier y regresión logística de scikit-learn.
• Interpretar intervalos de confianza, errores y limitaciones.

Secuencia sugerida

Práctica propia de esta materia

Derivar el gradiente, comprobarlo con diferencias finitas y observar cómo la escala de las variables cambia el descenso.

La figura es un punto de entrada. Pida al estudiante que explique qué cambia entre los tres pasos y qué resultado observable invalidaría su explicación.

Dificultad conceptual que conviene provocar

Idea engañosa: El gradiente no indica dónde está el mínimo; indica la pendiente local y cuánto cambia la pérdida en ese punto.

No la corrija inmediatamente. Solicite un ejemplo o contraejemplo, ejecute una comparación y recién entonces reconstruya la explicación con el grupo.

Preguntas para acompañar sin resolver

• ¿Qué observación concreta respalda esa afirmación?
• ¿Qué variable está cambiando y cuáles permanecen controladas?
• ¿La gráfica muestra el mecanismo o solamente una correlación?
• ¿En qué caso dejaría de ser válida esta conclusión?

Cierre verificable

La clase termina cuando el estudiante puede responder la pregunta esencial, interpretar su visualización y señalar al menos una limitación. Una métrica aislada no reemplaza ninguna de esas tres evidencias.