Controle de versão para data science

Acompanhar as alterações que você ou seus colaboradores fazem em dados e software é parte crucial de qualquer projeto, seja de pesquisa, data science ou engenharia de software. Conseguir recuperar ou fazer referência a uma versão específica de todo o projeto ajuda na reprodutibilidade antes da publicação, ao responder comentários de revisores e ao fornecer informações de apoio para revisores, editores e leitores.

As melhores ferramentas para rastrear mudanças são os sistemas de controle de versão usados em desenvolvimento de software, como Git, Mercurial e Subversion. Eles registram o que mudou em um arquivo, quando e por quem, e sincronizam as alterações em um servidor central para que vários colaboradores possam gerenciar mudanças no mesmo conjunto de arquivos.

Embora essas ferramentas facilitem o acompanhamento de mudanças, elas podem ter uma curva de aprendizado bem acentuada. Para vencê-la, há dois conjuntos de recomendações: um método manual, sistemático, para gerenciar alterações, e o controle de versão em sua forma completa. Você pode começar pelo primeiro enquanto avança rumo ao segundo — ou ir direto para o controle de versão.

Boas práticas de controle de versão

Independentemente da abordagem que você escolher, vale a pena considerar algumas boas práticas gerais:

1. Faça backup de (quase) tudo que foi criado por uma pessoa assim que for criado. Isso inclui scripts e programas de todos os tipos, pacotes de software dos quais seu projeto depende e documentação. Algumas exceções a essa regra são discutidas abaixo.

2. Mantenha as mudanças pequenas. Cada alteração não deve ser tão grande a ponto de tornar o rastreamento irrelevante. Por exemplo, uma única mudança como Revisar arquivo de script que adiciona ou modifica algumas centenas de linhas provavelmente é grande demais, pois não permitirá investigar separadamente mudanças em diferentes partes de uma análise. Da mesma forma, alterações não devem ser fragmentadas em pedaços minúsculos demais. Como regra prática, um bom tamanho para uma alteração é um grupo de edições que você poderia querer desfazer de uma só vez no futuro.

3. Compartilhe alterações com frequência. Todo mundo que trabalha no projeto deve compartilhar e incorporar mudanças dos outros regularmente. Não deixe que as versões do repositório de cada pessoa se afastem demais, pois o esforço para mesclar diferenças cresce mais rápido do que o tamanho da diferença. Isso é particularmente importante no procedimento manual descrito abaixo, que não oferece suporte para mesclar mudanças simultâneas e possivelmente conflitantes.

4. Crie, mantenha e use um checklist para salvar e compartilhar alterações do projeto. A lista deve incluir escrever mensagens de log que expliquem claramente as mudanças, o tamanho e o conteúdo de cada alteração, diretrizes de estilo para o código, atualização das listas de tarefas e proibição de enviar trabalho pela metade ou código quebrado.

5. Armazene cada projeto em uma pasta espelhada fora da máquina de trabalho do pesquisador usando um sistema como Dropbox ou um repositório remoto como o GitHub. Sincronize essa pasta pelo menos diariamente. Isso pode levar alguns minutos, mas esse tempo é recuperado no momento em que um laptop é roubado ou o HD dá problema.

Como fazer versionamento manual

A primeira abordagem sugerida, em que tudo é feito à mão, tem duas partes adicionais.

Primeiro, adicione um arquivo chamado CHANGELOG.txt à subpasta docs do projeto e registre, com data, as mudanças do projeto nesse arquivo em ordem cronológica inversa (ou seja, as mais recentes no topo). Esse arquivo é o equivalente ao caderno de laboratório e deve conter entradas como as mostradas abaixo.

## 2016-04-08

* Alterado para interpolação cúbica como padrão.
* Pergunta sobre histórico de TB na família movida para o final do questionário.

## 2016-04-06

* Adicionada opção de interpolação cúbica.
* Removida a pergunta sobre exposição a estafilococos (pode ser inferida a partir dos resultados do exame de sangue).

Segundo, copie todo o projeto sempre que for feita uma mudança significativa (ou seja, algo que afete materialmente os resultados) e armazene essa cópia em uma subpasta cujo nome reflita a data, na área que está sendo sincronizada. Essa abordagem organiza os projetos como mostrado abaixo:

.
|-- project_name
|   -- current
|       -- ...conteúdo do projeto conforme descrito antes...
|   -- 2016-03-01
|       -- ...conteúdo de 'current' em 1º mar 2016
|   -- 2016-02-19
|       -- ...conteúdo de 'current' em 19 fev 2016

Aqui, a pasta project_name é mapeada para um armazenamento externo (como Dropbox), current é onde o trabalho acontece e as outras pastas dentro de project_name são versões antigas.

Prós e contras do versionamento manual

Você vai ouvir com frequência: "dados são baratos, tempo é caro". Copiar tudo, como a abordagem acima sugere, pode parecer desperdício, já que muitos arquivos não terão mudado. Mas pense: um HD de 1 terabyte custa cerca de US$ 50 no varejo, o que significa que 50 GB saem por menos de US$ 5. Desde que arquivos de dados muito grandes fiquem fora da área com backup (vamos discutir isso adiante), essa abordagem custa menos do que o tempo de selecionar arquivos manualmente para copiar.

Esse procedimento manual atende aos requisitos descritos acima sem precisar de novas ferramentas. Porém, se vários pesquisadores trabalham no mesmo projeto, será necessário coordenar para que apenas uma pessoa mexa em arquivos específicos por vez. Em particular, pode ser útil criar um arquivo de changelog por colaborador e mesclá-los sempre que uma cópia de backup for feita.

Sistemas de controle de versão

O que o processo manual descrito acima mais exige é disciplina. As ferramentas da nossa segunda abordagem — a que usamos nos nossos próprios projetos — não só aceleram o processo manual: elas também automatizam algumas etapas e forçam outras, exigindo menos disciplina para resultados mais confiáveis.

É difícil saber qual ferramenta é a mais usada hoje em pesquisa, mas a mais comentada é, sem dúvida, o Git. Muito disso se deve ao GitHub, um serviço de hospedagem popular que combina a infraestrutura técnica de colaboração via Git com uma interface web moderna. O GitHub é gratuito para projetos públicos e de código aberto e para usuários acadêmicos e organizações sem fins lucrativos. O GitLab é uma alternativa bem conceituada que alguns preferem, porque a própria plataforma GitLab é gratuita e de código aberto. O Bitbucket oferece hospedagem gratuita para repositórios Git e Mercurial, mas não tem tantos usuários na comunidade científica.

O que não colocar sob controle de versão

Tamanhos e formatos de arquivo

Os benefícios dos sistemas de controle de versão não se aplicam igualmente a todos os tipos de arquivo. Em especial, o ganho pode variar conforme o tamanho e o formato do arquivo.

• Primeiro, a comparação de arquivos em sistemas de controle de versão é otimizada para arquivos de texto simples, como código-fonte. Normalmente, ver os chamados "diffs" é uma das grandes vantagens do controle de versão. Infelizmente, embora arquivos do Microsoft Office (como .docx do Word) ou outros arquivos binários, por exemplo PDFs, possam ser armazenados em um sistema de controle de versão, não é possível identificar com precisão as mudanças de uma versão para a outra. Já dados tabulares, como arquivos CSV, até podem ser versionados, mas mudar a ordem de linhas ou colunas vai gerar uma alteração enorme, mesmo que os dados em si não tenham mudado.

• Segundo, dados brutos não deveriam mudar e, portanto, não exigem versionamento. Manter arquivos de dados intermediários e outros resultados sob controle de versão também não é necessário se você consegue regenerá-los a partir dos dados brutos e do software. No entanto, se dados e resultados forem pequenos, é recomendável versioná-los para facilitar o acesso pelos colaboradores e permitir comparações entre versões.

• Terceiro, os sistemas de controle de versão atuais não foram feitos para lidar com arquivos de megabytes — muito menos de gigabytes —, então arquivos grandes de dados ou resultados não devem ser incluídos. (Como referência de "grande", o limite de um arquivo individual no GitHub é 100 MB.) Alguns sistemas híbridos emergentes, como o Git LFS, colocam notas textuais sob controle de versão e armazenam os dados grandes em um servidor remoto, mas ainda não estão maduros o suficiente para recomendarmos.

Compartilhamento inadvertido

Outra situação em que os benefícios do controle de versão não jogam a seu favor é o caso do "compartilhamento sem querer". Pesquisadores que lidam com dados sujeitos a restrições legais que proíbem o compartilhamento (como dados médicos) devem tomar cuidado para não colocar dados em sistemas públicos de controle de versão. Algumas instituições podem oferecer acesso a sistemas privados, então vale conferir com o seu time de TI.

Além disso, certifique-se de não colocar, por engano, credenciais sensíveis — como senhas e chaves privadas — em um sistema de controle de versão onde outros possam acessá-las.

Se você quiser experimentar tudo isso na prática, confira nossa introdução gratuita ao Git para Data Science.

Agradecimentos

Este post foi extraído de "Good enough practices in scientific computing" de Greg Wilson, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt e Tracy K. Teal, https://doi.org/10.1371/journal.pcbi.1005510.