28  Quarto

28.1 Introdução

O Quarto fornece uma estrutura (framework) unificada para autoria em ciência de dados, combinando seu código, seus resultados e seu texto. Documentos Quarto são plenamente reprodutíveis e suportam muitos formatos de saída como PDF, arquivos Word, apresentações e mais.

Arquivos Quarto foram projetados para serem usados de três maneiras:

1. Para se comunicar com pessoas tomadoras de decisão, que querem focar nas conclusões e não no código por trás da análise.

2. Para colaborar com outras pessoas cientistas de dados (incluindo você no futuro!) que estejam interessadas tanto em suas conclusões quanto em como você as alcançou (isto é, o código).

3. Como um ambiente em que se faz ciência de dados, como um caderno (notebook) de laboratório moderno em que se pode capturar não apenas o que você fez, como também o que você estava pensando.

Quarto é uma feerramenta de linha de comando, não é um pacote do R. Isso significa que ajuda, via de regra, não está disponível via ?. Em vez disso, enquanto você trabalhar neste capítulo e usar o Quarto no futuro, você deve procurar a documentação para Quarto.

Se você for uma pessoa que usa R Markdown, você deve estar pensando “Quarto parece muito com R Markdown”. Isso não está errado! Quarto une a funcionalidade de muitos pacotes do ecosistema do R Markdown (rmarkdown, bookdown, distill, xaringan, etc.) em um sistema único e consistente, mas também extende o ecosistema com apoio nativo para múltiplas linguagens de programação como Python e Julia, além do próprio R. De certa forma, o Quarto reflete tudo que foi aprendido na expansão e no suporte ao ecossistema do R Markdown em uma década.

28.1.1 Pré-requisitos

Você precisa da interface de linha de comando do Quarto (Quarto CLI – command line interface), mas não é necessário instalá-la ou carregá-la explicitamente. Seu RStudio o fará automaticamente quando for necessário.

28.2 Básico de Quarto

Isso é um arquivo Quarto – um arquivo de texto simples que possui a extensão .qmd:

---
title: "Tamanhos de diamante"
date: 2022-09-12
format: html
---

```{r}
#| label: setup
#| include: false

library(tidyverse)
library(dados)

menores <- diamante |> 
  filter(quilate <= 2.5)
```

Temos dados sobre `r nrow(diamante)` diamantes. 
Apenas `r nrow(diamante) - nrow(menores)` são maiores que 2.5 quilates. 
A distribuição dos demais é exibida a seguir:

```{r}
#| label: grafico-diamantes-menores
#| echo: false

menores |> 
  ggplot(aes(x = quilate)) + 
  geom_freqpoly(binwidth = 0.01)
```

O arquivo contém três tipos importantes de conteúdo:

1. Um cabeçalho YAML (opcional) envolto por ---.
2. Blocos (ou chunks) de código R envoltos por ```.
3. Texto misturado com formatação simples de texto como # título/subtítulo e _itálico_.

Figura 28.1 mostra um documento .qmd no RStudio com interface de notebook, no qual código e saída são intercalados. Você pode executar cada bloco de código clicando no ícone Executar – Run (triângulo verde que parece com o botão de play no canto superior direito do bloco de código), ou pressionando Cmd/Ctrl + Shift + Enter. O RStudio executará o código e mostrará os resultados juntamente com o código.

Figura 28.1: Um documento Quarto no RStudio. Código e saída intercalados no documento, com a saída do gráfico aparecendo logo abaixo do código.

Se você não gosta de ver seus gráficos e saída dos códigos no documento e prefere usar os painéis do console e gráfico (aba plot), é possível clicar no ícone de engrenagem próximo ao botão “Render” e selecionar “Chunk Output in Console” (ou seja, mostrar resultados do chunk no console), conforme mostrado em Figura 28.2.

Figura 28.2: Um documento Quarto no RStudio com a saída de gráfico no painel Plots.

Para produzir um relatório completo contendo todo o texto, código e resultados, clique em “Render” or pressione Cmd/Ctrl + Shift + K. Você também pode fazer isso programaticamente, em linha de código, com quarto::quarto_render("diamond-sizes.qmd"). Isso exibirá o relatório no painel de visualização, como exibido em Figura 28.3, e criará um arquivo HTML.

Figura 28.3: Um documento Quarto no RStudio com o documento renderizado no painel Viewer.

Quando se gera ou renderiza o documento, Quarto envia o arquivo .qmd para o knitr, https://yihui.org/knitr/, que executa todos os blocos de código e cria um novo arquivo markdown (.md) que inclui o código e seus resultados. O arquivo markdown gerado pelo knitr é então processado pelo pandoc, https://pandoc.org, que é responsável por criar a versão final do arquivo. Esse processo é ilustrado em Figura 28.4. A vantagem desse fluxo de trabalho em duas etapas é que é possível criar uma ampla variedade de formatos de arquivo, como você verá em Capítulo 29.

Figura 28.4: Diagrama do fluxo de trabalho Quarto de qmd a knitr, md, pandoc para saída nos formatos PDF, MS Word ou HTML.

Para iniciar seu próprio arquivo .qmd, selecione File > New File > Quarto Document… na barra de menu. O RStudio abrirá uma janela em que você poderá preencher informações para preencher seu arquivo com conteúdos úteis que lembra como os principais recursos do Quarto funcionam.

As seções a seguir aprofundam os três componentes de um documento Quarto em mais detalhes: o texto em markdown, os blocos de código e o cabeçalho YAML.

28.2.1 Exercícios

1. Crie um novo documento Quarto usando File > New File > Quarto Document. Leia as instruções. Pratique a execução dos blocos de código individualmente. Depois, renderize o documento clicando no botão designado e depois usando o atalho do teclado. Verifique se consegue alterar o código, rodá-lo novamente e ver o novo documento modificado.

2. Crie um novo documento Quarto para cada um dos três formatos disponibilizados: HTML, PDF e Word. Renderize cada um dos três documentos. Qual é a diferença entre as saídas (outputs)? Qual é a diferença entre as entradas (inputs)? (É possível que seja necessário instalar o LaTeX para construir o arquivo PDF — O RStudio avisará se isso for necessário.)

28.3 Editor Visual

O editor Visual no RStudio utiliza uma interface WYSIWYM para autoria de documentos Quarto. Por trás das cortinas, os textos em documentos Quarto (arquivos .qmd) são escritos em Markdown, um conjunto leve de convenções para formatação de arquivos de texto simples. Na verdade, o Quarto usa o markdown do Pandoc (uma versão um pouco extendida de Markdown que é interpretável pelo Quarto), incluindo tabelas, citações, referências cruzadas, notas de rodapé, divs/spans, listas de definição, atributos, HTML/TeX crus, entre outros, assim como suporta execução de células de código e a visualização de seus resultados em linha. Enquanto Markdown é desenhado para ser simples de ler e de escrever, como você verá em Seção 28.4, ainda é necessário aprender uma nova sintaxe. Assim, se documentos computacionais como arquivos .qmd são novos para você, mas você tem experiência com Google Docs ou MS Word, o jeito mais fácil de começar a usar Quarto no RStudio é pelo editor visual.

No editor visual, você pode tanto usar botões na barra de menu para inserir imagens, tabelas, referências cruzadas, etc. quanto usar o atalho geral ⌘ / para inserir qualquer coisa. Se você estiver no começo de uma linha (como ilustrado em Figura 28.5), você pode apenas digitar / para usar o atalho.

Figura 28.5: Editor visual Quarto.

Inserir e personalizar como os conteúdos são exibidos também é mais fácil com o uso do editor visual. Você pode colar uma imagem diretamente da sua área de transferência no editor visual (e o RStudio colocará uma cópia daquela imagem no diretório do projeto e montarará um link para ela) ou usar o menu Insert > Figure / Image do editor visual para navegar até a imagem desejada para inserir ou colar sua URL. Além disso, usando o mesmo menu você pode redimensionar a imagem e adicionar uma legenda, texto alternativo e um link.

O editor visual tem muito mais recursos que não enumeramos aqui que podem ser úteis a você na medida em que você ganha experiência em escrever com a ferramenta.

Mais importante, enquanto o editor visual exibe o conteúdo do documento com formatação, por trás ele salva o conteúdo em Markdown, permitindo transitar entre o editor visual e de código (source) para visualizar e editar o documento usando qualquer uma das ferramentas.

28.3.1 Exercícios

1. Crie novamente o documento em Figura 28.5 usando o editor visual.
2. Usando o editor visual, insira um bloco de código usando o menu Insert e depois faça o mesmo usando qualquer ferramenta.
3. Usando o editor visual, descubra como:
   1. Adicionar uma nota de rodapé.
   2. Adicionar uma linha horizontal.
   3. Adicionar um bloco de citação.
4. Usando o editor visual, vá em Insert > Citation e insira a citação para o artigo cujo título é Welcome to the Tidyverse usando o DOI (digital object identifier), que é 10.21105/joss.01686. Renderize o documento e observe como a referência aparece no documento. Que alteração você consegue identificar no YAML do seu documento?

28.4 Editor Source

Também é possível editar documentos Quarto usando o editor Source no RStudio, sem a assistência do editor visual. Enquanto o editor Visual será familiar para aqueles com experiência em escrita com ferramentas como Google docs, o editor Source será familia para aqueles com experiência escrevendo scripts R ou documentos R Markdown. O editor Source também pode ser útil para procurar erros (debugging) de sintaxe Quarto, já que muitas vezes é mais fácil achar esses erros em texto simples.

O guia abaixo mostra como usar o Markdown do Pandoc para escrever documentos Quarto em seu editor fonte.

## Formatação de texto

*itálico* **negrito** ~~taxado~~ `código`

sobrescrito^2^ subscrito~2~

[sublinhado]{.sublinhado} [small caps]{.smallcaps}

## Títulos

# Título Nível 1

## Título Nível 2

### Título Nível 3

## Listas

-   Item de lista não enumerada 1

-   Item 2

    -   Item 2a

    -   Item 2b

1.  Item de lista enumerada 1

2.  Item 2.
    Os números são incrementados automaticamente na saída.

## Links e imagens

<http://example.com>

[frase com link](http://example.com)

![texto de legenda opcional](quarto.png){fig-alt="Logomarca Quarto com a palavra quarto escrita em letras minúsculas"}

## Tabelas

| Primeiro título    | Segundo título     |
|--------------------|--------------------|
| Célula de conteúdo | Célula de conteúdo |
| Célula de conteúdo | Célula de conteúdo |

A melhor forma de aprender essas coisas é simplesmente tentar. Isso levará alguns dias, mas em pouco tempo se tornam algo automático e não será necessário pensar tanto sobre elas. Se você se esquecer, pode buscar uma boa folha de referência em Help > Markdown Quick Reference.

28.4.1 Exercícios

1. Pratique o que você aprendeu criando um currículo (CV) breve. O título deve ser o seu nome e você deve incluir cabeçalhos para pelo menos sua educação ou trabalho. Cada uma das seções deve incluir uma lista em tópicos de trabalhos/títulos. Destaque o ano em negrito.

2. Usando o editor source e a referência rápida para Markdown, descubra como:

   1. Adicionar uma nota de rodapé.
   2. Adicionar uma linha horizontal.
   3. Adicionar um bloco de citação.

3. Copie e cole o conteúdo de diamond-sizes.qmd a partir de https://github.com/cienciadedatos/pt-r4ds/tree/main/quarto para um arquivo R Quarto local. Verifique se você consegue executá-lo, então adicione texto depois do polígono de frequências que descreve suas características mais chamativas.

4. Crie um documento em Google doc ou MS Word (ou use um documento que você tenha criado previamente) que contenha títulos, hiperlinks, texto formatado, etc. Copie os conteúdos desse documento e cole-os em um documento quarto no editor visual. Em seguida, troque para o editor source e inspecione o código fonte.

28.5 Blocos de Código

Para executar código em um documento Quarto, é necessário incluir um bloco de código. Há três maneiras de fazer isso:

1. O atalho de teclado Cmd + Option + I / Ctrl + Alt + I.

2. O botão “Insert” na barra de ferramentas do editor.

3. Escrevendo manualmente os limitadores de bloco ```{r} e ```.

Recomendamos que você aprenda o atalho de teclado. Isso economizará muito tempo no longo prazo!

É possível prosseguir para a execução do código usando o atalho que agora (temos fé!) que você conhece e ama:Cmd/Ctrl + Enter. No entanto, blocos de código recebem um novo atalho: Cmd/Ctrl + Shift + Enter, que executa todo o código no bloco. Pense no bloco de código como uma função. Um bloco de código deve ser relativamente autocontido, focado em realizar uma única tarefa.

As seções a seguir descrevem o cabeçalho do bloco de código, que consiste em ```{r}, seguido de um rótulo opcional e diversas outras opções de bloco, cada uma em sua própria linha, marcada por #|.

28.5.1 Rótulo do bloco de código

Blocos de código podem receber um rótulo opcional, por exemplo

```{r}
#| label: adicao-simples

1 + 1
```

#> [1] 2

Há três vantagens nisso:

1. É possível navegar mais facilmente para blocos de código específicos usando o navegador em lista no canto inferior esquerdo do editor do script:

2. Gráficos produzidos pelos blocos de código terão nomes úteis para reutilizá-los em outros lugares. Mais sobre isso em Seção 28.6.

3. É possível organizar redes de bloco de código em cache para evitar múltiplas execuções de computações caras em toda execução. Mais sobre isso em Seção 28.8.

Os rótulos dos seus blocos de código devem ser curtos, mas evocativos e não devem conter espaços. Recomendamos o uso de traços (-) para separar palavras (em vez de sublinhados, _) e evitar o uso de outros caracteres especiais nos rótulos de código.

Em geral, você é livre para rotular o bloco de código como quiser, mas há um bloco cujo nome indica um coportamento especial: setup. Quando você está no modo notebook, o bloco de código com nome setup será executado automaticamente uma vez antes que todo o seu código seja executado.

Além disso, rótulos não podem ser duplicados. Cada rótulo de bloco de código deve ser único.

28.5.2 Opções de bloco de código (chunk options)

Saídas de blocos de código podem ser personalizadas com campos de opções (options) fornecidos para o cabeçalho do bloco. Quase 60 opções para personalização dos seus blocos de código são fornecidas pelo Knitr. Aqui cobriremos as opções mais importantes, que você utilizará com frequência. É possível verificar a lista completa em https://yihui.org/knitr/options.

O conjunto mais importante de opções controla se seu código será executado e que resultados serão exibidos no relatório final:

• eval: false previne o código de ser avaliado. (E obviamente, se o código não é executado, nenhum resultado será gerado). Isso é útil para exibir um código de exemplo ou para desabilitar um grande bloco de código sem comentar cada uma de suas linhas.

• include: false executa o código, mas não o mostra nem inclui seus resultados no documento final. Use isso para códigos de configurações cujos resultados você não quer que dêem uma aparência de desordem no seu relatório.

• echo: false evita o código mas permite a exibição dos resultados no arquivo finalizado. Use isso quando estiver escrevendo relatórios direcionados a pessoas que não querem ver o código por trás dos resultados.

• message: false ou warning: false previne o aparecimento de mensagens ou avisos no arquivo final.

• results: hide esconde os resultados; fig-show: hide esconde gráficos.

• error: true permite que a renderização do seu documento continue mesmo que ocorra um erro. Você raramente precisará incluir isso na versão final do seu relatório, mas pode ser útil se você precisa corrigir um erro específico dentro do seu .qmd. Também é útil se você está ensinando R e quer incluir um erro deliberadamente. O padrão, error: false impede a renderização caso exista qualquer erro no documento.

Cada uma dessas opções de bloco de código é adicionada ao cabeçalho do bloco, seguindo #|, por exemplo, no bloco a seguir o resultado não é impresso, já que eval está marcado como false.

```{r}
#| label: multiplicacao-simples
#| eval: false

2 * 2
```

A tabela a seguir resume que tipos de saída cada opção suprime:

Opção	Executa código	Mostra código	Resultados	Gráficos	Mensagens	Avisos
eval: false	X		X	X	X	X
include: false		X	X	X	X	X
echo: false		X
results: hide			X
fig-show: hide				X
message: false					X
warning: false						X

28.5.3 Opções Globais

Na medida em que você trabalhar mais com o knitr, você descobrirá que algumas das opções padrão dos blocos não satisfazem a sua necessidade e será preciso alterá-las.

É possível fazer isso adicionando suas opções preferidas no YAML do documento em execute. Por exemplo, se você estiver preparando um relatório para uma audiência que não precisa ver seu código, mas apenas seus resultados e narrativa, pode ser que seja desejável configurar echo: false no nível do documento. Isso esconderá o código por padrão e só exibirá blocos de código que você escolha mostrar ( com echo: true). Você pode configurar message: false e warning: false, mas isso tornará difícil a resolução de problemas de execução porque nenhuma das mensagens serão exibidas no final do documento.

title: "My report"
execute:
  echo: false

Como o Quarto foi desenhado para ser multi-línguas (funciona com R mas também com outras linguagens como Python, Julia, etc.), nem todas as opções do knitr estão disponíveis no nível de documento. Algumas das opções funcionam com knitr mas não com outros motores (engines) que o Quarto usa para executar código em outras linguagens (por exemplo, Jupyter). No entanto é possível ajustar essas como opções globais para o seu documento dentro do campo knitr em opts_chunk. Por exemplo, quando escrevemos livros ou tutoriais, configuramos:

title: "Tutorial"
knitr:
  opts_chunk:
    comment: "#>"
    collapse: true

Isso faz com que nossa formatação para comentários preferida seja usada e garante que o código e seu resultado sejam exibidos próximos um do outro.

28.5.4 Código em linha

Existe outra maneira de inserir código R em um documento Quarto: diretamente no texto com `r `. Isso pode ser muito útil se você for citar propriedades dos seus dados no texto. Por exemplo, o documento modelo usado no começo do capítulo tinha:

Temos dados sobre `r nrow(diamonds)` diamantes. Apenas `r nrow(diamonds) - nrow(smaller)` são maiores que 2.5 quilates. A distribuição dos restantes é exibida abaixo:

Quando o relatório é renderizado, os resultados dessas computações são inseridas no texto:

Temos dados sobre 53940 diamantes. Apenas 126 são maiores que 2.5 quilates. A distribuição dos restantes é exibida abaixo:

Ao inserir números no texto, format() é seu amigo. A função permite configurar o número de digits (casas decimais) para que você não imprima o número com um grau de precisão que chega a ser ridículo e big.mark para facilitar a leitura dos números. Você pode combiná-las em uma função auxiliar:

comma <- function(x) format(x, digits = 2, big.mark = ",")
comma(3452345)
#> [1] "3,452,345"
comma(.12358124331)
#> [1] "0.12"

28.5.5 Exercícios

1. Adicione uma seção que explore como o tamanho de diamantes varia de acordo com corte, cor e transparência. Considere que você está escrevendo um relatório para alguém que não sabe R e em vez de usar echo: false em cada bloco, configure como uma opção global.

2. Faça o download de diamond-sizes.qmd de https://github.com/hadley/r4ds/tree/main/quarto. Adicione uma seção que descreva os 20 maiores diamantes, incluindo uma tabela que mostre seus atributos mais importantes.

3. Modifique diamonds-sizes.qmd para usar label_comma() e produzir um resultado bem formatado. Inclua também a percentagem de diamantes que são maiores que 2.5 quilates.

28.6 Figuras

As figuras em um documento Quarto podem ser integradas (como um arquivo PNG ou JPEG) ou geradas como resultado de um bloco de código.

Para integrar uma imagem a partir de um arquivo externo, é possível usar o menu Insert no editor Visual no RStudio e selecionar Figure / Image. Isso abrirá um menu em que é possível buscar a imagem que você deseja inserir, assim como adicionar um texto alternativo ou legenda e ajustar seu tamanho.

No editor visual também é possível simplesmente colar uma imagem da sua área de transferência no documento, então o RStudio inserirá uma cópia daquela imagem na pasta do seu projeto.

Se você incluir um bloco de código que gera uma figura (como uma chamada a ggplot()), a imagem resultante será automaticamente incluída no seu documento Quarto.

28.6.1 Tamanho de figura

O maior desafio ao trabalhar com imagens no Quarto é fazer com que elas fiquem do tamanho e no formato corretos. Há cinco opções principais que controlam o tamanho da figura: fig-width, fig-height, fig-asp, out-width e out-height. Ajustar o tamanho é desafiador porque há dois tamanhos (aquele da figura criada pelo R e aquele que é inserido no documento final) e múltiplas formas de especificar tamanho (isto é, altura, largura e aspect ratio - proporcional: escolha dois dos três).

Recomendamos três das cinco opções:

• Gráficos tendem a ser esteticamente mais agradáveis se têm largura consistente. Para garantir isso, configure fig-width: 6 (6 polegadas) e fig-asp: 0.618 (a razão áurea) nas definições padrão. Nos blocos individuais, ajuste apenas fig-asp.

• Controle o tamanho da saída com out-width e configure como uma percentagem da largura do corpo do documento. Sugerimos out-width: "70%" e fig-align: center.

  Isso dá espaço para os gráficos respirarem, sem tomar espaço demais.

• Para inserir múltiplos gráficos na mesma linha, configure layout-ncol em 2 para dois gráficos, 3 para três gráficos, etc. Isso efetivamente ajusta out-width para “50%” para cada gráfico se layout-ncol for 2, “33%” se layout-ncol for 3, etc. Dependendo do que você está tentando ilustrar (por exemplo, mostrar dados ou variações de gráficos), você pode experimentar ajustar também fig-width conforme a discussão a seguir.

Se você perceber que está precisando apertar os olhos para enxergar o texto no seu gráfico, você precisa ajustar o fig-width. Se fig-width é maior que o tamanho da figura renderizada no documento final, o texto ficará muito pequeno; se fig-width for menor, o texto ficará grande demais. Frequentemente será necessário alguma experimentação para acertar a razão entre fig-width e a largura do seu documento. Para ilustrar, os três gráficos a seguir têm fig-width de 4, 6, e 8 respectivamente:

Se você quiser garantir que o tamanho da fonte seja consistente em todas as suas figuras, será necessário ajustar sempre o out-width com o fig-width para manter a mesma razão com o out-width padrão. Por exemplo, se seu fig-width padrão é 6 e o out-width está em “70%”, será necessário configurar fig-width a 4.3 (6 * 0.5 / 0.7) quando ajustar out-width: "50%".

Entender dimensionamento é uma arte e uma ciência e acertar essas coisas pode requerer uma abordagem de tentativa e erro. Você pode aprender mais sobre isso no post de blog tomando controle de dimensionamento de gráficos.

28.6.2 Outras opções importantes

Quando estamos trabalhando com código e texto, como neste livro, é possível ajustar fig-show: hold de modo que os gráficos sejam exibidos após o código. Isso rende o efeito agradável de nos forçar a quebrar blocos de código grandes em menores com suas explicações.

Para adicionar uma legenda ao gráfico, use fig-cap. No Quarto isso mudará a figura de inline (no meio do texto) para “floating”.

Se você está produzindo PDF, o tipo de gráfico padrão é PDF. Isso é um bom padrão porque PDFs são gráficos vetoriais de alta qualidade. No entanto, isso pode gerar gráficos muito grandes e lentos se você está exibindo milhares de pontos. Nesse caso, ajuste fig-format: "png" para forçar o uso de PNGs. Esses têm qualidade ligeiramente menor, mas são muito mais compactos.

É uma boa ideia dar rótulos a blocos de código que produzam figuras, mesmo que você rotineiramente não faça isso. O rótulo do bloco é usado para gerar o nome de arquivo do gráfico salvo em disco, então nomear seus blocos facilita muito a identificação dos gráficos e reutilizá-los em outras circunstâncias (por exemplo, quando é necessário pegar um único gráfico para enviar um email).

28.6.3 Exercícios

1. Abra diamond-sizes.qmd no editor visual, ache uma imagem de diamante, copie e cole no documento. Clique duas vezes na imagem e adicione uma legenda. Redimensione a imagem e renderize o documento. Observe como a imagem é salva no seu diretório de trabalho.

2. Edite o rótulo do bloco de código em diamond-sizes.qmd que gera um gráfico para que comece com o prefixo fig- e adicione uma legenda à figura com a opção de bloco fig-cap. Em seguida, edite o texto acima do bloco de código e adicione uma referência cruzada para a figura com Insert > Cross Reference.

3. Mude o tamanho da figura com as seguintes opções de bloco, uma por vez, renderize o documento e descreva como a figura muda.

   1. fig-width: 10

   2. fig-height: 3

   3. out-width: "100%"

   4. out-width: "20%"

28.7 Tabelas

Semelhante ao apresentado para figuras, é possível incluir dois tipos de tabelas em um documento Quarto. Elas podem ser tabelas markdown que você pode criar diretamente em seu documento Quarto (usando o menu Insert Table) ou podem ser geradas como resultado de um bloco de código. Nesta seção focaremos na segunda, tabelas geradas via computação.

Por padrão, Quarto imprime data frames e matrizes como você as veria no console:

mtcars[1:5, ]
#>                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
#> Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
#> Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
#> Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
#> Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
#> Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2

Se voce preferir que os dados sejam expostos com formatação adicional, você pode usar a função knitr::kable(). O código abaixo gera Tabela 28.1.

knitr::kable(mtcars[1:5, ], )

Tabela 28.1: Uma tabela feita com knitr (kable).

	mpg	cyl	disp	hp	drat	wt	qsec	vs	am	gear	carb
Mazda RX4	21.0	6	160	110	3.90	2.620	16.46	0	1	4	4
Mazda RX4 Wag	21.0	6	160	110	3.90	2.875	17.02	0	1	4	4
Datsun 710	22.8	4	108	93	3.85	2.320	18.61	1	1	4	1
Hornet 4 Drive	21.4	6	258	110	3.08	3.215	19.44	1	0	3	1
Hornet Sportabout	18.7	8	360	175	3.15	3.440	17.02	0	0	3	2

Leia a documentação para ?knitr::kable para ver de que outras formas você pode personalizar a sua tabela. Para uma personalização ainda mais profunda, considere os pacotes gt, huxtable, reactable, kableExtra, xtable, stargazer, pander, tables, e ascii. Cada um fornece um conjunto de ferramentas para retornar tabelas formatadas a partir de código R.

28.7.1 Exercícios

1. Abra diamond-sizes.qmd no editor visual, insira um bloco de código e adicione uma tabela com knitr::kable() que mostre as 5 primeiras linhas do data frame diamonds.
2. Exiba a mesma tabela com gt::gt().
3. Adicione um rótulo de bloco de código que comece com o prefixo tbl- e adicione a legenda para a tabela com a opção de bloco tbl-cap. Depois edite o texto acima do bloco de código para adicionar a referência cruzada para a tabela com Insert > Cross Reference.

28.8 Salvando em cache

Normalmente, cada renderização do documento começa de uma folha em branco. Isso é ótimo para reprodutibilidade porque garante que você capturou toda computação importante em código. No entanto, pode ser doloroso refazer computações que tomam um tempo longo. A solução para isso é cache: true.

É possível habilitar o cache do knitr no nível do documento para guardar em cache os resultados de todas as computações em um documento usando as opções padrão de YAML:

---
title: "Meu documento"
execute: 
  cache: true
---

Também é possível permitir caching no nível de bloco para guardar os resultados da computação de um bloco específico em cache.

```{r}
#| cache: true

# código para uma computação longa...
```

Quando configurado, isso salvará os resultados do bloco para um arquivo de nome especial em seu disco de armazenamento. Em execuções subsequentes, o knitr verificará se houve alguma alteração no código e caso isso não tenha acontecido os resultados em cache serão reutilizados.

O sistema de cache deve ser usado com cuidado porque, por padrão, é usado apenas no código, e não em suas dependências. Por exemplo, aqui o bloco dados_processados depende do bloco dados-crus:

``` {{r}}
#| label: dados-crus
#| cache: true

dadoscrus <- readr::read_csv("um_arquivo_enorme.csv")
```

``` {{r}}
#| label: dados_processados
#| cache: true

dados_processados <- dadoscrus |> 
  filter(!is.na(var_importante)) |> 
  mutate(nova_variavel = transformacao_complicada(x, y, z))
```

Guardar o bloco processed_data em cache signigica que ele será executado novamente se o pipeline de dplyr for alterado, mas não se a chamada de read_csv() mudar. Esse problema pode ser evitado com a opção dependson:

``` {{r}}
#| label: dados-processados
#| cache: true
#| dependson: "dados-brutos"

dados_processados <- dadoscrus |> 
  filter(!is.na(var_importante)) |> 
  mutate(nova_variavel = transformacao_complicada(x, y, z))
```

dependson deve conter um vetor de caracteres em todos os blocos de que o bloco em cache depende. O knitr atualizará os resultados para o bloco em cache sempre que detectar que uma de suas dependências mudou.

Note que os blocos não serão atualizados se um_arquivo_enorme.csv mudar, já que o cache do knitr só monitora alterações no arquivo .qmd. Se você quiser também monitorar mudanças naquele arquivo, é possível usar a opção cache.extra. Essa é uma expressão de R arbitrária que invalida o cache toda vez que há alteração. Uma boa função neste caso é file.mtime(): a função retorna quando foi a última alteração. Você pode então escrever:

``` {{r}}
#| label: raw-data
#| cache: true
#| cache.extra: !expr file.mtime("um_arquivo_enorme.csv")

dadoscrus <- readr::read_csv("um_arquivo_enorme.csv")
```

Seguimos o conselho de David Robinson para nomear esses blocos: cada um é nomeado de acordo com o objeto primário que é criado. Isso facilita a compreensão da especificação de dependson.

Na medida em que suas estratégias de cache vão complicando, é uma boa ideia limpar todo o seu cache com knitr::clean_cache().

28.8.1 Exercícios

1. Ajuste uma sequência de blocos em que d depende de c e b e os dois últimos dependem de a. Faça com que cada bloco imprima lubridate::now(), ajuste cache: true e verifique o que você entendeu sobre caching.

28.9 Resolução de problemas

Resolver problemas em documentos Quarto pode ser desafiador porque você não está mais em um ambiente interativo de R, então você precisará aprender uns truques novos. Além disso, o erro pode ter ocorrido devido a problemas no documento de Quarto ou mesmo devido ao código em R no documento.

Um erro comum em documentos com blocos de código é haver rótulos de blocos duplicados, o que tem certa ocorrência se o seu fluxo de trabalho envolve copiar e colar de blocos de código. Para abordar esse problema, tudo que você precisa fazer é mudar o nome de um dos seus rótulos duplicados.

Se os erros ocorrem por causa do código em R no documento, a primeira coisa que você deveria fazer sempre é tentar recriar o problema em uma sessão interativa. Reinicie o R, depois execute todos os blocos (Run all chunks) via Run region no menu Code ou com o atalho Ctrl + Alt + R. Se estiver com sorte, isso recriará o problema e você descobrirá o que está acontecendo interativamente.

Se isso não ajudar, deve haver algo diferente entre o seu ambiente interativo e o seu ambiente Quarto. Será necessário explorar as opções sistematicamente. A diferença mais comum é o diretório de trabalho: o diretório de trabalho de um documento Quarto é aquele em que o documento vive. Verifique se o diretório é o que você espera usando getwd() em um bloco.

A seguir, tente listar todas as coisas que poderiam causar o bug. Será necessário verificar sistematicamente se essas coisas são as mesmas na sua sessão R e na sua sessão Quarto. A forma mais fácil de fazer isso é ajustar error: true no bloco causando o problema e usar print() e str() para verificar que as configurações são o que você espera.

28.10 Cabeçalho YAML

É possível controlar muitas outras configurações de “documento inteiro” ajustando os parâmetros do cabeçalho YAML. Você pode estar pensando no que significa YAML: é “YAML Ain’t Markup Language” ou “YAML não é linguagem Markup” – mas não carrega a sigla em português. A linguagem foi projetada para representar dados hierárquicos de uma forma que seja fácil para humanos lerem e escreverem. Quarto usa isso para controlar muitos detalhes da saída. Aqui discutiremos três: documentos autocontidos, parâmetros de documentos e bibliografias.

28.10.1 Documentos Autocontidos

Documentos HTML tipicamente têm uma série de dependências externas (por exemplo imagens, guias de estilo CSS, JavaScript, etc.) e, por padrão, o Quarto coloca essas dependências em uma pasta _files no mesmo diretório que o seu arquivo .qmd. Se você publicar o arquivo HTML em uma plataforma (por exemplo, QuartoPub, https://quartopub.com/), as dependências desse diretório são publicadas com o documento e então estarão disponíveis no relatório publicado. No entanto, se você quer enviar o relatório para um colega por email, é possível que prefira ter um único documento HTML autocontido que tem suas dependências todas embutidas. Você pode fazer isso especificando a opção embed-resources.

format:
  html:
    embed-resources: true

O arquivo resultante será autocontido, de modo que não necessitará de qualquer arquivo interno nem de acesso à internet para ser exibido corretamente por um navegador.

28.10.2 Parâmetros

Documentos Quarto podem incluir um ou mais parâmetros cujos valores podem ser ajustados quando se renderiza o relatório. Parâmetros são úteis quando se quer executar mais vezes o mesmo relatório com valores diferentes para vários inputs chave. Por exemplo, pode ser que seja necessário produzir relatórios de vendas por filial, resultados de provas por aluno ou mesmo resumos demográficos por país. Para declarar um ou mais parâmetros, use o campo params.

Esse exemplo usa o parâmetro my_class para determinar que classe de carros será exibida:

---
format: html
params:
  minha_classe: "suv"
---

```{r}
#| label: setup
#| include: false

library(tidyverse)
library(dados)

classe <- milhas |> filter(classe == params$minha_classe)
```

# Economia de combustível para `r params$minha_classe`

```{r}
#| message: false

ggplot(classe, aes(x = cilindrada, y = rodovia)) + 
  geom_point() + 
  geom_smooth(se = FALSE)
```

Como se pode ver, parâmetros estão disponíveis dentro dos blocos de código como uma lista chamada params com permissão apenas de leitura.

É possível escrever vetores atômicos diretamente no cabeçalho YAML. É possível ainda executar expressões arbitrárias em R prefixando o valor do parâmetro com !expr. Essa é uma boa forma de especificar parâmetros de data/tempo.

params:
  start: !expr lubridate::ymd("2015-01-01")
  snapshot: !expr lubridate::ymd_hms("2015-01-01 12:30:00")

28.10.3 Bibliografias e citações

Bibliografia e citações podem ser automaticamente geradas pelo Quarto em uma série de estilos. A forma mais direta de adicionar citações e bibliografias no seu documento Quarto é usando o editor visual no RStudio.

Para adicionar a citação no editor visual, vá em Insert > Citation. Citações podem ser inseridas a partir de uma variedade de fontes:

1. Referências DOI (Digital Object Identifier).

2. Bibliotecas particulares ou de grupo do Zotero.

3. Pesquisas na Crossref, DataCite, ou na PubMed.

4. Seu documento de bibliografia (um arquivo .bib no diretório do seu documento).

Internamente, o editor visual usa a representação padrão para citações do markdown Pandoc (por exemplo, [@citation]).

Se você inserir uma citação usando um dos primeiros três métodos, o editor visual automaticamente criará um arquivo bibliography.bib para você e adicionará a sua referência a ele. Isso também adicionará um campo bibliography ao YAML do documento. À medida em que você insere mais referências, esse arquivo é povoado com as citações. Também é possivel editar diretamente esse arquivo usando muitos formatos comuns como BibLaTeX, BibTeX, EndNote, Medline.

Para criar a citação dentro do seu arquivo .qmd no editor source, use a chave composta de ‘@’ + identificador da citação do seu arquivo de bibliografia. Em seguida, coloque a citação entre colchetes. Seguem alguns exemplos:

Separe múltiplas citações com `;`: Blah blah [@smith04; @doe99].

É possível inserir comentários arbitrários nos colchetes: 
Blah blah [veja @doe99, pp. 33-35; também @smith04, cap. 1].

Remova os colchetes para criar uma citação direta: @smith04 diz blah, ou @smith04 [p. 33] diz blah.

Adicione um `-` antes da citação para suprimir o nome do autor:
Smith diz blah [-@smith04].

Quando o Quarto renderiza o seu arquivo, a bibliografia será construída e adicionada ao final do seu documento. A bibliografia conterá cada uma das citações do seu arquivo de bibliografia, mas não é criado um título no documento para ela. Como resultado, é uma prática comum finalizar o seu documento com um título de seção para a bibliografia como # Referências ou # Bibliografia.

É possível alterar o estilo das suas citações e bibliografia fazendo referência a um arquivo CSL (citation style language – ou linguagem de estilo de citação) no campo csl:

bibliography: rmarkdown.bib
csl: apa.csl

Assim como no campo de bibliografia, seu arquivo csl deve conter um caminho para o arquivo. Aqui assumimos que o arquivo CSL está no mesmo diretório que o arquivo .qmd. Um bom lugar para encontrar arquivos de estilo CSL para sua bibligrafia é em: https://github.com/citation-style-language/styles.

28.11 Fluxo de trabalho

Anteriormente discutimos um fluxo de trabalho básico para executar seu código R, trabalhando interativamente no console, e depois salvar o que funciona no editor de script. O Quarto junta o console e o editor de script, deixando menos clara a linha que separa a exploração interativa e captura de código para longo prazo. Você pode trabalhar interativamente dentro de um bloco, editando e executando novamente com Cmd/Ctrl + Shift + Enter. Quando o trabalho estiver bom, você pode continuar e criar um novo bloco de código.

O Quarto também é importante porque integra estreitamente texto e código. Isso faz do Quarto um ótimo caderno de análise (analysis notebook), porque permite desenvolver código e registrar seus pensamentos. Um caderno de análise compartilha muitos dos mesmos objetivos de um caderno de laboratório clássico nas ciências exatas. O caderno:

• Permite gravar o que você fez e por que você fez. Independentemente de quão boa é a sua memória, se você não registrar o que fez, chegará um momento em que você esquecerá os detalhes importantes. Escreva para não se esquecer!

• Apoia o pensamento rigoroso. É mais provável que você desenvolva uma análise robusta se você registrar seus pensamentos enquanto trabalha, depois pode continuar a refletir sobre eles. Isso também economiza tempo quando você eventualmente organizar sua análise para compartilhar com outras pessoas.

• Ajuda outras pessoas a entenderem o seu trabalho. É raro fazer análise de dados sozinho e você frequentemente fará parte de uma equipe. Um caderno de laboratório ajuda a compartilhar com seus colegas não apenas o que você fez, mas também porque você fez o que fez.

Muitos dos bons conselhos sobre o uso efetivo de cadernos de laboratórios podem também ser traduzidos para cadernos de análise. Tiramos de nossa própria experiência e dos conselhos de Collin Purrington sobre cadenos de laboratório (https://colinpurrington.com/tips/lab-notebooks) para desenvolver essas dicas:

• Garanta que cada caderno tem um título descritivo, um nome evocativo e um primeiro parágrafo que descreve brevemente os objetivos de análise.

• Use o campo de data do cabeçalho YAML para registrar a data em que você começou a trabalhar no caderno:

  date: 2016-08-23

  Use ISO8601 YYYY-MM-DD para não haver ambiguidade. Use mesmo que você não escreva datas desse jeito!

• Se você passa muito tempo em uma ideia de análise e no final parece que não vai dar em nada, não apague! Faça uma breve anotação sobre o motivo de a análise ter falhado e deixe no caderno. Isso ajudará você a não cair na mesma rota quando voltar à análise no futuro.

• Geralmente é melhor registrar dados fora do R. Se você precisa registrar um pequeno trecho dos dados, faça isso de forma explícita usando tibble::tribble().

• Se você descobrir um erro no arquivo de dados, nunca o modifique diretamente. Em vez disso, escreva código para corrigir o valor. Escreva o motivo do reparo.

• Antes de finalizar os trabalhos do dia, garanta que é possível renderizar o caderno. Se está usando caching, limpe os caches. Isso permitirá a correção de problemas enquanto o código ainda está fresco na memória.

• Se você quiser que seu código seja reprodutível a longo prazo (por exemplo, para voltar a trabalhar nele no mês ou ano seguinte), pode ser necessário registrar as versões dos pacotes que seu código usa. Uma abordagem rigorosa é usar renv, https://rstudio.github.io/renv/index.html, que guarda os pacotes no seu diretório do projeto. Um macete é incluir um bloco que execute sessionInfo() — isso não permite facilmente recriar seus pacotes em seu estado atual, mas pelo menos ajuda a saber em que estado estavam.

• Você criará muitos, muitos cadernos de análise no decorrer da sua carreira. Como você os organizará de modo que consiga achá-los no futuro? Recomendamos guardá-los em projetos individuais e criar um bom esquema de nomes.

28.12 Resumo

Neste capítulo apresentamos o Quarto para escrita e publicação reprodutível de documentos computacionais que incluam seu código e seu texto no mesmo lugar. Você aprendeu sobre escrever em documentos Quarto no RStudio com o editor fonte ou visual, como blocos de código funcionam e como personalizar opções para cache de computações. Além disso, você aprendeu sobre ajustes no cabeçalho YAML para criar documentos autocontidos ou parametrizados, assim como incluir citações e bibliografia. Também demos dicas de fluxo de trabalho e de resolução de problemas.

Enquanto essa introdução deve ser suficiente para iniciar seu trabalho com Quarto, ainda há muito a aprender. Quarto ainda é relativamente jovem e ainda está crescendo rapidamente. O melhor lugar para se atualizar das últimas inovações é o site oficial: https://quarto.org.

Há dois tópicos importantes que não cobrimos aqui: colaboração e detalhes para comunicar sua ideia com precisão para outros humanos. Colaboração é uma parte vital da ciência de dados moderna e você pode facilitar muito a sua vida usando ferramentas de controle de versão, como Git e GitHub. Recomendamos o livro “Happy Git with R”, uma introdução amigável ao Git e ao GitHub para quem programa em R, escrito pela Jenny Bryan. O livro está disponível online com acesso livre: https://happygitwithr.com.

Também não comentamos sobre o que você deveria realmente escrever para comunicar seus resultados da sua análise com clareza. Para melhorar sua escrita, recomendamos muito a leitura de Style: Lessons in Clarity and Grace por Joseph M. Williams & Joseph Bizup, ou The Sense of Structure: Writing from the Reader’s Perspective por George Gopen. Ambos os livros ajudarão a entender a estrutura de frases e parágrafos e darão ferramentas para tornar sua escrita mais clara. (esses livros são um tanto caros, mas são muito usados em cursos de inglês, então há muitas cópias baratas de segunda mão). George Gopen também tem uma série de artigos curtos sobre escrita em https://www.georgegopen.com/the-litigation-articles.html. Esses são direcionados a advogados, mas quase tudo se aplica a cientistas de dados também.