Reprodutibilidade em R e GitHub

introR: introdução à linguagem R

16 de outubro de 2025

Conteúdo


  • Reprodutibilidade
  • Ambiente reprodutível: renv
  • Documentos dinâmicos: Quarto
  • Quarto e GitHub
  • Web applications (apps): Shiny

Reprodutibilidade

Capacidade de recriar uma análise e obter os mesmos resultados com os mesmos dados e códigos

Reprodutibilidade

Por que reprodutibilidade importa?


  • Transparência científica: todos podem verificar e entender o processo
  • Reutilização de código e dados: economiza tempo e reduz erros
  • Colaboração eficiente: equipes trabalham com o mesmo ambiente
  • Base sólida: análises confiáveis, auditáveis e atualizáveis

Reprodutibilidade

Pilares

  1. Organização do projeto
    • Diretórios: /data, /R, /output, /scripts
  2. Gerenciamento de dependências
    • renv: fixar versões dos pacotes
  3. Controle de versão
    • git + GitHub para rastrear mudanças
  4. Documentação clara
    • Descrever métodos e passos no README ou documento Quarto
  5. Automação e repetição
    • Scripts reproduzem todo o fluxo das análises
    • Web applications (apps) Shiny para interação on-line

Pacotes no R

Pacotes no R

  • Os pacotes mudam com o tempo (versões)
  • Quebras de código entre as principais versões
  • Acessível a partir de diferentes repositórios (CRAN, GitHub, R Universe, etc.)
  • Apenas uma versão de um pacote pode ser instalada
  • Um pacote pode ter muitas dependências

Temos que especificar os pacotes necessários, suas versões e os repositórios nos quais eles estão acessíveis

Pacotes no R

Biblioteca vs pacote

  • Biblioteca: diretório onde os pacotes são instalados
  • Pacote: coleção de funções, documentação, dados e testes
# bibliotecas
.libPaths()
[1] "/home/mude/R/x86_64-pc-linux-gnu-library/4.5"
[2] "/usr/local/lib/R/site-library"               
[3] "/usr/lib/R/site-library"                     
[4] "/usr/lib/R/library"                          
# pacotes
find.package("base")
[1] "/usr/lib/R/library/base"
find.package("renv")
[1] "/home/mude/R/x86_64-pc-linux-gnu-library/4.5/renv"

renv

Gerenciamento de pacotes

  • Cria um ambiente reprodutível (reproducible environment) e isolado de pacotes para cada projeto
  • Armazena versões dos pacotes em renv.lock
install.packages("renv")
library(renv)

renv

Por que usar renv?

  • Evita conflitos de versão funções mudam entre versões
  • Reproduz resultados mesmo após atualizações do R
  • Compartilha ambientes com colegas ou colaboradores
  • Documenta automaticamente os pacotes usados

renv

Funções


Função Descrição
init() Inicializa renv em um projeto
status() Verifica consistências entre o lockfile e a biblioteca do projeto
snapshot() Registra o estado atual da biblioteca do projeto no lockfile
restore() Restaura a biblioteca do projeto a partir de um lockfile
install() Instala pacotes na biblioteca do projeto
remove() Remove pacotes da biblioteca do projeto
deactivate() Desativa temporariamente renv para o projeto
activate() (Re)ativa renv no projeto

renv

Workflow

renv

Sistema de bibliotecas


Default R behaviour

Library system with renv

renv

Arquivos e diretório

  • .Rprofile: arquivo de perfil do projeto do RStudio
  • renv/: diretório que armazena as versões dos pacotes
  • renv.lock: arquivo com as versões de cada pacote para reconstruir o ambiente
.
├── .Rprofile          # Activate renv on project opening
│
├── renv/
│   ├── .gitignore     # Ignore large renv files (e.g. packages)
│   ├── activate.R     # R script to launch renv
│   ├── library/       # R packages
│   └── settings.dcf   # renv settings
│
└── renv.lock

renv

Fluxo de uso

# Inicializar ambiente renv
renv::init()

# Verificar o estado atual dos pacotes
renv::status()

# Instalar pacotes usando o renv
renv::install("tidyverse")

# Registrar estado atual dos pacotes
renv::snapshot()

# Restaurar ambiente em outra máquina
renv::restore()

renv

Colaborando com renv

  • Basta compartilhar o arquivo renv.lock
  • Então seu colega terá que inicializar o renv no projeto
  • Todos os pacotes no arquivo renv.lock serão instalados na biblioteca do projeto
# Restaurar ambiente em outra máquina
renv::restore()

renv

Recomendações

  • Use renv no final do projeto para congelar seu ambiente de pacotes e depois compartilhar o renv.lock
  • Adicione renv/ ao .gitignore
  • Versionar somento o renv.lock

Documentação no R

Documentação no R

Documentação no R

Documentação de pesquisa

  • Registro sistemático, claro e organizado das etapas de um projeto científico, desde o planejamento até a publicação

  • Garante que o trabalho possa ser entendido, verificado e reproduzido por outros pesquisadores

Documentação no R

Escrita científica

Documentação no R

Programação Literária

Programação literária é um paradigma de programação introduzido em 1984 por Donald Knuth (LaTeX), no qual um programa de computador é apresentado como uma explicação de como ele funciona em uma linguagem natural (e.g. inglês), intercalado (embutido) com trechos de macros e código-fonte tradicional, a partir dos quais um código-fonte compilável pode ser gerado.

Conceito inicial

Implementação moderna com Quarto

Quarto

Descrição

  • Fornece uma estrutura para ciência de dados, combinando código, resultados e texto
  • Documentos são totalmente reproduzíveis, automatizando a inclusão das últimas versões dos resultados e análises
  • Quarto é a nova geração do R Markdown

Quarto

Software

  • Software novo que não depende do R (instalado com o RStudio)
  • Interface de linha de comando - Command Line Interface (CLI)
  • Podemos usar o Quarto no terminal
quarto help

Usage:   quarto
Version: 1.9.2 

Description:

  Quarto CLI

Options:

  -h, --help     - Show this help.                            
  -V, --version  - Show the version number for this program.  

Commands:

  render     [input] [args...]     - Render files or projects to various document types.                 
  preview    [file] [args...]      - Render and preview a document or website project.                   
  serve      [input]               - Serve a Shiny interactive document.                                 
  create     [type] [commands...]  - Create a Quarto project or extension                                
  use        <type> [target]       - Automate document or project setup tasks.                           
  add        <extension>           - Add an extension to this folder or project                          
  update     [target...]           - Updates an extension or global dependency.                          
  remove     [target...]           - Removes an extension.                                               
  convert    <input>               - Convert documents to alternate representations.                     
  pandoc     [args...]             - Run the version of Pandoc embedded within Quarto.                   
  typst      [args...]             - Run the version of Typst embedded within Quarto.                    
  run        [script] [args...]    - Run a TypeScript, R, Python, or Lua script.                         
  list       <type>                - Lists an extension or global dependency.                            
  install    [target...]           - Installs a global dependency (TinyTex or Chromium).                 
  uninstall  [tool]                - Removes an extension.                                               
  tools                            - Display the status of Quarto installed dependencies                 
  publish    [provider] [path]     - Publish a document or project to a provider.                        
  check      [target]              - Verify correct functioning of Quarto installation.                  
  call                             - Access functions of Quarto subsystems such as its rendering engines.
  help       [command]             - Show this help or the help of a sub-command.                        

Quarto

Multiplas saídas

  • Múltiplos formatos de saída: páginas web, PDFs, Word, sites, livros e mais

Quarto

Usos

  1. Comunicação com tomadores de decisão ou público mais amplo, com foco nas conclusões, não nos códigos das análises

  2. Colaboração com outros cientistas de dados, interessados tanto nas conclusões quanto nos códigos

  3. Ambiente para fazer ciência de dados, como um caderno de laboratório moderno, registro do que foi feito e dos pensamentos

Quarto

Funcionamento


Quarto

Funcionamento


Quarto

Projeto Quarto

Quarto

Arquivo Quarto (.qmd)

Quarto

Arquivo Quarto (.qmd)

Quarto

Arquivo Quarto (.qmd) - Source editor

Quarto

Arquivo Quarto (.qmd) - Visual editor

Quarto

Arquivo Quarto (.qmd) - Renderizar

Quarto

Arquivo Quarto (.qmd) - Anatomia






  • YAML (Yet Another Markup Language): cabeçalho (início do .qmd) onde são inseridas as configurações do documento (formatação, data, título, autor etc.), delimitado por --- e ---
  • Texto: usa markdown como sua sintaxe de documento principal
  • Códigos (chunks): blocos de códigos onde se insere códigos em R, Python, Julia e outros, delimitado por ```{r} e ```

Quarto

Arquivo Quarto (.qmd) - Anatomia




---
title: "Hello, Penguins"
format: html
execute:
  echo: false
---

## Meet the penguins

The __penguins__ data contains size measurements for 
penguins from three islands in the Palmer Archipelago, 
Antarctica.

The _three_ species of penguins have quite distinct 
distributions of physical dimensions (@fig-penguins).

# ```{r}
#| label: fig-penguins
#| fig-cap: "Dimensions of penguins across three species."
#| warning: false
library(tidyverse, quietly = TRUE)
library(palmerpenguins)
penguins |>
  ggplot(aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species)) +
  scale_color_manual(
    values = c("darkorange", "purple", "cyan4")) +
  theme_minimal()
# ```

Quarto

Arquivo Quarto (.qmd) - Anatomia


---
title: "Hello, Penguins"
format: html
execute:
  echo: false
---

## Meet the penguins

The __penguins__ data contains size measurements for 
penguins from three islands in the Palmer Archipelago, 
Antarctica.

The _three_ species of penguins have quite distinct 
distributions of physical dimensions (@fig-penguins).

#| label: fig-penguins
#| fig-cap: "Dimensions of penguins across three species."
#| warning: false
library(tidyverse, quietly = TRUE)
library(palmerpenguins)
penguins |>
  ggplot(aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species)) +
  scale_color_manual(
    values = c("darkorange", "purple", "cyan4")) +
  theme_minimal()

Quarto

Arquivo Quarto (.qmd) - YAML - Formato

HTML

---
title: "Título"
format: html
editor: visual
---

Word

---
title: "Título"
format: docx
editor: visual
---

PDF

Precisa instalar um pacote LaTeX

---
title: "Título"
format: pdf
editor: visual
---

Quarto

Arquivo Quarto (.qmd) - Texto - markdown

  • Markdown é um formato de texto simples projetado para ser fácil de escrever e, ainda mais importante, fácil de ler

  • Quarto é baseado no Pandoc e usa sua variação de markdown como sintaxe de documento

Quarto

Arquivo Quarto (.qmd) - Texto - markdown


### Text formatting
*italic* **bold** ~~strikeout~~ `code`
superscript^2^ subscript~2~
[underline]{.underline} [small caps]{.smallcaps}

### Lists
-   Bulleted list item 1
-   Item 2
    -   Item 2a
    -   Item 2b
1.  Numbered list item 1
2.  Item 2.

### Equations
inline math: $E = mc^{2}$


Text formatting

italic bold strikeout code

superscript2 subscript2

underline small caps

Lists

  • Bulleted list item 1
  • Item 2
    • Item 2a
    • Item 2b
  1. Numbered list item 1
  2. Item 2.

Equations

inline math: \(E = mc^{2}\)

Quarto

Arquivo Quarto (.qmd) - Código - chunk



The _three_ species of penguins have quite distinct 
distributions of physical dimensions (@fig-penguins).

````{r}
#| label: fig-penguins
#| fig-cap: "Dimensions of penguins across three species."
#| warning: false
library(tidyverse, quietly = TRUE)
library(palmerpenguins)
penguins |>
  ggplot(aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species)) +
  scale_color_manual(
    values = c("darkorange", "purple", "cyan4")) +
  theme_minimal()
````

Quarto

Arquivo Quarto (.qmd) - Código - chunk

Quarto

Galeria


Quarto

Quarto e GitHub

Podemos hospedar gratuitamente as saídas do Quarto de forma on-line no GitHub

Repositório > Settings > Pages > GitHub Pages

Shiny

Descrição

  • Framework do R para criar aplicações web interativas
  • Permite construir dashboards, painéis de visualização, e ferramentas analíticas
  • Totalmente integrado ao R (sem necessidade de HTML/CSS/JS)

Shiny

Exemplo

  • Disponibilização de redes de interação planta-dispersor na Mata Atlântica

Muito obrigado!