Control de versiones para Data Science

Registrar los cambios que tú o tus colaboradores hacéis en los datos y el software es fundamental en cualquier proyecto, ya sea de investigación, data science o ingeniería de software. Poder consultar o recuperar una versión concreta de todo el proyecto facilita la reproducibilidad antes de publicar, al responder a los comentarios de los revisores y al aportar información de apoyo para revisores, editores y lectores.

Las mejores herramientas para seguir los cambios son los sistemas de control de versiones utilizados en desarrollo de software, como Git, Mercurial y Subversion. Registran qué se cambió en un archivo, cuándo y por quién, y sincronizan los cambios con un servidor central para que varias personas puedan gestionar modificaciones sobre el mismo conjunto de archivos.

Aunque estas herramientas facilitan el seguimiento de cambios, su curva de aprendizaje puede ser pronunciada. Para superarla, hay dos enfoques recomendados: un método manual y sistemático para gestionar cambios y, por otro lado, el control de versiones en toda su potencia. Puedes empezar con el primero mientras avanzas hacia el segundo, o lanzarte directamente al control de versiones.

Buenas prácticas para el control de versiones

Elijas el enfoque que elijas, conviene tener presentes algunas buenas prácticas generales:

1. Haz copia de seguridad de (casi) todo lo que crea una persona en cuanto se cree. Incluye scripts y programas de todo tipo, paquetes de software de los que dependa tu proyecto y documentación. Más abajo comentamos algunas excepciones a esta regla.

2. Mantén los cambios pequeños. Cada cambio no debería ser tan grande que haga irrelevante el seguimiento. Por ejemplo, un único cambio como Revise script file que añade o modifica varios cientos de líneas probablemente es demasiado grande, porque no permite analizar por separado los cambios en distintos componentes de un análisis. Del mismo modo, tampoco conviene fraccionar en cambios diminutos. Como regla práctica, un buen tamaño para un cambio es un conjunto de ediciones que, llegado el caso, te gustaría poder deshacer de una sola vez en el futuro.

3. Comparte cambios con frecuencia. Quienes trabajen en el proyecto deberían compartir e incorporar cambios de los demás de forma regular. No permitas que las versiones del repositorio se desalineen entre personas, porque el esfuerzo de fusionar diferencias crece más rápido que el tamaño de la diferencia. Esto es especialmente importante en el procedimiento manual descrito abajo, que no ayuda a fusionar cambios simultáneos y potencialmente conflictivos.

4. Crea, mantén y usa una lista de comprobación para guardar y compartir cambios del proyecto. Debería incluir escribir mensajes de registro que expliquen claramente los cambios, el tamaño y contenido de cada cambio, pautas de estilo para el código, actualización de listas de tareas y la prohibición de subir trabajo a medias o código roto.

5. Guarda cada proyecto en una carpeta que se replique fuera de tu equipo de trabajo usando un sistema como Dropbox o un repositorio remoto como GitHub. Sincroniza esa carpeta al menos a diario. Puede llevar unos minutos, pero lo recuperarás con creces el día que te roben el portátil o falle el disco duro.

Cómo abordar el versionado manual

El primer enfoque sugerido, en el que todo se hace a mano, tiene dos partes adicionales.

Primero, añade un archivo llamado CHANGELOG.txt en la subcarpeta docs del proyecto y anota con fecha los cambios del proyecto en orden cronológico inverso (es decir, lo más reciente primero). Este archivo es el equivalente a un cuaderno de laboratorio y debería contener entradas como las que ves abajo.

## 2016-04-08

* Switched to cubic interpolation as default.
* Moved question about family's TB history to end of questionnaire.

## 2016-04-06

* Added option for cubic interpolation.
* Removed question about staph exposure (can be inferred from blood test results).

Segundo, copia el proyecto completo cada vez que hagas un cambio importante (es decir, que afecte de forma sustancial a los resultados) y guarda esa copia en una subcarpeta cuyo nombre refleje la fecha en el área que se sincroniza. Este enfoque da lugar a proyectos organizados como se muestra a continuación:

.
|-- project_name
|   -- current
|       -- ...project content as described earlier...
|   -- 2016-03-01
|       -- ...content of 'current' on Mar 1, 2016
|   -- 2016-02-19
|       -- ...content of 'current' on Feb 19, 2016

Aquí, la carpeta project_name está vinculada a un almacenamiento externo (como Dropbox), current es donde se trabaja y el resto de carpetas dentro de project_name son versiones anteriores.

Ventajas y desventajas del versionado manual

Se suele decir que "los datos son baratos y el tiempo es caro". Copiarlo todo, como sugiere este enfoque, puede parecer derrochador, ya que muchos archivos no habrán cambiado, pero piensa que: un disco de un terabyte cuesta en torno a 50 $, lo que significa que 50 GB cuestan menos de 5 $. Siempre que mantengas los archivos de datos grandes fuera del área con copia de seguridad (lo veremos con más detalle más abajo), este método cuesta menos que el tiempo que tardarías en seleccionar a mano qué archivos copiar.

Este procedimiento manual cumple los requisitos descritos sin necesidad de herramientas nuevas. Ahora bien, si varias personas trabajan en el mismo proyecto, tendrán que coordinarse para que solo una persona modifique a la vez archivos concretos. En particular, puede ser útil crear un archivo de cambios por colaborador y fusionarlos cada vez que se haga una copia de respaldo.

Sistemas de control de versiones

Lo que más exige el proceso manual anterior es autodisciplina. Las herramientas en las que se basa nuestro segundo enfoque —el que usamos en nuestros propios proyectos— no solo aceleran el proceso manual: también automatizan algunos pasos y obligan a cumplir otros, reduciendo así la necesidad de autodisciplina y ofreciendo resultados más fiables.

Es difícil saber qué herramienta es la más usada hoy en investigación, pero de la que más se habla, sin duda, es Git. En gran parte se debe a GitHub, un popular servicio de alojamiento que combina la infraestructura técnica para colaborar con Git y una moderna interfaz web. GitHub es gratuito para proyectos públicos y de código abierto y para usuarios del ámbito académico y sin ánimo de lucro. GitLab es una alternativa muy bien valorada que algunos prefieren porque la propia plataforma GitLab es libre y de código abierto. Bitbucket ofrece alojamiento gratuito para repositorios Git y Mercurial, pero no cuenta con tantos usuarios en el ámbito científico.

Qué no debes poner bajo control de versiones

Tamaños y formatos de archivo

Los beneficios del control de versiones no se aplican por igual a todos los tipos de archivo. En particular, estos sistemas pueden resultar más o menos útiles según el tamaño y el formato.

• Para empezar, la comparación de archivos en sistemas de control de versiones está optimizada para archivos de texto plano, como el código fuente. Normalmente, poder ver las "diffs" es una de las grandes ventajas del control de versiones. Por desgracia, aunque los archivos de Microsoft Office (como los .docx de Word) u otros binarios, por ejemplo PDFs, pueden guardarse en un sistema de control de versiones, no es posible identificar cambios concretos de una versión a otra. También se pueden incluir datos tabulares, como archivos CSV, pero cambiar el orden de filas o columnas generará una gran diferencia aunque los datos en sí no hayan cambiado.

• En segundo lugar, los datos en bruto no deberían cambiar y, por tanto, no requieren seguimiento de versiones. Tampoco es necesario versionar los archivos de datos intermedios u otros resultados si puedes regenerarlos a partir de los datos en bruto y el software. No obstante, si los datos y resultados son pequeños, es recomendable versionarlos para facilitar el acceso de colaboradores y la comparación entre versiones.

• En tercer lugar, los sistemas de control de versiones actuales no están pensados para manejar archivos de varios megabytes, y menos aún gigabytes, así que no conviene incluir archivos grandes de datos o resultados. (Como referencia de "grande", el límite para un archivo individual en GitHub es de 100 MB). Están surgiendo sistemas híbridos como Git LFS que guardan bajo control de versiones las referencias textuales y almacenan los datos grandes en un servidor remoto, pero aún no están lo bastante maduros como para recomendarlos sin reservas.

Compartir por accidente

Otro caso en el que los beneficios del control de versiones no juegan a tu favor es el del "compartir por accidente". Quienes trabajen con datos sujetos a restricciones legales que impidan su difusión (por ejemplo, datos médicos) deben evitar subirlos a sistemas públicos de control de versiones. Algunas instituciones ofrecen acceso a sistemas privados, así que merece la pena consultarlo con tu departamento de TI.

Además, asegúrate de no incluir sin querer credenciales de seguridad, como contraseñas y claves privadas, en un sistema de control de versiones donde otras personas puedan acceder a ellas.

Si quieres probar todo esto, echa un vistazo a nuestro curso gratuito de introducción a Git para Data Science.

Agradecimientos

Esta publicación está basada en "Good enough practices in scientific computing" de Greg Wilson, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt y Tracy K. Teal, https://doi.org/10.1371/journal.pcbi.1005510.