Versiebeheer voor data science

Wijzigingen bijhouden die jij of je samenwerkers aan data en software doen, is een cruciaal onderdeel van elk project, of het nu onderzoek, data science of software-engineering is. De mogelijkheid om naar een specifieke versie van het hele project te verwijzen of die terug te halen, helpt bij reproduceerbaarheid: voorafgaand aan publicatie, bij het beantwoorden van reviewers, en bij het aanleveren van ondersteunende informatie voor reviewers, redacteuren en lezers.

De beste tools om wijzigingen te volgen zijn de versiebeheersystemen die in softwareontwikkeling worden gebruikt, zoals Git, Mercurial en Subversion. Ze houden bij wat er in een bestand is gewijzigd, wanneer en door wie, en synchroniseren wijzigingen met een centrale server zodat meerdere bijdragers veranderingen aan dezelfde set bestanden kunnen beheren.

Hoewel deze tools het bijhouden van wijzigingen makkelijker maken, kunnen ze een steile leercurve hebben. Om die leercurve te overwinnen, zijn er twee sets aanbevelingen: een systematische, handmatige aanpak voor het beheren van wijzigingen en versiebeheer in volle glorie. Je kunt de eerste gebruiken terwijl je naar de tweede toewerkt, of meteen in versiebeheer duiken.

Best practices voor versiebeheer

Welke aanbeveling je uiteindelijk ook kiest, er zijn een paar algemene best practices of aanbevelingen om rekening mee te houden:

1. Maak (bijna) alles wat door een mens is gemaakt direct een back-up. Dit omvat scripts en programma's van allerlei aard, softwarepakketten waarvan je project afhankelijk is, en documentatie. Enkele uitzonderingen op deze regel worden hieronder besproken.

2. Houd wijzigingen klein. Elke wijziging moet niet zo groot zijn dat het bijhouden ervan zinloos wordt. Een enkele wijziging zoals Revise script file die enkele honderden regels toevoegt of wijzigt, is waarschijnlijk te groot, omdat dit niet toelaat om veranderingen aan verschillende onderdelen van een analyse afzonderlijk te onderzoeken. Tegelijkertijd moeten wijzigingen ook niet in té kleine stukjes worden opgeknipt. Vuistregel: een goede omvang voor één wijziging is een groep bewerkingen waarvan je je kunt voorstellen dat je die op een gegeven moment in één stap ongedaan wilt maken.

3. Deel wijzigingen vaak. Iedereen die aan het project werkt, zou regelmatig wijzigingen moeten delen en die van anderen moeten overnemen. Laat versies van de projectrepository van individuele onderzoekers niet uit elkaar lopen, want de inspanning die nodig is om verschillen samen te voegen, neemt sneller toe dan de omvang van het verschil. Dit is extra belangrijk voor de hieronder beschreven handmatige versieprocedure, die geen hulp biedt bij het samenvoegen van gelijktijdige, mogelijk conflicterende veranderingen.

4. Maak, onderhoud en gebruik een checklist voor het opslaan en delen van wijzigingen in het project. De lijst moet onder meer bevatten: logberichten schrijven die wijzigingen duidelijk uitleggen, de omvang en inhoud van afzonderlijke wijzigingen, stijlafspraken voor code, het bijwerken van to-dolijsten, en verboden op het committen van half werk of kapotte code.

5. Sla elk project op in een map die gespiegeld wordt buiten de werkmachine van de onderzoeker met een systeem zoals Dropbox of een externe repository zoals GitHub. Synchroniseer die map minstens dagelijks. Het kost een paar minuten, maar die tijd verdien je direct terug als een laptop wordt gestolen of de harde schijf crasht.

Hoe handmatig versiebeheer aan te pakken

De eerste voorgestelde aanpak, waarbij alles met de hand gebeurt, heeft twee extra onderdelen.

Voeg eerst een bestand genaamd CHANGELOG.txt toe aan de submap docs van het project, en maak gedateerde notities over wijzigingen aan het project in dit bestand in omgekeerd chronologische volgorde (dus meest recent bovenaan). Dit bestand is het equivalent van een labjournaal en zou items moeten bevatten zoals hieronder getoond.

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

Kopieer vervolgens het hele project wanneer er een significante wijziging is aangebracht (dus een wijziging die de resultaten wezenlijk beïnvloedt), en sla die kopie op in een submap waarvan de naam de datum weerspiegelt, in het gebied dat gesynchroniseerd wordt. Deze aanpak resulteert in projecten die als volgt zijn georganiseerd:

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

Hier wordt de map project_name gekoppeld aan externe opslag (zoals Dropbox), is current de plek waar wordt gewerkt, en zijn andere mappen binnen project_name oude versies.

Voor- en nadelen van handmatig versiebeheer

Je hoort vaak: "Data is goedkoop, tijd is duur". Alles kopiëren zoals de bovenstaande aanpak suggereert, kan verspilling lijken, omdat veel bestanden niet zijn gewijzigd. Maar bedenk: een harde schijf van een terabyte kost in de winkel ongeveer \$50, wat betekent dat 50 GB minder dan $5 kost. Zolang grote databestanden buiten het geback-upte gebied worden gehouden (dit komt hieronder verder aan bod), kost deze aanpak minder dan de tijd die het zou kosten om bestanden handmatig te selecteren voor kopiëren.

Deze handmatige procedure voldoet aan de hierboven geschetste eisen zonder dat er nieuwe tools nodig zijn. Als meerdere onderzoekers aan hetzelfde project werken, moeten ze echter afstemmen zodat maar één persoon tegelijk aan specifieke bestanden werkt. Ze kunnen er met name voor kiezen om één changelogbestand per bijdrager te maken en die bestanden samen te voegen telkens wanneer een back-upkopie wordt gemaakt.

Versiebeheersystemen

Wat het hierboven beschreven handmatige proces vooral vereist, is zelfdiscipline. De tools die onze tweede aanpak ondersteunen — de aanpak die we in onze eigen projecten gebruiken — versnellen niet alleen het handmatige proces: ze automatiseren ook enkele stappen en dwingen andere af, en vereisen daardoor minder zelfdiscipline voor betrouwbaardere resultaten.

Het is lastig te zeggen welk hulpmiddel vandaag de dag het meest wordt gebruikt in onderzoek, maar de tool waar ongetwijfeld het meest over wordt gesproken, is Git. Dat komt grotendeels door GitHub, een populair hostingplatform dat de technische infrastructuur voor samenwerking via Git combineert met een moderne webinterface. GitHub is gratis voor publieke en open-sourceprojecten en voor gebruikers in het onderwijs en non-profits. GitLab is een goed aangeschreven alternatief dat sommigen prefereren, omdat het GitLab-platform zelf vrij en open source is. Bitbucket biedt gratis hosting voor zowel Git- als Mercurial-repositories, maar heeft lang niet zoveel wetenschappelijke gebruikers.

Wat je niet onder versiebeheer moet zetten

Bestandsgroottes en -formaten

De voordelen van versiebeheersystemen gelden niet in gelijke mate voor alle bestandstypen. Deze systemen kunnen met name meer of minder opleveren afhankelijk van bestandsgrootte en -formaat.

• Ten eerste is bestandsvergelijking in versiebeheersystemen geoptimaliseerd voor platte-tekstbestanden, zoals broncode. De mogelijkheid om zogenaamde "diffs" te zien, is normaal gesproken een van de grote pluspunten van versiebeheer. Helaas kunnen Microsoft Office-bestanden (zoals de door Word gebruikte .docx-bestanden) of andere binaire bestanden, bijvoorbeeld PDF's, wel in een versiebeheersysteem worden opgeslagen, maar is het niet mogelijk om specifieke wijzigingen van de ene naar de andere versie precies aan te wijzen. Ook tabeldata, zoals CSV-bestanden, kunnen in zo'n systeem worden gezet, maar het wijzigen van de volgorde van rijen of kolommen zal een grote wijziging opleveren, zelfs als de data zelf niet is veranderd.

• Ten tweede zou ruwe data niet moeten veranderen en hoeft daarom niet onder versiebeheer te staan. Het onder versiebeheer plaatsen van intermediaire databestanden en andere resultaten is evenmin nodig als je ze kunt regenereren uit ruwe data en software. Maar als data en resultaten klein zijn, is het aan te raden ze te versioneren voor gemakkelijke toegang door samenwerkers en voor vergelijking tussen versies.

• Ten derde zijn versiebeheersystemen van vandaag niet ontworpen om bestanden van megabytes groot te verwerken, laat staan gigabytes, dus grote data- of resultatenbestanden moeten niet worden opgenomen. (Als ijkpunt voor "groot": de limiet voor een individueel bestand op GitHub is 100 MB.) Sommige opkomende hybride systemen zoals Git LFS zetten tekstuele notities onder versiebeheer, terwijl de grote data zelf op een externe server wordt opgeslagen, maar deze zijn nog niet volwassen genoeg om aan te raden.

Onbedoeld delen

Een andere situatie waarin de voordelen van versiebeheersystemen niet in je voordeel werken, is het geval van "onbedoeld delen". Onderzoekers die werken met data die onderhevig is aan juridische beperkingen die delen verbieden (zoals medische data), moeten ervoor waken om die data niet in publieke versiebeheersystemen te plaatsen. Sommige instellingen bieden mogelijk toegang tot private systemen, dus het is de moeite waard om dit bij je IT-afdeling na te vragen.

Zorg er daarnaast voor dat je geen beveiligingsgegevens, zoals wachtwoorden en privésleutels, per ongeluk in een versiebeheersysteem plaatst waar anderen er mogelijk bij kunnen.

Wil je dit allemaal eens uitproberen? Bekijk dan onze gratis introductie tot Git voor Data Science.

Dankwoord

Deze post is afkomstig uit "Good enough practices in scientific computing" door Greg Wilson, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt en Tracy K. Teal, https://doi.org/10.1371/journal.pcbi.1005510.