5.1 Reproducibilidad

🖥️ Diapositivas — Sesión 27 (vie 4 dic)

La reproducibilidad es el boleto de entrada a la confianza en la ciencia computacional. Si su resultado no puede regenerarse a partir de sus datos y su código, es una anécdota, por bien que se vea la gráfica.

Definiciones: reproducibilidad frente a replicabilidad¶

Las definiciones varían entre disciplinas. Adoptamos las del informe de 2019 de las National Academies, Reproducibility and Replicability in Science engineering2019confidence:

• Reproducibilidad es obtener resultados consistentes usando los mismos datos de entrada, pasos computacionales, métodos, código y condiciones de análisis. A menudo se le llama reproducibilidad computacional. Involucra los datos originales y el código original.
• Replicabilidad es obtener resultados consistentes en estudios nuevos dirigidos a la misma pregunta científica, cada uno recolectando sus propios datos. Dos estudios se replican si sus resultados concuerdan dentro de la incertidumbre inherente al sistema.

Dos términos afines del mismo informe: la verificación pregunta si el código es correcto, y la validación pregunta si el modelo predice datos sobre los que no fue construido. Note la trampa: un error de programación se reproduce a la perfección. La reproducibilidad exacta no certifica corrección — certifica que el flujo de trabajo es determinista y completo. Lo que atrapa un error reproducible es la validación sobre datos reservados (la disciplina del capítulo 3 de los conjuntos de prueba ocultos).

Para un análisis reproducible, el informe pide a quienes investigan tres cosas:

• Datos: los datos de entrada, o los scripts que los descargan o los generan, más los productos intermedios cuando regenerarlos es costoso.
• Métodos: los pasos computacionales y los parámetros, en forma ejecutable siempre que sea posible.
• Entorno computacional: sistema operativo, hardware y dependencias de bibliotecas.

En aprendizaje automático, la reproducibilidad suele aceptarse dentro de una tolerancia declarada y no bit a bit, porque el entrenamiento involucra aleatoriedad e indeterminismo de punto flotante. Decidir qué tolerancia es aceptable es parte de su trabajo como científico o científica; volvemos a ello más abajo.

Por qué subió lo que está en juego cuando los agentes empezaron a escribir código¶

Hasta hace poco, la principal amenaza a la reproducibilidad era el descuido humano: una celda de cuaderno ejecutada fuera de orden y sin registro, un CSV editado a mano, un «final_v3_REAL.ipynb». Esas amenazas siguen existiendo. La nueva es la escala. Un agente puede generar un análisis completo — descarga de datos, ingeniería de características, modelo, figuras, prosa — en minutos. La salida es fluida e internamente consistente. También puede estar equivocada de formas que la fluidez oculta: una característica con fuga de datos, un conjunto filtrado que descartó en silencio los casos difíciles, una métrica calculada sobre la partición de entrenamiento.

Usted no puede revisar código generado por agentes a la velocidad a la que los agentes lo generan. Lo que sí puede hacer es volver ejecutables las verificaciones. Un entorno fijado significa que el código del agente correrá mañana contra las mismas bibliotecas. Las transformaciones programadas significan que cada paso desde el dato crudo hasta la figura es inspeccionable y reejecutable. CI significa que cada cambio se vuelve a ejecutar antes de aterrizar. Este es el tema de todo el capítulo: cuando usted delega el tecleo, no debe delegar la verificación. La política de IA del curso (capítulo 1.8) dice que usted debe poder defender cada línea que entrega; las prácticas de abajo son las que hacen posible esa defensa para código que no escribió a mano.

La pila de la reproducibilidad¶

Cinco capas, desde el suelo hacia arriba.

1. Fijación del entorno¶

«Funciona en mi máquina» suele significar «funciona con las versiones de bibliotecas de mi máquina». Los solucionadores, los valores por defecto e incluso los flujos de números aleatorios cambian entre versiones. La solución es un bloqueo: una lista legible por máquina de versiones exactas de paquetes que una herramienta puede recrear en cualquier lugar.

Tres herramientas comunes:

• pixi (la que usa este libro): un pixi.toml declara las dependencias; pixi.lock fija cada paquete, para cada plataforma. pixi install recrea el entorno exactamente.
• conda-lock: la misma idea para entornos conda — convierte un environment.yml en un archivo de bloqueo (lockfile) por plataforma.
• uv: herramienta rápida compatible con pip; uv lock fija un proyecto de Python puro.

Este libro es su propio ejemplo trabajado. La raíz del repositorio tiene un pixi.toml que declara la cadena de herramientas:

[dependencies]
python = "3.12.*"
numpy = ">=2.0"
pandas = ">=2.2"
scikit-learn = ">=1.6"
pytorch = ">=2.4"
obspy = ">=1.4"
# ...

[pypi-dependencies]
mlgeo-synth = { path = ".", editable = true }

Las restricciones declaradas son laxas (>=), pero el pixi.lock confirmado las resuelve a versiones exactas. Cada estudiante, cada ejecutor de CI y cada agente que trabaje en este repositorio ejecuta la misma pila. Cuando actualizamos una biblioteca, el archivo de bloqueo cambia en un commit — el entorno tiene historia, igual que el código.

Para su proyecto: confirme el manifiesto y el archivo de bloqueo. Un environment.yml sin versiones es una sugerencia, no un entorno.

2. Semillas y determinismo¶

La aleatoriedad entra al aprendizaje automático por muchos lados: barajado de datos, divisiones entrenamiento/prueba, inicialización de pesos, dropout (el apagado aleatorio de unidades durante el entrenamiento, lección 4.2), optimizadores estocásticos. Contrólela explícitamente:

import numpy as np
import torch

rng = np.random.default_rng(42)   # NumPy: pass rng around, do not use global state
torch.manual_seed(42)             # PyTorch: CPU and GPU generators

Prefiera np.random.default_rng(seed) sobre el antiguo np.random.seed(): un objeto Generator es local, de modo que dos partes de su código no pueden compartir y perturbar en silencio un único flujo global. En scikit-learn, pase random_state= a cada estimador y a cada divisor que lo acepte.

Conozca los límites. En GPU, algunas operaciones usan algoritmos no deterministas por velocidad (atómicas en las reducciones, autoajuste de cuDNN). torch.use_deterministic_algorithms(True) fuerza núcleos deterministas donde existen, a costa de rendimiento, y lanza error donde no existen. Las reducciones en paralelo también pueden diferir entre equipos porque la suma de punto flotante no es asociativa. La postura práctica: haga determinista todo lo que sea barato volver determinista, y luego mida la varianza restante entre corridas y reporte los resultados con esa dispersión. Una mejora declarada que sea menor que su varianza entre semillas no es un resultado. El ejercicio de 5.2 cuantifica exactamente esto.

3. Los datos crudos son inmutables; toda transformación está programada¶

El directorio de datos crudos es de solo lectura. Nadie — ni usted, ni un agente — edita un archivo crudo. Todo cambio de forma (limpieza, remuestreo, extracción de características, etiquetado) es un script que lee de data/raw/ y escribe en data/processed/. Si alguna vez los datos procesados quedan en duda, usted los borra y vuelve a correr los scripts. Esta es la disciplina de datos listos para IA del capítulo 2, replanteada como regla del sistema de archivos, y es la práctica de reproducibilidad más barata que existe. Corolario: si un paso ocurrió solo en una celda de cuaderno que usted ya sobrescribió, no ocurrió.

4. Contenedores, en un párrafo¶

Los archivos de bloqueo fijan sus paquetes, pero no el sistema operativo, las bibliotecas del sistema ni los compiladores que están debajo. Los contenedores (Docker, Apptainer/Singularity en HPC) congelan esa capa entera en una imagen que puede correr en cualquier parte. Para la mayoría de los proyectos del curso, un archivo de bloqueo alcanza; recurra a un contenedor cuando deba correr en un clúster que no controla, distribuir un servicio o archivar un resultado a largo plazo (revistas y archivos aceptan cada vez más una imagen junto al código). Mismo principio, un nivel más abajo en la pila.

5. Verificaciones ejecutables: la CI de este libro¶

La afirmación más fuerte de reproducibilidad es la que una máquina verifica en cada cambio. La propia construcción de este libro es el caso de estudio: un flujo de trabajo de GitHub Actions (.github/workflows/build.yaml) corre en cada pull request, instala el entorno bloqueado con pixi y ejecuta cada cuaderno del libro durante la construcción con MyST (myst build --execute --html). Si una celda de código falla — porque cambió una biblioteca, porque se movió un conjunto de datos o porque una edición rompió una celda anterior — la construcción falla y el pull request no puede fusionarse. En el mismo trabajo corre un verificador de enlaces.

La consecuencia es una garantía que la prosa por sí sola nunca podría dar: cada resultado que usted ve en este libro fue calculado, desde cero, en un entorno limpio, en el commit que está leyendo. La sección 5.3 muestra cómo copiar este patrón a su propio repositorio de proyecto, y la tabla de clasificación de la clase (capítulo 3.5) convierte la misma idea en calificación: su entrega es lo que CI logre ejecutar, nada más.

Lista de verificación¶

Antes de afirmar que un resultado es reproducible, revise:

• git clone + un comando documentado recrean el entorno (archivo de bloqueo confirmado)
• toda la aleatoriedad tiene semilla, y la varianza entre corridas con distintas semillas está medida
• los datos crudos son de solo lectura; cada transformación del dato crudo a la figura es un script bajo control de versiones
• un clon fresco en otra máquina (o en CI) reejecuta el flujo de trabajo de principio a fin
• los números reportados coinciden con la reejecución dentro de la tolerancia declarada

Lecturas adicionales¶

• National Academies of Sciences, Engineering, and Medicine (2019). Reproducibility and Replicability in Science. The National Academies Press. undefined & undefined (2019)
• The Turing Way, Guide for Reproducible Research: https://book.the-turing-way.org/reproducible-research/reproducible-research
• Pineau et al. (2021), «Improving Reproducibility in Machine Learning Research», JMLR 22(164) — el artículo de la lista de verificación de reproducibilidad de NeurIPS.