Tipos de produtos (=‘Output’)

Podemos produzir diferentes tipos de produtos utilizando arquivos Rmd: documentos, apresentações, sítios web, e painéis de gestão (conhecidos como dashboard na língua inglesa). Discorrerei sobre cada um deles, nas próximas seções.

Objetivos de aprendizado

• Compilar um arquivo Rmd em HTML;
• Compilar um arquivo Rmd em PDF;
• Compilar um arquivo Rmd em DOCX;

HTML

O arquivo HTML é a saída mais comum quanto ao tipo de produto gerado em arquivos Rmd e, portanto, possui o maior número de funcionalidades disponíveis em comparação com os outros tipos de produtos possíveis (PDF e DOCX). Há diversas maneiras de produzir HTML distintos, a depender do pacote R utilizado e a finalidade do HTML. Começaremos pela maneira mais simples, utilizando a função rmarkdown::html_document() do pacote R rmarkdown (Allaire et al. 2024):

---
title: "Análise exploratória de dados"
author: Ricardinho
date: 4 Jun 2024
output: html_document
---

Acrescentar sumário

Para acrescentar um sumário (ou tabela de conteúdo) em seu documento, use o argumento toc e especifique a profundidade do sumário por meio do argumento toc_depth:

---
title: "Análise exploratória de dados"
author: Ricardinho
date: 4 Jun 2024
output: 
  html_document:
    toc: true
    toc_depth: 3
---

Reparem que em metadados YAML, os espaços contam; isto é, a indentação é necessária!

A profundidade do sumário diz respeito ao grau do cabeçalho que se deseja atingir, isto é, você deseja que seu sumário liste os cabeçalhos até o segundo grau (== “##”)? Ou até o terceiro grau (==“###”)? Ou até o quarto grau (=“####”) ?

Para cada uma das respostas acima, teríamos o argumento toc_depth com as seguintes respostas:

toc_depth: 2
toc_depth: 3
toc_depth: 4

Se não desejarmos o sumário, podemos usar o argumento toc: false ou simplesmente não utilizá-lo.

Numerar seções

Você pode numerar seções utilizando o argumento number_sections, que habilita a numeração caso seja atribuído o valor true a ele:

---
title: "Análise exploratória de dados"
author: Ricardinho
date: 4 Jun 2024
output: 
  html_document:
    number_sections: true
---

Se você desejar numerar todas as seções, excluindo alguma(s), você pode fazer acrescentar o valor {-} após o cabeçalho que você deseja não numerar. Por exemplo, suponha que a seção # Prefácio não deva ser numerada por você. Você deve fazer então da seguinte maneira:

# Prefácio {-}

Referência cruzada de figuras e tabelas

Fazer referência de figuras e tabelas no texto é um recurso muito útil em qualquer tipo de documento. Porém, este recurso só está disponível no pacote R bookdown (Xie 2024). Logo, será necessário mudar o valor atribuído ao argumento output nos metadados do seu arquivo. Em vez de output: html_document, usaremos output: bookdown::html_document2. Veja abaixo:

---
title: "Análise exploratória de dados"
author: Ricardinho
date: 4 Jun 2024
output: bookdown::html_document2
---

Em seguida, devemos nos preocupar com a referência em si. Para isso, precisaremos dos itens abaixo:

• Figuras ou tabelas deverão possuir uma legenda;
• Pedaços de código nomeados, pois esse nome será o código utilizado como identificador da referência.

A referência cruzada é feita por meio da seguinte notação:

\@ref(tipo:codigo)

em que tipo se refere à figura fig ou tabela tab, e codigo se refere ao codigo identificador do pedaço de código em que faremos a inserção da figura ou tabela.

Para ficar mais claro, vejam o exemplo abaixo:

---
title: "Análise exploratória de dados"
author: Ricardinho
date: 4 Jun 2024
output: bookdown::html_document2
---

## Introdução

Aqui eu tenho um texto introdutório sobre minha análise exploratória de dados (AED) referentes a carros.  

Vejam a figura \@ref(fig:fig1).  

```{r fig1, fig.cap = "Aqui vai a legenda das figuras."}
plot(mtcars)
```


A tabela \@ref(tab:minha-tabela) expõe as primeiras 6 linhas do conjunto de dados 'mtcars'.  

```{r minha-tabela}
kable(head(mtcars), caption = "Aqui vai a legenda de tabelas, isto é, dentro do argumento 'caption' da função knitr::kable")
```

Para mais possibilidades, veja a seção Update the date automatically do livro Rmarkdown cookbook (Xie, Dervieux, e Riederer 2020).

Aparência

Por meio do argumento theme dentro do YAML, podemos controlar a aparência de seu arquivo HTML. Possíveis valores incluem:

default, bootstrap, cerulean, cosmo, darkly, flatly, journal, lumen, paper, readable, sandstone, simplex, spacelab, united, yeti

Teste cada uma dessas possibilidades e veja como fica a aparência de seu produto. Para testar, escreva dessa maneira no seu YAML, substituindo após theme: por cada uma das possibilidades acima:

---
title: "Análise exploratória de dados"
author: Guguinha
output: 
  html_document:
    theme: journal
---

Podemos mudar também a aparência dos pedaços de códigos em nossos produtos. Suponha que eu possua o código abaixo:

1 + 1

[1] 2

Como ele vai aparecer no produto final?

Nós controlamos essa variável por meio do argumento highlight. As opções disponíevis incluem:

default, tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark, textmate

Teste as opções acima em seu YAML escrevendo como abaixo:

---
title: "Análise exploratória de dados"
author: Guguinha
output: 
  html_document:
    highlight: espresso
---

Controle de pedaços de código

Os códigos escritos nas diversas linguagens possíveis de serem utilizadas em arquivos Rmd podem ser controlados quanto à exibição no produto final e também quanto aos efeitos dos códigos. Exemplificarei alguns dos argumentos mais utilizados:

• echo

• eval

• include

• message

• warning

# echo
```{r echo = FALSE}
library("MASS")
```

# eval
```{r eval = FALSE}
plot(long, lat, data = coordenadas)
```

# include
```{r include = FALSE}
library("dplyr")
library("purrr")
library("vegan")
```

# message
```{r message = FALSE}
library("dplyr")
library("purrr")
library("vegan")
```

# warning
```{r warning = FALSE}
library("palmerpenguins")
library("ggplot2")

ggplot(penguins) +
  geom_point(aes(x = bill_length_mm, y = bill_depth_mm, color = species)) +
  theme_bw()
```

Controle de figuras

Podemos controlar como as figuras aparecerão em nossos produtos por meio dos argumentos YAML a seguir:

• fig_width e fig_height controlam, respectivamente, a largura e altura da imagem;

• fig_caption controla se as figuras devem ser compiladas com ou sem legendas (valores possíveis true ou false)

• dev controla qual dispositivo deve compilar as figuras, isto é, se pdf, png, ou outros (padrão é o png).

Vejam possibilidades abaixo e testem em seus arquivos:

---
title: "Análise exploratória de dados"
author: Guerreira Luaninha
date: 4 Jun 2024
output: 
  html_document:
    fig_width: 7
    fig_height: 6
    fig_caption: true
---

Outra maneira de controlar a aparência das figuras é por meio de argumentos dentro dos pedaços de código. Os argumentos disponíveis são escritos de maneira parecida com os argumentos utilizados no YAML, porém diferem quanto à inserção de um ponto (.) no lugar do subtraço (_). As opções mais populares são:

• fig.height e fig.width, que determinam a altura e a largura da figura em polegadas, respectivamente. Os valores devem ser numéricos. Exemplo: fig.width = 8, fig.height = 4.

• fig.dim que combina a largura e a altura da figura, respectivamente, na mesma função, também expressa em polegadas. Exemplo: fig.dim = c(8, 4) é o mesmo que `fig.width = 8, fig.height = 4.

• fig.cap, que determina a legenda da figura. Deve apresentar sempre o texto que se deseja colocar entre aspas. Exemplo: fig.cap = "Essa é a legenda de minha figura.".

• out.width e out.height, que expressa o tamanho da imagem no produto final, cujos valores são expressos em porcentagens, “50%”, “70%” etc. Exemplo: out.width = "50%", out.height = "80%".

Exemplos de aplicação desses argumentos são expressos abaixo:

# Usando fig.width e fig.height
```{r, fig.width = 12, fig.height = 10, fig.cap="Olha a legenda da figura"}
knitr::include_graphics("fotinha.jpg")
```

# out.width e out.height
```{r, out.width="50%", out.height = "50%"}
knitr::include_graphics("fotinha.jpg")
```

# fig.dim
```{r, fig.dim = c(12,10)}
knitr::include_graphics("fotinha.jpg")
```

Mais opções estão explicadas detalhadamente na seção Plots da página dedicada ao pacote knitr (Xie 2014).

PDF

O formato PDF possui opções não disponíveis para outros formatos, já que é o LaTeX que controla o produto final. Do que já vimos até então, as opções Acrescentar sumário, Numerar seções, Referência cruzada de figuras e tabelas e Controle de figuras também são válidas no PDF.

Allaire, JJ, Yihui Xie, Christophe Dervieux, Jonathan McPherson, Javier Luraschi, Kevin Ushey, Aron Atkins, et al. 2024. rmarkdown: Dynamic Documents for R. https://github.com/rstudio/rmarkdown.

Xie, Yihui. 2014. «knitr: A Comprehensive Tool for Reproducible Research in R». Em Implementing Reproducible Computational Research, editado por Victoria Stodden, Friedrich Leisch, e Roger D. Peng. Chapman; Hall/CRC.

———. 2024. bookdown: Authoring Books and Technical Documents with R Markdown. https://github.com/rstudio/bookdown.

Xie, Yihui, Christophe Dervieux, e Emily Riederer. 2020. R Markdown Cookbook. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown-cookbook.