Controllo di versione per la data science

Tenere traccia delle modifiche che tu o i tuoi collaboratori apportate a dati e software è una parte fondamentale di qualsiasi progetto, che si tratti di ricerca, data science o ingegneria del software. Poter fare riferimento o recuperare una versione specifica dell’intero progetto aiuta la riproducibilità sia in fase di preparazione alla pubblicazione, sia quando rispondi ai commenti dei revisori o fornisci informazioni di supporto a revisori, editor e lettori.

Gli strumenti migliori per tracciare le modifiche sono i sistemi di controllo di versione usati nello sviluppo software, come Git, Mercurial e Subversion. Registrano cosa è stato cambiato in un file, quando e da chi, e sincronizzano le modifiche su un server centrale affinché più collaboratori possano gestire cambiamenti allo stesso insieme di file.

Sebbene questi strumenti rendano più semplice il tracciamento delle modifiche, possono avere una curva di apprendimento ripida. Per superarla, esistono due insiemi di raccomandazioni: un approccio manuale sistematico per gestire le modifiche e il controllo di versione in tutta la sua potenza. Puoi usare il primo mentre lavori verso il secondo, oppure tuffarti direttamente nel controllo di versione.

Buone pratiche per il controllo di versione

Qualunque opzione tu scelga, ci sono alcune buone pratiche e raccomandazioni generali da tenere a mente:

1. Fai il backup (quasi) di tutto ciò che crea un essere umano non appena viene creato. Questo include script e programmi di ogni tipo, pacchetti software da cui dipende il tuo progetto e documentazione. Alcune eccezioni a questa regola sono discusse di seguito.

2. Tieni le modifiche piccole. Ogni modifica non dovrebbe essere così grande da rendere irrilevante il tracciamento. Per esempio, una singola modifica come Revise script file che aggiunge o cambia diverse centinaia di righe è probabilmente troppo ampia, perché non permette di analizzare separatamente cambiamenti a componenti diversi di un’analisi. Allo stesso modo, le modifiche non dovrebbero essere spezzettate in parti troppo piccole. Come regola generale, una buona dimensione per una singola modifica è un gruppo di interventi che potresti voler annullare in un solo passaggio in futuro.

3. Condividi le modifiche spesso. Tutti coloro che lavorano al progetto dovrebbero condividere e integrare regolarmente le modifiche degli altri. Non permettere che le versioni del repository del progetto dei singoli ricercatori divergano, perché lo sforzo necessario per unire le differenze cresce più velocemente della loro dimensione. Questo è particolarmente importante per la procedura di versionamento manuale descritta sotto, che non offre alcun aiuto per unire cambiamenti simultanei, potenzialmente in conflitto.

4. Crea, mantieni e usa una checklist per salvare e condividere le modifiche al progetto. L’elenco dovrebbe includere la scrittura di messaggi di log che spieghino chiaramente ogni modifica, la dimensione e il contenuto delle singole modifiche, le linee guida di stile per il codice, l’aggiornamento delle to-do list e il divieto di fare commit di lavoro a metà o codice rotto.

5. Archivia ogni progetto in una cartella che sia replicata al di fuori del computer di lavoro del ricercatore usando un sistema come Dropbox o un repository remoto come GitHub. Sincronizza quella cartella almeno una volta al giorno. Potrà richiedere qualche minuto, ma quel tempo viene ripagato nel momento in cui un portatile viene rubato o il disco si guasta.

Come affrontare il versionamento manuale

Il primo approccio suggerito, in cui tutto è fatto a mano, ha due ulteriori componenti.

Per prima cosa, aggiungi un file chiamato CHANGELOG.txt alla sottocartella docs del progetto e annota in questo file, con data e in ordine cronologico inverso (ovvero, i più recenti per primi), le modifiche apportate al progetto. Questo file è l’equivalente di un quaderno di laboratorio e dovrebbe contenere voci come quelle mostrate di seguito.

## 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).

In secondo luogo, copia l’intero progetto ogni volta che viene effettuata una modifica significativa (cioè una che influisce materialmente sui risultati) e archivia quella copia in una sottocartella il cui nome riflette la data, nell’area che viene sincronizzata. Questo approccio porta a progetti organizzati come mostrato sotto:

.
|-- 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

Qui, la cartella project_name è mappata su uno storage esterno (come Dropbox), current è dove si lavora, e le altre cartelle dentro project_name sono versioni precedenti.

Pro e contro del versionamento manuale

Si sente spesso dire "I dati costano poco, il tempo è prezioso". Copiare tutto come suggerito sopra può sembrare uno spreco, dato che molti file non saranno cambiati, ma considera: un hard disk da un terabyte costa circa 50 $ al dettaglio, il che significa che 50 GB costano meno di 5 $. A patto di tenere i file di dati di grandi dimensioni fuori dall’area sottoposta a backup (ne parleremo più dettagliatamente sotto), questo approccio costa meno del tempo che servirebbe per selezionare a mano i file da copiare.

Questa procedura manuale soddisfa i requisiti delineati sopra senza bisogno di nuovi strumenti. Se però più ricercatori lavorano allo stesso progetto, dovranno coordinarsi affinché una sola persona modifichi specifici file in un dato momento. In particolare, potrebbero voler creare un file di changelog per ciascun contributore e unire tali file ogni volta che si crea una copia di backup.

Sistemi di controllo di versione

Ciò che il processo manuale descritto sopra richiede maggiormente è autodisciplina. Gli strumenti alla base del nostro secondo approccio — quello che usiamo nei nostri progetti — non solo accelerano il processo manuale: automatizzano alcuni passaggi mentre ne impongono altri e richiedono quindi meno autodisciplina per risultati più affidabili.

È difficile sapere quale strumento sia oggi il più usato nella ricerca, ma quello di cui si parla di più è senza dubbio Git. Questo soprattutto grazie a GitHub, un popolare servizio di hosting che combina l’infrastruttura tecnica per la collaborazione via Git con un’interfaccia web moderna. GitHub è gratuito per progetti pubblici e open source e per utenti nel mondo accademico e no-profit. GitLab è un’alternativa molto apprezzata che alcuni preferiscono, perché la piattaforma stessa è open source e gratuita. Bitbucket offre hosting gratuito sia per repository Git che Mercurial, ma non ha una base di utenti scientifici altrettanto ampia.

Cosa non mettere sotto controllo di versione

Dimensioni e formati dei file

I vantaggi dei sistemi di controllo di versione non si applicano allo stesso modo a tutti i tipi di file. In particolare, questi sistemi possono essere più o meno utili a seconda della dimensione e del formato dei file.

• Innanzitutto, il confronto dei file nei sistemi di controllo di versione è ottimizzato per i file di testo semplice, come il codice sorgente. Di solito, la possibilità di vedere i cosiddetti "diff" è uno dei grandi punti di forza del controllo di versione. Purtroppo, sebbene i file Microsoft Office (come i file .docx usati da Word) o altri file binari, ad esempio i PDF, possano essere archiviati in un sistema di controllo di versione, non è possibile individuare cambiamenti specifici da una versione all’altra. Anche i dati tabellari, come i file CSV, possono essere inseriti in tali sistemi, ma cambiare l’ordine di righe o colonne genererà una grande differenza, anche se i dati in sé non sono cambiati.

• In secondo luogo, i dati grezzi non dovrebbero cambiare e quindi non dovrebbero richiedere il tracciamento delle versioni. Mantenere sotto controllo di versione file di dati intermedi e altri risultati non è necessario se puoi rigenerarli dai dati grezzi e dal software. Tuttavia, se dati e risultati sono piccoli, è consigliabile versionarli per facilitare l’accesso da parte dei collaboratori e il confronto tra versioni.

• In terzo luogo, i sistemi di controllo di versione odierni non sono progettati per gestire file di dimensioni nell’ordine dei megabyte, per non parlare dei gigabyte, quindi i file di dati o risultati di grandi dimensioni non dovrebbero essere inclusi. (Come riferimento per "grande", il limite per un singolo file su GitHub è 100 MB.) Alcuni sistemi ibridi emergenti, come Git LFS, mettono sotto controllo di versione le note testuali, archiviando invece i dati di grandi dimensioni su un server remoto, ma non sono ancora abbastanza maturi da poterli consigliare.

Condivisione involontaria

Un altro caso in cui i benefici dei sistemi di controllo di versione non giocano davvero a tuo favore è quello della "condivisione involontaria". I ricercatori che trattano dati soggetti a restrizioni legali che ne vietano la condivisione (come i dati medici) dovrebbero fare attenzione a non inserire dati in sistemi pubblici di controllo di versione. Alcune istituzioni possono fornire accesso a sistemi privati, quindi vale la pena informarsi presso il reparto IT.

Inoltre, assicurati di non inserire involontariamente credenziali di sicurezza, come password e chiavi private, in un sistema di controllo di versione dove potrebbero essere accessibili ad altri.

Se vuoi provare tutto questo, dai un’occhiata alla nostra introduzione gratuita a Git per la Data Science.

Ringraziamenti

Questo post è tratto da "Good enough practices in scientific computing" di Greg Wilson, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt e Tracy K. Teal, https://doi.org/10.1371/journal.pcbi.1005510.