34 Paquetes de investigación abiertos y reutilizables
Este capítulo forma parte de un libro en desarrollo activo y todavía no ha pasado por la revisión del autor. El contenido puede cambiar a medida que avanza la revisión.
La decisión de investigación. Decides qué entra en la cápsula de reproducibilidad que viaja con tu nota de investigación, y defiendes la afirmación de que una persona desconocida puede volver a ejecutar tu trabajo y obtener tus números. Tú respondes por lo que el paquete incluye y por si “esto se reproduce” es honesto, y nunca dejas que una ejecución limpia haga pasar por correcta a una que no lo es.
34.1 Por qué importa esta decisión
La decisión en juego: qué va dentro de la cápsula que viaja con tu trabajo, y si la oración “esto se reproduce” es honesta cuando la escribes.
“No quiero oír que corre en tu laptop. Dame la carpeta, déjame borrar todo y déjame apretar ejecutar. Si tu número titular no vuelve en mi máquina, todavía no tienes un resultado. Tienes el recuerdo de uno.” — un editor de replicación, abriendo la carpeta adjunta a tu entrega
Una nota de investigación argumenta tu afirmación en prosa. La cápsula demuestra que la afirmación sobrevive sin ti en la sala. Si el único lugar donde tu análisis corre es la laptop donde lo construiste, en el orden de clics que resulta que recuerdas, entonces nadie puede revisarte, y un resultado que nadie puede revisar es un rumor con gráfico. Este capítulo es cómo empaquetas el trabajo para que revisarlo sea fácil, y cómo conservas la honestidad sobre lo que “reproducible” significa de verdad.
34.2 El concepto
Una cápsula de reproducibilidad es todo lo que una persona desconocida necesita para reconstruir tus números y nada que tendría que adivinar. Ejemplo: una carpeta con tu cuaderno, tus datos y un registro corto de cada decisión hecha a mano. Tiene cinco partes, cada una definida una sola vez.
- Un cuaderno ejecutable que pasa reiniciar y ejecutar todo, es decir, borras el kernel y corres cada celda de arriba abajo sin memoria de clics anteriores. Ejemplo: Entorno de ejecución, Reiniciar y ejecutar todo, y tu número titular reaparece.
- Una nota de procedencia de datos: de dónde vino cada conjunto de datos, su versión y cómo puede usarse. Ejemplo: la URL de descarga, la fecha y la licencia.
- Una semilla fija, un número de arranque que hace que cada paso aleatorio devuelva los mismos valores en cada ejecución. Ejemplo:
SEED = 464alimentando cada remuestreo. - Una bitácora de decisiones: las decisiones hechas a mano que dieron forma al resultado, cada una con su razón. Ejemplo: cada fila que descartaste, y por qué.
- Un registro de uso de IA: cada herramienta, su tarea y cómo verificaste su salida.
Las cápsulas se rompen de maneras aburridamente predecibles, lo cual es buena noticia, porque una falla predecible es una falla detectable. Con nombre, son los cinco pecados del paquete: una ruta escrita a mano que solo existe en tu máquina, una semilla faltante que mueve cada ejecución, una edición manual que ninguna ejecución limpia reproduce, una exclusión sin documentar sin razón registrada, y datos vencidos que quien lee no puede volver a obtener. El auditor del laboratorio busca los cinco. Pero quédate con la única línea que carga todo el capítulo: una cápsula con cero alertas es ejecutable, nunca está probada como correcta. El escaneo te lleva a la línea de salida. Quien te vuelve a ejecutar en frío es la carrera.
34.3 Un ejemplo resuelto
Recopilaste la participación electoral por casilla en doce condados de un estado en una elección intermedia, y tu titular es la proporción de casillas donde la participación cayó por debajo del 40%. Mira el mismo análisis entregado de dos maneras.
La cápsula pecadora carga ~/Desktop/turnout_clean.csv, un archivo que solo tiene tu laptop. Calcula por bootstrap un intervalo de confianza para esa proporción sin semilla, así que el intervalo se mueve en cada ejecución. Corrige a mano un nombre de casilla duplicado en una celda que ninguna ejecución limpia repite. Descarta en silencio cada casilla cuyo conteo de personas registradas faltaba, sin nota sobre por qué. Y sus datos se descargaron “en algún momento de la primavera pasada”, antes de que el estado certificara el conteo, sin versión registrada. Cinco pecados, y cada uno rompe la nueva ejecución.
La cápsula limpia carga el archivo certificado desde su URL pública, con la fuente, la fecha de descarga y los términos de uso en la nota de procedencia. Fija SEED = 464 antes del bootstrap. Registra en la bitácora de decisiones la única corrección de nombre con su razón. Conserva las casillas con conteos de registro faltantes, o las descarta con una regla registrada y declarada de antemano. Ahora una persona desconocida borra el kernel, corre de arriba abajo, y tu proporción de casillas por debajo del 40% vuelve. Mismo número, sin adivinanzas.
Aquí está la comprobación de honestidad que el auditor no puede hacer por ti. La cápsula limpia todavía puede estar equivocada: tu semilla podría estar fijada sobre el subconjunto incorrecto, o descartar las casillas con registro faltante podría ser una mala regla limpiamente registrada. Ejecutable no es correcto. Ese hueco es exactamente por qué tu cápsula la ejercita una persona, no solo un script.
34.4 El laboratorio en Colab
Este capítulo tiene su propio cuaderno de acompañamiento: ábrelo en Colab con la insignia de arriba. El cuaderno reúne los prompts y el código del capítulo y termina con el espacio de trabajo Ahora te toca a ti, para que completes el paso del capítulo en tu proyecto sin salir de Colab. El laboratorio de aula completo detrás de este capítulo es el cuaderno del curso nb15 — From poster to research note (del póster a la nota de investigación) (abrir en Colab), parte del curso de acompañamiento presentado en el apéndice Para docentes. Ahí construyes audit_capsule, lo ves marcar los cinco pecados en un paquete roto a propósito y ninguno en uno limpio, y después pegas las líneas clave de tu propia cápsula y arreglas lo que detecte.
34.5 Prompts de IA recomendados
Comprométete primero con tu propia respuesta y después delega. Empaquetar es un bucle de IA que correrás más de una vez: el ciclo prompt → respuesta → interrogación → refinamiento → nueva ejecución. Preguntas, arreglas lo que vuelve, vuelves a ejecutar la cápsula en frío, y esa nueva ejecución saca a la superficie el siguiente hueco. Algunas herramientas ya corren ese bucle solas, editando archivos y reejecutando hasta que nada dé error. Un bucle que termina sin errores demostró que el código se ejecuta. No demostró que los números estén bien, y solo tú puedes notar la diferencia. Cada prompt es una tarea verificable, no un veredicto.
Localiza la herramienta estándar.
Act as a reproducibility assistant. Name the standard file and format for recording
the exact package versions a notebook needs in order to rerun, and cite the official
documentation. Only name tools you are confident exist.Después de ejecutarlo, verifica: abre la documentación oficial y confirma que el archivo y su sintaxis existen. Contrarresta la fabricación confiada (un nombre de herramienta inventado llega con la misma seguridad que uno real).
Enumera para que puedas verificar (la persona que replica en frío).
Here are the key lines of my capsule: [paste]. Playing a replicator who has only
these lines and none of my memory, list every input, file, or by-hand step you would
need to rerun my headline number and might not find here.Después de ejecutarlo, verifica: contrasta cada hueco nombrado con lo que tu propia ejecución de audit_capsule de verdad marcó, y descarta cualquier hueco que no corresponda a ninguna línea realmente faltante. Contrarresta la ilusión de exhaustividad (una cápsula ordenada que se ve entera mientras falta un insumo).
Hazle red team (revisión adversaria) a la afirmación.
My claim is: "a stranger can rerun this capsule and get my number." Act as a hostile
replication reviewer and name every way it could fail on a machine that is not mine.
Do not fix it for me.Después de ejecutarlo, verifica: si solo te tranquiliza, empuja de vuelta y exige la peor falla individual. Contrarresta el acuerdo complaciente (elogio que revisa tu ego, no tu paquete).
Tú decides qué entra en la cápsula y si la oración “esto se reproduce” es honesta. La herramienta puede enumerar huecos y fijar versiones, pero no puede registrar la procedencia verdadera de tus datos, juzgar si la razón registrada de una exclusión es una buena razón, ni certificar que tu análisis es correcto y no solo ejecutable. El nombre en la carpeta, y la afirmación de que una persona desconocida puede confiar en ella, son tuyos.
34.6 Un caso de falla de la IA
Pegas tu cuaderno en tu IA y preguntas: “¿esto correrá en frío y producirá mi proporción de baja participación?”. Recorre cada celda y responde, con total confianza: “Sí, esto corre de arriba abajo sin problemas y devuelve tu número titular”. Suena como una palomita verde. No lo es. La IA nunca ejecutó nada. Leyó el código y lo narró. La celda 3 carga ~/Desktop/turnout_clean.csv, una ruta que solo tiene tu laptop, y el recorrido fluido describió la lectura de ese archivo como si estuviera ahí.
Lo detectas de la única manera que cuenta: de verdad corres reiniciar y ejecutar todo en un kernel nuevo, idealmente en Colab, en una máquina que no es la tuya. El FileNotFoundError aparece en la celda 3 en segundos. Una ejecución narrada no es una ejecución. Verificas el cuaderno ejecutándolo, no leyendo un párrafo sobre ejecutarlo.
34.7 Ahora te toca a ti
Tu proyecto ya tiene una nota de investigación y una carpeta que corre; este paso convierte las dos en una sola cápsula que alguien podría tomar dentro de un año y reutilizar.
- Arma las cinco partes para tu propio proyecto: el cuaderno ejecutable, la nota de procedencia de datos, la semilla fija, la bitácora de decisiones y tu registro de uso de IA. Todo lo que quien lee tendría que adivinar pertenece a una de las cinco.
- Corre la auditoría del capítulo sobre tus propias líneas clave y arregla lo que marque, empezando por el pecado que más tentación te daba dejar en paz. Las rutas escritas a mano y las semillas faltantes son los dos que más seguido rompen a quien viene de fuera.
- Escribe el README que una persona desconocida lee primero: qué pregunta el proyecto, cuál es el número titular, qué archivo lo produce y en qué orden ejecutar las cosas.
- Vuelve a ejecutarlo en frío en un segundo entorno, una sesión limpia de Colab o una máquina que no sea la tuya, y comprueba que el titular vuelve dentro del redondeo. Un número que viaja es reproducible. Un número que no viaja significa que algo que cargabas a mano estaba haciendo un trabajo silencioso que nunca empaquetaste.
- Escribe una oración honesta sobre el límite de todo esto: tu cápsula es ejecutable, que no es lo mismo que correcta, y nombra la decisión dentro de ella que más querrías que alguien cuestionara.
- Registra la ronda de empaquetado en tu AI Research Ledger (registro de investigación con IA) y verifica al menos una salida con un método nombrado de la Guía de Verificación. Un revisor de IA puede hacer la comprobación contigo; la decisión de aceptar o rechazar sigue siendo tuya.