Introdução à Ciência de Dados no R

---

Aula 11 - Documentos Dinâmicos

Aula 11

Antonio Vinícius Barbosa

26-03-2024

Documentos Dinâmicos

Literate programming

A ideia do Literate programming consiste em combinar inputs e outputs com o objetivo de criar documentos reproduzíveis

• De forma geral, combina o texto da forma usual com elementos de programação.
• Assim, os diversos elementos são combinados para gerar um documento reprodutível e auto explicativo

Pacotes

Alguns pacotes do R permitem a integração de textos e códigos

• sweave: permitia que o código R fosse integrado a documentos LaTeX
• knitr: variação do Markdown que permite a junção de códigos
• rmarkdown: permite a construção de textos, apresentações, sites…

Atualmente, o quarto é a ferramenta mais completa para gerar documentos dinâmicos

quarto

quarto

• quarto é um sistema de publicação científica e técnica de código aberto
• É possível combinar texto narrativo e código para produzir uma saída elegantemente formatada como documentos, páginas da Web, postagens de blog, livros e muito mais.

Para instalar, fazemos:

#Instalar pacote
install.packages("rmarkdown")
install.packages("quarto")

quarto

Como o quarto funciona?

• Ao renderizar um documento quarto, primeiro o knitr executa todos os blocos de código e cria um novo documento markdown (.md) que inclui o código e sua saída.
• O arquivo markdown gerado é então processado pelo pandoc, que cria o formato finalizado.
• O botão Render encapsula essas ações e as executa na ordem certa.

Criando um documento quarto

• Para criar um novo documento vá em File > New File > Quarto Document
• Alternativamente, utilize os comandos Ctrl+Shift+P para criar um novo documento

Renderização

Use o botão Render no RStudio IDE para renderizar o arquivo e visualizar a saída com um único clique ou atalho de teclado (Ctrl + Shift + K).

Ao renderizar, o quarto gera um novo arquivo que contém texto, código e resultados selecionados do arquivo .qmd. O novo arquivo pode ser um documento HTML,PDF, MS Word, apresentação, website, livro, documento interativo ou outro formato.

Formas de visualização

Existem dois tipos de editores: Source e Visual

A anatomia de um documento

Há três componentes principais em um documento Quarto:

• Os metadados (YAML) contêm as informações básicas do documento, tais como título, autor e o tipo de output, além de outras opções. Este componente está compreendido entre três linhas (---).
• O corpo do documento, escrito em Markdown.
• O bloco de código (ou code chunk) com a indicação da linguagem utilizada a ser executada.

A anatomia de um documento

Como exemplo, considere o seguinte código

---
title: "ggplot2 demo"
date: "5/22/2021"
format: html
---

## Air Quality

There is a relationship between temperature and the ozone level.

```{r}
#| label: fig-airquality
library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess"
)
```

Metadata: YAML

Como vimos, os metadados são inseridos entre os três traços (---). A sintaxe dos metadados é o YAML (YAML Ain’t Markup Language). Nela, inserimos informações básicas do documento, tais como o título, data:

---
key: value
---

Por exemplo, para inserir o título fazemos:

---
title: "Meu primeiro documento"
---

Para inserir data no documento:

---
date: 09/05/2023
---

Opções de Formatos

Existem várias opções de formatos. Para o formato HTML:

---
format: html
---

Para documentos com formato PDF:

---
format: pdf
---

Para apresentações, utilizamos:

---
format: revealjs
---

Outras opções disponíveis podem ser vistas neste link.

Opções de Formatos

Além disso, é possível definir opções dentro de um formato:

---
format: 
  html:
    toc: true
    code-fold: true
---

Notar que a identação (espaçamento) importa no YAML.

format: html

• Para outras opções do formato HTML, ver a documentação.
• Além disso, ver o guia de referência.

Markdown: elementos textuais

• Desenvolvido em 2004 por John Gruber e Aaron Swartz para simplificar a estruturação de um texto, o Markdown é um sistema de formatação aberto que torna a escrita e a leitura mais simples. Com uma codificação mínima, além de fácil, ele é visualmente mais “limpo” e pode ser convertido facilmente para HTML.

Sintaxe Markdown

Do lado esquerdo temos alguns exemplos da sintaxe do Markdown e, do lado direito, o resultado gerado.

Sintaxe Markdown

Para inserir seções e subseções no texto, fazemos através do símbolo #

Sintaxe Markdown

Para inserir tópicos, listas ordenadas e tabelas no Markdown, utilizamos a seguinte sintaxe:

Adicionando links e hyperlinks

Para adicionar um link, podemos fazer:

A [UFPB](https://www.ufpb.br/) é a maior universidade do estado.

A UFPB é a maior universidade do estado.

Ou diretamente, através de:

Website da UFPB: <https://www.ufpb.br/>

Website da UFPB: https://www.ufpb.br/

Bloco de códigos

Um bloco de código (ou code chunks) possui a seguinte estrutura básica:

```{r}
#| label: car-stuff
#| echo: false
mtcars |>  
  distinct(cyl)
```

• Um código é inserido entre os símbolos ```
• {r} siginifica a linguagem que o código será executado
• As opções de execução são inseridos através de comentário especial #| (hashpipe)

Códigos em linha

Para incluir expressões executáveis, utilizamos a notação 'r ' . Por exemplo, podemos usar código embutido para indicar o número de observações em nossos dados.

A base mtcars possui 32 linhas e 11 colunas.

Bloco de códigos

• A forma como adicionamos códigos no documento depende do contexto.
• Para fins didáticos, é sempre importante mostrar o código e o resultado gerado.
• Para relatórios e trabalhos acadêmicos, no entanto, podemo omitir o código e apresentar apenas o output.

Bloco de códigos

Por exemplo, as opções eval e echo mudam a forma de apresentação e execução:

```{r}
#| eval: true
#| echo: true
head(mtcars)
```

O código gera o seguinte resultado

head(mtcars)

                   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
Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

Bloco de códigos

Para apresentar apenas o output, fazemos:

```{r}
#| eval: true
#| echo: false
head(mtcars)
```

Obtendo, como resulado:

                   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
Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

Bloco de códigos

Ainda, é possível apresentar apenas o código, mas não executar:

```{r}
#| eval: false
#| echo: true
head(mtcars)
```

Obtendo, como resulado:

head(mtcars)

Outras opções de execução

• include: (true) Inclui o resultado do código no documento.
• message: (true) Inclui mensagem do R.
• warning: (true) Inclui avisos do R.
• output: (true) Como e se incluir os resultados.
• label: Adicionar um label para um código
• collapse (true) Junta código e resultado num mesmo quadro.

Outras opções de execução

```{r}
#| label: meu_histograma
#| eval: true
#| echo: true
#| warning: false
#| message: false
#| collapse: true
head(mtcars)
```

Como resultado, obtemos:

c(1, 1) + c(2, 4, 5)
## [1] 3 5 6

Destacando partes do código

É possível destacar linhas (ou conjunto de linhas de um código):

```{r}
#| label: meu_histograma
#| eval: false
#| code-line-numbers: "|5|7-11|"
library(ggplot2)

ggplot(data = mtcars) +
  geom_histogram(
    aes(x = hp), bins = 10
  ) +
  theme_minimal()
```

Callout Blocks

• Os Callout Blocks são uma excelente maneira de chamar atenção para determinados conceitos.

• Existem cinco tipos diferentes de chamadas disponíveis:

  • note
  • warning
  • important
  • tip
  • caution

Callout Blocks

:::{.callout-note}
## Importante
Este é um exemplo para notas!
:::

:::{.callout-tip}
## Dica
Este é um exemplo para dicas!
:::

Callout Blocks

:::{.callout-warning}
## Aviso
Este é um exemplo para avisos!
:::

:::{.callout-important}
## Importante
Este é um exemplo para algo importante!
:::

Callout Blocks

Importante

Este é um exemplo para notas!

Dica

Este é um exemplo para dicas!

Callout Blocks

Aviso

Este é um exemplo para avisos!

Importante

Este é um exemplo para algo importante!

Inserindo figuras

quarto possui uma série de ferramentas para introduzir finguras nos documentos. Para introduzir uma figura em Markdown, fazemos

![Elefante](elefante.jpg)

Elefante

Opções de figuras

Para alterar as dimensões de uma figura, utilizamos os parâmetros width e height. Além disso, podemos ajustar o alinhamento através de fig-align.

![Elefante](elefante.jpg){width=200 fig-align="left"}

Elefante

Figuras através de links

Para inserir figuras externas, obtidas através de links, fazemos:

![Caramelo](https://p16.resso.me/img/tos-alisg-i-0000/d0b1ea1759d84159a3bbd11952613b68~c5_500x500.jpg){width=100 fig.align="center"}

Caramelo

Subfiguras

Para adicionar múltiplas figuras, fazemos:

::: {#fig-elephants layout-ncol=2}

![Subfigura 1](https://quarto.org/docs/gallery/interactive/interactive-jupyter.png)

![Subfigura 2](https://quarto.org/docs/gallery/articles/advanced-layout-pdf.png)

Famous Elephants
:::

Subfiguras

Subfigura 1

Subfigura 2

Figure 1: Exemplo de documentos quarto

Tabelas

Uma das formas de adicionar tabelas é através da função kable do pacote knitr

knitr::kable(
  dados::dados_starwars[1:5,1:5],
  caption = "Personagens Starwars"
  )

Tabelas

Personagens Starwars

nome	altura	massa	cor_do_cabelo	cor_da_pele
Luke Skywalker	172	77	Loiro	Branca clara
C-3PO	167	75	NA	Ouro
R2-D2	96	32	NA	Branca, Azul
Darth Vader	202	136	Nenhum	Branca
Leia Organa	150	49	Castanho	Clara

Para outras opções de costumização das tabelas, é recomendado o pacote kableExtra

Mais adiante veremos as funcionalidades do pacote gt.

Apresentações

Apresentações

O quarto suporta alguns formatos para criar apresentações:

• revealjs — reveal.js (HTML)
• pptx — PowerPoint (MS Office)
• beamer — Beamer (LaTeX/PDF)

Enquanto o formato pptx e beamer geram apresentações estáticas, o formato revealjs gera aprensetações mais flexíveis.

Criando apresentações

Em Markdown, os slides são delineados usando seções. Por exemplo, esta é uma apresentação simples com dois slides (cada um definido com um título de nível 2 (##):

---
title: "Apresentacao ICDR"
author: "Antonio Vinicius"
format: revealjs
---

## Slide 1

- Apresentacao
- Objetivos

## Slide 2

- Resultados
- Conclusão

Criando apresentações

Para dividir os slides por seções, podemos introduzir títulos de nível 1 (#)

---
title: "Apresentacao ICDR"
author: "Antonio Vinicius"
format: revealjs
---

# Parte 1

## Slide 1

- Apresentacao
- Objetivos


# Parte 2

## Slide 2

- Resultados
- Conclusão

Listas incrementais

Por default, os bullets em um slide são apresentados de única vez. Podemos, no entanto, utilizar listas incrementais, conforme o exemplo a seguir:

---
title: "Apresentacao ICDR"
author: "Antonio Vinicius"
format: revealjs
---

## Slide 1

::: {.incremental}

- Apresentacao
- Objetivos

:::

Listas incrementais

É possível definir as listas incrementais de maneira global. Isto tornará default durante toda a apresentação:

---
title: "Apresentacao ICDR"
author: "Antonio Vinicius"
format: 
  revealjs:
    incremental: true
---

## Slide 1

- Apresentacao
- Objetivos

Slides com pausas

Para adicionar pausas dentro de um slide, inserimos três pontos (. . .) separados por espaços:

---
title: "Apresentacao ICDR"
author: "Antonio Vinicius"
format: 
  revealjs:
    incremental: true
---

## Slide 1

Texto inicial, antes da pausa

. . .

- Item 1
- Item 2

Múltiplas Colunas

Para inserir colunas lado a lado, você pode usar a classe .columns, contendo dois ou mais elementos .columns e o atributo width, conforme o exemplo a seguir:

---
title: "Apresentacao ICDR"
author: "Antonio Vinicius"
format: revealjs
---

## Slide 1

:::: {.columns}

::: {.column width="40%"}
Coluna 1
:::

::: {.column width="60%"}
Coluna 2
:::

::::

Adicionando guias

Para adicionar guias (ou tabset panel), utilizamos a classe .panel-tabset. Note que é importante incluir seções (##) para cada guia. Considere o exemplo abaixo

• Guia 1
• Guia 2

Inserir conteúdo da guia 1

Inserir conteúdo da guia 2

Adicionando guias

Para obter as guias, fazemos:

---
title: "Apresentacao ICDR"
author: "Antonio Vinicius"
format: revealjs
---

## Slide 1

::: {.panel-tabset}

## Guia 1

Inserir conteúdo da guia 1

## Guia 2

Inserir conteúdo da guia 2

:::

Transições de slides

Para os diferentes tipos de transições de slides, temos

• none: sem transição (instantâneo)
• fade: cross fade
• slide: Slide horizontal
• convex: slide convexo
• concave: slide côncavo
• zoom: do centro para fora da tela

---
format: 
  revealjs:
    transition: fade
    transition-speed: fast
---

Numerando slides

Para adicionar o número do slide, fazemos

---
format: 
  revealjs:
    slide-number: c/t
---

Onde c/t significa slide corrente/total de slides. Outras opões são c, h.v, h/v.

Adicionando texto de rodapé

---
format:
  revealjs: 
    footer: "Meu texto de rodapé"
---

Para adicionar um texto de rodapé numa apresentação:

Quizz #1

• Crie uma nova apresentação revealjs no Quarto.
• Mude o YAML:
  • Nome do autor: eu nome
  • Título: “Minha primeira apresentação Quarto!”
  • Adiciona o número do slide
  • Inserir rodapé: “Minha apresentação!”
• No segundo slide, adiciona uma lista incremental sobre as top 5 disciplinas que você mais gostou no curso.

• Adicionar um slide com 2 colunas. No lado direito, adicionar apenas o code chunk e no lado direito apenas o resultado da execução.
• Adicionar um slide com 2 guias. Na primeira guia, adicionar apenas o code chunk e na segunda guia apenas o resultado da execução.
• No próximo slide, adicione uma figura externa
• Gere a apresentação!

15:00

Gerando PDF

Para gerar arquivos PDF, é necessário instalar uma distribuição TeX. No terminal, fazer:

quarto install tool tinytex

Uma vez instalado, ajustamos o formato do documento:

---
format: pdf
---

Opções do PDF

title: "Meu documento"
format: 
  pdf: 
    documentclass: report
    classoption: [twocolumn, landscape]
    lof: true
    lot: true
    geometry:
      - top=30mm
      - left=20mm
      - heightrounded
    fontfamily: libertinus
    colorlinks: true
---

• documentclass: classe do documento, como article, report ou book
• classoption: estrutura onecolumn/twocolumn, portrait/landscape
• lof-lot: lista de figuras e tabelas
• geometry: recuo das margens
• fontfamily: usar fontes do sistema. Ver lista completa em systemfonts::system_fonts()
• colorlinks: destacar links do texto

Publicação

Quarto Pub

Quarto Pub é um serviço gratuito de publicação de conteúdo criado com o Quarto. É ideal para blogs, sites de cursos ou projetos, livros e apresentações.

O primeiro passo consiste em criar uma conta gratuita no Quarto Pub.

Quarto Pub

Para publicar um conteúdo, é necessário criar um projeto no RStudio. Em seguida, digitar no Terminal

quarto publish quarto-pub

Após isso, é necessário adicionar o login e senha cadastrados.

Galeria

Galeria

Para aprender mais, ver galeria com exemplos e códigos (link).