Blog
Versionamento da planilha e script R: como tornar a análise reprodutível
Uma análise estatística não termina quando o valor de p aparece na tela. Em TCC, dissertação, tese ou artigo, uma pergunta igualmente importante é: se o banco mudar, você consegue identificar o que mudou, executar novamente a análise e chegar aos resultados correspondentes? É aí que entram o versionamento da planilha e o script R.
Versionar não significa criar dezenas de arquivos chamados final, final2 e final_agora_vai. Significa manter uma trilha compreensível entre dados recebidos, decisões de limpeza, transformações, análise e resultados. Diretrizes recentes de integridade de dados destacam a necessidade de registrar versões dos dados, consultas e mudanças no processamento para favorecer a reprodutibilidade.
Por que a planilha final não é suficiente?
Imagine uma pesquisa com 250 participantes. Depois da primeira análise, o pesquisador percebe que três idades foram digitadas incorretamente e que uma categoria estava codificada de duas formas. Se essas correções forem feitas diretamente no único arquivo existente, sem registro, torna-se difícil saber por que uma tabela mudou. O problema não é corrigir o dado; é perder a história da correção.
Uma prática mais segura é preservar uma versão dos dados recebidos e realizar limpeza e transformação de maneira documentada. O banco original funciona como referência, enquanto arquivos derivados representam etapas posteriores. Isso ajuda tanto quem analisa quanto quem precisa revisar o trabalho meses depois.
Essa organização complementa o cuidado descrito no nosso guia sobre coleta de dados e construção do banco. Um banco bem estruturado reduz erros; uma trilha de versões permite entender o que aconteceu depois que ele entrou na análise.
Como nomear versões sem criar confusão
Não existe uma convenção universal obrigatória, mas o nome precisa permitir identificar o arquivo sem depender da memória. Datas em formato AAAA-MM-DD, número de versão e uma descrição curta podem ser úteis. Por exemplo: dados_recebidos_2026-09-23.xlsx, dados_limpos_v01.csv e dicionario_variaveis_v02.xlsx.
O ponto central é estabelecer uma regra e mantê-la. Alterações relevantes também podem ser registradas em um arquivo CHANGELOG ou README: data, versão, responsável e motivo da mudança. Estudos sobre versionamento de conjuntos de dados defendem mecanismos que permitam rastrear versões e comparar mudanças, favorecendo reutilização e integração.
O banco bruto deve ser preservado
Quando possível, evite transformar manualmente o arquivo bruto e salvá-lo por cima. Uma estrutura simples de projeto pode separar pastas como data_raw, data_processed, scripts, outputs e docs. O arquivo bruto fica preservado; o script lê esse arquivo, aplica regras explícitas e gera a versão processada.
Isso não significa publicar dados pessoais ou sensíveis. Reprodutibilidade e abertura são conceitos relacionados, mas não idênticos. Restrições éticas, consentimento, LGPD e regras institucionais continuam valendo. É possível manter um processo internamente reprodutível sem tornar dados identificáveis públicos.
Por que o script R muda a qualidade da análise
Operações feitas apenas por cliques ou edições manuais podem ser difíceis de reconstruir. Um script registra instruções: importar dados, recodificar variáveis, aplicar critérios de exclusão, produzir estatísticas descritivas, ajustar modelos e gerar tabelas ou figuras.
Isso é especialmente útil quando a banca ou um revisor pede uma alteração. Em vez de refazer etapas manualmente, você modifica a regra apropriada e executa novamente o fluxo. Nosso guia como fazer a análise estatística do TCC passo a passo mostra como as decisões estatísticas precisam acompanhar a pergunta do estudo; o script acrescenta rastreabilidade a essas decisões.
Um roteiro simples de script em R
Para projetos pequenos, não é necessário começar com uma infraestrutura complexa. Um fluxo pode ser dividido em blocos: configuração do projeto e pacotes; importação; conferência e limpeza; criação de variáveis derivadas; análise descritiva; análise inferencial; exportação de tabelas e gráficos.
Outra possibilidade é separar essas etapas em scripts numerados, como 01_importacao.R, 02_limpeza.R, 03_descritiva.R e 04_modelos.R. O importante é que a ordem seja clara e que cada etapa tenha uma função definida.
Também vale registrar decisões que não ficam evidentes no código: por que determinada variável foi recodificada, qual regra definiu um valor impossível ou por que um participante foi excluído. Comentários no script e um README curto podem economizar muito tempo posteriormente.
Planilha, dicionário de dados e script cumprem funções diferentes
A planilha contém observações. O dicionário explica o significado das variáveis, unidades, categorias e códigos. O script descreve as transformações e análises. Esses três elementos se complementam.
Por exemplo, uma coluna grupo com valores 0 e 1 não é autoexplicativa. O dicionário pode indicar 0 = controle e 1 = intervenção. O script pode converter os códigos em fatores com rótulos legíveis. Separar essas responsabilidades reduz ambiguidades e facilita a revisão.
O mesmo princípio vale para dados faltantes: decisões sobre exclusão, imputação ou modelagem precisam ser justificadas, e não escondidas em edições silenciosas da planilha.
Git é obrigatório?
Não. Para um projeto pequeno, uma convenção consistente de arquivos e backups já representa grande avanço. Mas sistemas de controle de versão acrescentam recursos úteis: histórico de alterações, comparação entre versões e possibilidade de recuperar estados anteriores do código.
Em equipes, o benefício aumenta porque alterações deixam de depender da troca de anexos por e-mail. Ainda assim, controle de versão não substitui uma política adequada para dados sensíveis. Bancos identificáveis não devem ser enviados automaticamente para repositórios públicos.
Registre também o ambiente computacional
Um script pode deixar de produzir exatamente o mesmo resultado no futuro se versões de pacotes mudarem. No ecossistema R, o pacote renv permite criar uma biblioteca específica do projeto e um arquivo de bloqueio que registra pacotes e versões. A documentação oficial informa que esse lockfile pode ser usado para restaurar o ambiente do projeto.
Em análises mais extensas, ferramentas de pipeline também podem explicitar dependências entre dados, modelos e produtos. O Transparent Assessment Framework, por exemplo, organiza uma análise em etapas sequenciais e inclui recursos voltados ao versionamento de dados e software. Isso não é requisito para todo TCC, mas mostra que reprodutibilidade é uma propriedade do fluxo inteiro, não apenas do arquivo final.
Resultados também devem nascer do código
Uma fonte frequente de inconsistência ocorre quando o resultado é calculado no R e depois copiado manualmente para Word ou Excel. Se a análise mudar, uma tabela antiga pode permanecer no texto. Sempre que for viável, exporte tabelas e figuras diretamente do script e identifique os arquivos gerados.
Essa prática também melhora a produção de gráficos estatísticos adequados ao tipo de resultado. O código registra não apenas os números, mas filtros, escalas, rótulos e demais escolhas usadas na figura.
Um checklist mínimo para análise reprodutível
Antes de considerar a análise encerrada, verifique: o banco bruto foi preservado? As versões processadas têm identificação clara? Existe dicionário de variáveis? As correções importantes foram registradas? A limpeza pode ser refeita pelo script? Os critérios de exclusão estão explícitos? Tabelas e gráficos podem ser regenerados? Os pacotes utilizados estão documentados? Outra pessoa autorizada conseguiria compreender a sequência de passos?
Não é necessário transformar um trabalho acadêmico em um projeto de engenharia de software. O objetivo é reduzir dependência de memória, cliques e arquivos misteriosos.
Reprodutibilidade não significa resultado idêntico em qualquer situação
Alguns procedimentos possuem aleatoriedade. Nesses casos, pode ser necessário registrar uma semente aleatória. Diferenças de software, algoritmos ou arredondamentos também podem influenciar resultados. Por isso, documentar ambiente, versões e decisões é mais útil do que simplesmente afirmar que uma análise é reprodutível.
Os princípios FAIR propõem que artefatos digitais científicos sejam localizáveis, acessíveis, interoperáveis e reutilizáveis, sem impor uma tecnologia única. Para software de pesquisa, iniciativas FAIR4RS estendem essa discussão a códigos, scripts e fluxos computacionais. Na prática cotidiana, a ideia pode começar de forma simples: arquivos organizados, transformações explícitas e resultados que podem ser refeitos.
O que entregar ao final de uma consultoria estatística?
Quando o escopo permite, uma entrega tecnicamente transparente pode incluir banco analisado ou orientação sobre sua estrutura, dicionário de variáveis, script utilizado, tabelas, gráficos e notas sobre decisões relevantes. Isso ajuda o pesquisador a compreender o que foi feito e facilita ajustes posteriores.
Na Estatística para Pesquisa, a proposta é que a análise não seja uma caixa-preta. O pesquisador precisa conseguir compreender e defender os métodos utilizados. Se você está preparando TCC, dissertação, tese ou artigo, organizar o fluxo antes da análise pode evitar retrabalho justamente na fase em que o prazo costuma ficar mais apertado.
Referências e recursos
Wilkinson MD et al. The FAIR Guiding Principles for scientific data management and stewardship. Scientific Data. 2016;3:160018. Acesso editorial.
González-Cebrián A et al. Standardised Versioning of Datasets: a FAIR-compliant Proposal. Scientific Data. 2024;11:358. Acesso editorial.
Guidelines for Research Data Integrity (GRDI). Scientific Data. Acesso editorial.
R Project/CRAN. Transparent Assessment Framework for Reproducible Research. Documentação.
R Project/CRAN. renv: gerenciamento de dependências e lockfiles. Documentação.