5  Produção de relatórios com Quarto

5.1 Introdução

No curso Introdução à análise de dados no R, utilizamos arquivos .R para escrever os códigos em R. Em scripts .R, todo o conteúdo é interpretado como código em R, exceto o que estava precedido de # (utilizado para comentários).

Por exemplo:

# Aula sobre ggplot2 -----

# Carregar pacotes
library(ggplot2)
library(palmerpenguins)

# Código que gera o gráfico
penguins |>
  ggplot() +
  aes(x = flipper_length_mm, y = body_mass_g) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange", "darkorchid", "cyan4")) +
  theme_minimal()

# ....

Essa forma de trabalhar é ótima para criar scripts de análise de dados, mas não é a melhor forma de criar relatórios que combinam texto, código e resultados.

5.2 Literate programming

O conceito de literate programming, ou programação letrada1, foi criado por Donald Knuth na década de 80. Esse conceito propõe a escrita de códigos intercalados com texto explicativo, de forma que o fluxo de raciocínio fique claro para leitores e colaboradores. A ideia central é que o código seja parte da comunicação, tornando o relatório um documento legível tanto para computadores quanto para humanos.

Com base nesse conceito, surgiram ferramentas que tornam possível criar relatórios reprodutíveis que combinam texto, código e resultados, como o R Markdown e, mais recentemente, o Quarto.

5.3 R Markdown

O R Markdown é um pacote em R que possibilita criar arquivos com códigos em R, resultados dos códigos, e textos explicativos. Esses arquivos tem extensão .Rmd.

Lançado em 20152, ele rapidamente se tornou uma das ferramentas mais populares para a criação de relatórios dinâmicos e reprodutíveis na comunidade R.

Exemplo de um arquivo .Rmd

O R Markdown possibilita exportar os arquivos em diversos formatos, como HTML, PDF, Word, apresentações, entre outros.

5.4 Quarto

Como citado anteriormente, o R Markdown é uma ferramenta muito boa para escrita técnica e científica reprodutível, mas, por ser um pacote em R, o seu uso acaba ficando limitado às pessoas que usam R.

Em 2022, a Posit (anteriormente chamada de RStudio) (mesma empresa responsável pelo RMarkdown) lançou o Quarto, uma nova ferramenta que permite a criação de documentos dinâmicos e reprodutíveis.

O Quarto é um sistema de escrita técnica e científica, de código aberto. Ele é uma evolução do R Markdown, mas não depende do R para funcionar. Isso significa que você pode usar o Quarto para escrever documentos com códigos em Python, R, Julia, Observable, entre outras linguagens, e exportar para diversos formatos, como PDF, HTML, Word, entre outros. Por exemplo: Você pode usar o VSCode como IDE, escrever um documento com código em Python e gerar o documento final. Tudo isso sem precisar ter o R e/ou RStudio instalados.

Arte por Allison Horst.

Arte por Allison Horst.
Nota

O Quarto foi lançado em 2022, e apresenta melhorias em relação ao R Markdown.

Nesta aula, vamos focar no Quarto, mas caso queira utilizar o RMarkdown, os principais conceitos são os mesmos.

5.4.1 Instalação do Quarto

Como dito anteriormente, o Quarto não é um pacote em R como o RMarkdown, e sim um software que podemos instalar em nosso computador.

Quando instalamos as versões mais recentes do RStudio IDE, o Quarto já vem instalado. Caso você não tenha o RStudio instalado, você pode instalar o Quarto de forma independente.

Para instalar ou atualizar o Quarto, acesse a página de instalação, faça o download do instalador referente ao seu sistema operacional (Windows, Mac OS, Linux) e faça a instalação.

5.4.1.1 Exercício

  1. Verifique se o Quarto está instalado no seu computador. Para isso, abra o RStudio e verifique se o botão “New File” apresenta a opção “Quarto Document”.

5.4.2 Criar um novo documento Quarto (.qmd)

Os arquivos Quarto tem extensão .qmd, e podem ser criados no RStudio clicando no botão “New File” e selecionando “Quarto Document”.

Criar um novo arquivo Quarto

Em seguida, o RStudio apresentará uma janela chamada “New Quarto Document” com algumas opções para criar um novo arquivo. Essas opções são passíveis de alteração posteriormente, então não precisamos nos preocupar muito com elas agora. Em resumo:

  • Title: Título do documento
  • Author: Nome de quem está criando o documento
  • Format: Formato do documento (HTML, PDF, Word). Vamos manter em HTML.
  • Engine: Knitr ou Jupyter. Vamos manter em Knitr.
  • Editor: Caixa para selecionar o editor visual. Por enquanto, vamos deixar desmarcado.

Para criar o documento, clique em “Create”:

New Quarto Document

O RStudio criará um arquivo .qmd com uma estrutura inicial:

Arquivo Quarto criado

5.4.2.1 Exercício

  1. Crie um arquivo com Quarto básico, adicionando o título “Meu primeiro relatório”, e no campo de autoria adicionando o seu nome. Mantenha selecionada a opção para exportar um arquivo HTML. Salve o arquivo como "aula-2.qmd" na pasta do projeto do curso, em "relatorios/".

5.4.3 Renderizar o arquivo

Podemos clicar no botão Render para que o arquivo seja renderizado (ou seja, o código fonte será transformado em um arquivo final HTML/Word/PDF/etc). É necessário salvar o arquivo antes de renderizar.

Na imagem a seguir, temos um exemplo de um arquivo em sua versão .qmd e a versão renderizada em HTML. Observe que o botão render foi destacado em vermelho, e que o arquivo renderizado foi aberto no painel Viewer do RStudio.

Exemplo: Arquivo .qmd e a versão renderizada em HTML

Caso você clique em render e não aconteça nada, você pode:

  1. Verificar se o RStudio está configurado para mostrar a versão preliminar (Preview) do documento no painel Viewer, clicando na engrenagem ao lado do botão Render e selecionando a opção “Preview in Viewer Pane”:

Opção Preview in Viewer Pane
  1. Verificar se o arquivo foi salvo na pasta do projeto.

Nos próximos tópicos, vamos explorar a estrutura de um arquivo Quarto e como adicionar conteúdos a ele.

5.4.3.1 Exercício

  1. Renderize o arquivo "aula-2.qmd" que você criou anteriormente. Verifique se o arquivo foi renderizado corretamente, se você consegue visualizar o conteúdo no painel Viewer do RStudio, e se o arquivo foi salvo na pasta do projeto.

5.4.4 Estrutura de um arquivo Quarto

Os arquivos Quarto tem extensão .qmd, e são divididos em três partes:

  • Metadados: Informações sobre o documento, como título, autor, formato, data, editor, entre outros. Essa parte é delimitada por --- no início e no final. É escrita em formato yaml, com a estrutura chave: valor. Nos metadados, a indentação (espaços entre o início da linha e o início do texto) é importante para o correto funcionamento do documento.

  • Campos de código (code chunks): Trechos de código (em R ou outra linguagem) que podem ser executados e exibidos no documento. Os campos de código podem ser criados utilizando a marcação ```{r} no início e ``` no final, ou utilizando o botão de criar novo chunk: .

  • Textos com marcação em Markdown: Textos explicativos, títulos, listas, tabelas, imagens, links, entre outros. A marcação é feita em Markdown, uma linguagem de marcação simples.

O que é Markdown?

Markdown é uma linguagem de marcação simples que permite escrever textos com formatação básica, como títulos, listas, links, imagens, entre outros. A ideia é que o texto seja legível mesmo sem a formatação, e que a marcação seja simples e intuitiva.

O arquivo abaixo é um exemplo de um arquivo Quarto:

---
title: "Título do documento"
format: html
---

# Título 1

Este é um texto de exemplo.

```{r}
# este é um campo de código em R
1 + 1
```
1
Metadados
2
Texto com marcação em Markdown
3
Campo de código

5.4.4.1 Exercício

  1. Vamos começar a adicionar um pouco de conteúdo no arquivo "aula-2.qmd" criado anteriormente. Adicione:

  • Um campo de código, onde o pacote tidyverse seja carregado.

  • Um campo de código, com o código para criar um gráfico simples com o pacote ggplot2. Caso você não tenha um código em mente, você pode utilizar o código abaixo:

library(palmerpenguins)
penguins |>
  ggplot() +
  aes(x = flipper_length_mm, y = body_mass_g) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange", "darkorchid", "cyan4")) +
  theme_minimal()
  • Um parágrafo simples de texto, descrevendo o que foi feito.
  1. Salve o arquivo e renderize-o. Verifique se o conteúdo foi renderizado corretamente.

5.4.5 Editor Source e Visual

Ao utilizar documentos Quarto, podemos escolher entre dois modos de edição: Source (código fonte) e Visual.

  • Editor Source: Modo de edição de código, onde podemos ver e editar o código fonte do documento. É o modo padrão.

  • Editor Visual: Modo de edição visual, onde podemos ver uma prévia do documento como um todo, com o texto formatado e uma barra de ferramentas. É importante perceber que quando alteramos o documento no editor visual, o código fonte é atualizado automaticamente. Saiba mais sobre o Editor Visual.

Barra de ferramentas do editor visual

A seguir, temos um exemplo de um documento Quarto no modo Source e Visual:

Editor Source

Editor Visual

Para alterar entre os modos de edição, escolha a opção desejada nos botões no canto superior direito do documento:

Alterar entre modo Source e Visual

O editor Visual tem várias opções para facilitar a formação do texto com Markdown e inserir outros tipos de conteúdo (como por exemplo: notas de rodapé, citações, imagens, links, tabelas simples, expressões matemáticas com LaTeX, entre outros):

Opções do editor Visual. Fonte: documentação do Quarto.

Opções do editor Visual. Fonte: documentação do Quarto.

Caso queira que o RStudio sempre abra o documento no editor de preferência, você pode adicionar essa informação nos metadados do documento, utilizando editor: seguido de source ou visual. Por exemplo:

---
editor: source
---
---
editor: visual
---

5.4.5.1 Exercício

  1. Explore as opções do editor Visual, adicionando um pouco de formatação ao texto do arquivo "aula-2.qmd". Tente adicionar pelo menos um título, uma lista, e um link.

  2. Altere entre os modos Source e Visual. Veja a diferença entre o código fonte e a visualização do documento.

  3. Entre os modos Source e Visual, qual você prefere para escrever documentos? Por quê?

5.4.6 Adicionando conteúdos com código

Nota

Existem vários tipos de conteúdo que podem ser adicionados a um documento Quarto, como texto, código, gráficos, tabelas, imagens, links, entre outros.

O melhor lugar para aprender sobre esses conteúdos é a documentação do Quarto, que é muito completa e bem organizada.

Vamos explorar alguns tipos de conteúdos que podem ser adicionados a um documento Quarto que sejam resultados de códigos em R.

Como citado anteriormente, podemos adicionar código em R em campos de código, ou code chunks. Dentro de um campo de código, podemos adicionar comentários, códigos em R, e os resultados dos códigos serão exibidos logo em seguida no documento.

Para adicionar um campo de código, utilizamos a marcação ```{r} no início e ``` no final. Por exemplo:

```{r}
# Exemplo: somando 1 + 1
1 + 1
```
[1] 2

A partir de agora, vamos omitir a marcação de iniciar e finalizar os campos de código, porém saiba que é necessário adicionar essas marcações para que o código seja executado. Por exemplo, o código acima seria apresentado desta forma:

# Exemplo: somando 1 + 1
1 + 1
[1] 2

5.4.6.1 Adicionando gráficos

Para adicionar um gráfico, podemos criar um campo de código e adicionar o código que gera o gráfico (igual ao utilizando em scripts .R).

Os gráficos gerados a partir de um campo de código são exibidos logo após o código.

Por exemplo:

# Carregar os pacotes
library(tidyverse)
library(palmerpenguins)

# exemplo de código
penguins |>
  ggplot() +
  aes(x = flipper_length_mm, y = body_mass_g) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange", "darkorchid", "cyan4")) +
  labs(
    x = "Comprimento da nadadeira (mm)",
    y = "Massa corporal (g)",
    color = "Espécie",
    shape = "Espécie",
    title = "Relação entre comprimento da nadadeira e massa corporal",
    subtitle = "Pinguins das espécies Adelie, Chinstrap e Gentoo",
    caption = "Fonte: Pacote palmerpenguins."
  ) +
  theme_minimal()

5.4.6.2 Adicionando tabelas

Para adicionar tabelas (que sejam geradas com código), não basta apenas adicionar o código que gera a tabela. Veja o que acontece se tentarmos adicionar uma tabela com o código abaixo:

pinguins_frequencia <- penguins |> 
  count(species, island, sort = TRUE)

pinguins_frequencia
# A tibble: 5 × 3
  species   island        n
  <fct>     <fct>     <int>
1 Gentoo    Biscoe      124
2 Chinstrap Dream        68
3 Adelie    Dream        56
4 Adelie    Torgersen    52
5 Adelie    Biscoe       44

Observe que o resultado que apareceu no relatório é igual ao que apareceria no console do R.

Para que a tabela seja exibida de forma mais amigável, podemos utilizar alguma função de tabela para gerar tabelas. Existem diversas funções (de diferentes pacotes em R) que possibilitam a criação de tabelas. A função knitr::kable() é muito utilizada, e permite criar tabelas simples a partir de um data frame.

Por exemplo, podemos utilizar o knitr::kable() para exibir a tabela criada:

pinguins_frequencia |> 
  knitr::kable()
species island n
Gentoo Biscoe 124
Chinstrap Dream 68
Adelie Dream 56
Adelie Torgersen 52
Adelie Biscoe 44

Podemos explorar os argumentos da função para personalizar a tabela, como adicionar nomes de colunas, entre outros. Por exemplo:

pinguins_frequencia |> 
  knitr::kable(col.names = c("Espécie", "Ilha", "Quantidade"))
Espécie Ilha Quantidade
Gentoo Biscoe 124
Chinstrap Dream 68
Adelie Dream 56
Adelie Torgersen 52
Adelie Biscoe 44
Dica

Além da função knitr::kable(), existem outras funções que podem ser utilizadas para criar tabelas. Abaixo listamos alguns pacotes que possuem funções para criar tabelas, e podem ser explorados posteriormente:

  • kableExtra: este pacote apresenta funções para personalizar tabelas criadas com knitr::kable(), porém o seu funcionamento é focado em tabelas em HTML e PDF (com LaTeX). Se o seu objetivo é gerar documentos em word, não utilize o kableExtra.

  • flextable: este pacote é focado em criar tabelas para documentos em Word, e permite maior personalização. Para aprender a utilizar o flextable, consulte a documentação do pacote e o guia de usuário (flextable book).

  • reactable: este pacote é focado em criar tabelas interativas em HTML, e permite adicionar filtros, ordenação, entre outros. Para aprender a utilizar o reactable, consulte a documentação do pacote.

  • gt: este pacote foi criado pela equipe da RStudio/Posit, e tenta utilizar uma filosofia similar ao ggplot2 (a gramática dos gráficos), porém com tabelas (gt sendo gramática de tabelas). O gt tem funções para as diferentes partes da tabela: cabeçalho, corpo, rodapé, entre outros. Para aprender a utilizar o gt, consulte a documentação do pacote. Curiosidade: em 2023 a mesma equipe lançou a biblioteca gt para Python.

5.4.6.2.1 Exercício

  1. No arquivo "aula-2.qmd", crie um campo de código com uma tabela de frequência de pinguins por espécie e sexo, utilizando a base de dados penguins. Salve essa tabela de frequência em um objeto chamado pinguins_freq_especie_sexo.

  2. Utilizando o objeto criado, apresente essa tabela formatada com a função knitr::kable().

  3. Experimente adicionar outra tabela utilizando alguma função de tabela de outro pacote citado como extra, como flextable::flextable(), reactable::reactable(), ou gt::gt().

5.4.6.3 Adicionar código em linha (inline code)

Até agora, exploramos como adicionar conteúdos com código dentro de um campo de código. Mas e se quisermos adicionar um resultado de um código em um texto?

Não é interessante adicionar manualmente conteúdos que podem ser gerados com código, pois isso pode tornar o documento menos reprodutível. Principalmente se os dados podem ser atualizados com o tempo!

Para adicionar um resultado de um código em um texto, podemos utilizar o que chamamos de código em linha, ou inline code. Para isso, utilizamos a seguinte sintaxe:

Por exemplo, o texto abaixo apresenta conteúdos feitos com campos de código:

A base de dados penguins apresenta pinguins de três espécies: Adelie, Gentoo, Chinstrap. A base possui 344 observações e 8 (sendo que cada observação corresponde a um pinguim) variáveis: species, island, bill_length_mm, bill_depth_mm, flipper_length_mm, body_mass_g, sex, year. A coleta de dados foi feita em três ilhas: Torgersen, Biscoe, Dream, entre os anos de 2007 e 2009.

Você consegue identificar onde foram utilizados os códigos em linha?

Os conteúdos em destaque foram feitos com códigos em linha:

A base de dados penguins apresenta pinguins de três espécies: Adelie, Gentoo, Chinstrap. A base possui 344 observações e 8 (sendo que cada observação corresponde a um pinguim) variáveis: species, island, bill_length_mm, bill_depth_mm, flipper_length_mm, body_mass_g, sex, year. A coleta de dados foi feita em três ilhas: Torgersen, Biscoe, Dream, entre os anos de 2007 e 2009.

Dicas para adicionar conteúdos com código em linha:

  • Se você vai escrever algo no texto que pode ser gerado com código, experimente utilizar o código em linha.

  • A base de dados que você está utilizando pode ser atualizada futuramente? Se sim, busque adicionar conteúdos com códigos em linha.

  • Caso algum conteúdo que você quer adicionar com código de linha dependa de um código “grande” (mais de uma linha), é interessante criar um campo de código, salvar o resultado em um objeto, e utilizar o código em linha para chamar o objeto.

5.4.6.3.1 Exercícios
  1. Ainda no arquivo "aula-2.qmd": utilizando a base de dados pnud_min do pacote abjData, escreva uma breve descrição da base de dados, utilizando códigos em linha. Ideias de conteúdos: número de observações, número de variáveis, variáveis presentes na base, quais são os anos presentes na base, quais são os municípios com o menor e maior indicador de IDH municipal para o ano mais recente, entre outros.

Caso não conheça o pacote abjData, você pode carregar a base de dados com o código abaixo:

# install.packages("abjData") # executar caso não tenha o abjData instalado
library(abjData)
pnud_min
# A tibble: 16,686 × 15
   ano   muni_id muni_nm   uf_sigla regiao_nm  idhm idhm_e idhm_l idhm_r espvida
   <chr> <chr>   <chr>     <chr>    <chr>     <dbl>  <dbl>  <dbl>  <dbl>   <dbl>
 1 1991  1100015 ALTA FLO… RO       Norte     0.329  0.112  0.617  0.516    62.0
 2 1991  1100023 ARIQUEMES RO       Norte     0.432  0.199  0.684  0.593    66.0
 3 1991  1100031 CABIXI    RO       Norte     0.309  0.108  0.636  0.43     63.2
 4 1991  1100049 CACOAL    RO       Norte     0.407  0.171  0.667  0.593    65.0
 5 1991  1100056 CEREJEIR… RO       Norte     0.386  0.167  0.629  0.547    62.7
 6 1991  1100064 COLORADO… RO       Norte     0.376  0.151  0.658  0.536    64.5
 7 1991  1100072 CORUMBIA… RO       Norte     0.203  0.039  0.572  0.373    59.3
 8 1991  1100080 COSTA MA… RO       Norte     0.425  0.22   0.629  0.553    62.8
 9 1991  1100098 ESPIGÃO … RO       Norte     0.388  0.159  0.653  0.561    64.2
10 1991  1100106 GUAJARÁ-… RO       Norte     0.468  0.247  0.662  0.625    64.7
# ℹ 16,676 more rows
# ℹ 5 more variables: rdpc <dbl>, gini <dbl>, pop <int>, lat <dbl>, lon <dbl>

5.4.7 Opções de campos de código (chunk options)

Os campos de código, ou code chunks, são trechos de código que podem ser executados em documentos Quarto. Eles oferecem diversas opções para personalizar a execução e a exibição do código e dos resultados. Essas opções permitem configurar como o código aparece no relatório, como ele é executado e como os resultados são apresentados.

As opções devem ser apresentadas na linha após o início do campo de código, precedido de #|, no formato nome_opcao: valor. Por exemplo:

```{r}
#| nome_opcao: valor

# código em R aqui
1 + 1
```

Existem muitas opções de campos de código, e estão listadas na documentação do Quarto. Neste momento, vamos explorar algumas das principais opções!

5.4.7.1 Exibir ou ocultar o código

A opção echo: define se o código será exibido (ou não) no relatório. Por padrão, o código é exibido. Para ocultar o código, podemos adicionar echo: false no campo de código.

5.4.7.2 Executar ou não o código

A opção eval: define se o código será executado (ou não) no relatório. Por padrão, o código é executado. Para não executar o código, podemos adicionar eval: false no campo de código.

5.4.7.3 Mensagens (messages) e avisos (warnings)

Ao executar um campo de código, mensagens e avisos podem ser gerados. Podemos controlar se essas mensagens e avisos serão exibidos no relatório com as opções messages: e warnings:. Por padrão, ambos são exibidos. Para ocultar as mensagens, podemos adicionar messages: false no campo de código. Para ocultar os avisos, podemos adicionar warnings: false.

5.4.8 Tipos de formatos para exportar

O Quarto permite exportar os documentos em diversos formatos, como HTML, PDF, Word, entre outros. Para definir o formato de saída, podemos adicionar um campo format nos metadados do documento. Por exemplo:

  • HTML:
---
format: html
---
  • Word:
---
format: docx
---
---
format: pdf
---
  • Apresentação em HTML:
---
format: revealjs
---

Essas são as opções de formatos mais utilizadas. Para ver a lista completa, consulte a documentação do Quarto.

5.4.9 Projetos em Quarto

Em breve

5.4.10 Quarto CLI

Em breve

5.4.11 Extensões

Em breve

  1. https://www.ime.usp.br/~pf/CWEB/lit-prog.html↩︎

  2. Curiosidade: o criador do pacote R Markdown, Yihui Xie, fez uma apresentação sobre a história do R Markdown no R-Day Brasil em 2021.↩︎