Capítulo 8 Criando relatórios no R

Em diversas situações práticas do dia a dia, um cientista de dados precisa transformar suas análises em documentos, relatórios, apresentaçoes ou até mesmo painéis interativos de alta qualidade.

No R, o cientista de dados irá criar tais documentos utilizando a ferramenta chamada de R Markdown. Porém, antes de falarmos mais sobre o R Markdown, iremos introduzir muito brevemente o que seria o Markdown.

8.1 Markdown

Foi desenvolvido em 2004 por John Gruber e Aaron Swartz para simplificar a estruturação de um texto. O Markdown pode ser visto como uma linguagem de marcação, isto é, não é uma linguagem de programação. As linguagens de marcação, de uma forma geral, nos dizem como algo deve ser entendido, mas não têm capacidade de processamento e execução de funções. Sendo assim, o Markdown pode ser visto como um sistema de formatação aberto que torna a escrita e a leitura mais simples.

Por exemplo, uma das linguagens de marcação mais usadas é o HTML. Ela apenas diz como uma página web está estruturada, mas não executa nenhum processamento. O Markdown, da mesma forma, apenas informa como um documento está estruturado.

Podemos citar como uma das grandes vantagens do Markdown, a sua simplicidade e a possibilidade de utilização de uma linguagem comum para a criação de vários tipos de documentos. Por exemplo, um mesmo código Markdown pode ser convertido para LaTeX (gera pdf’s), HTML, docx etc. Entretanto, para tal, é necessário um conversor, que lê um código em Markdown e, considerando a escolha do output desejado, converte o arquivo para a linguagem desejada. Isto ficará mais claro com os exemplos que serão discutidos ao longo deste material.

8.2 R Markdown

O R Markdown é a possibilidade de executarmos scripts em R (além de outras linguagens) e incorporá-los a um arquivo Markdown (extensão .Rmd). O responsável pela execução dos “pedaços” (chunk) de códigos é o pacote knitr que gerará um arquivo .Rmd com os códigos e seus resultados. Na sequência, o pandoc, que é um conversor, converte-o para a linguagem desejada, gerando os arquivos nos formatos escolhidos (.html, .docx, .pdf, .odt).

Com R Markdown, é possível:

  • Compilar um documento em um relatório com diferentes formatos de saída (PDF, HTML e Word).
  • Produzir slides para apresentações.
  • Entre outras possibilidades.

8.2.1 Primeiros passos no R Markdown

Instale o pacote knitr. Após a instalação, no Rstudio, acesse os menus File > New File > R Markdown… e clique em OK para criar um novo documento R Markdown.

Será aberta a janela abaixo solicitando algumas informações para a criação do arquivo.

A janela acima permite que seja definido um título, o autor, a data e o formato na qual o arquivo será produzido. Se formos produzir o arquivo em PDF ou em word é preciso verificar se possuímos os pré-requisitos indicados. Preencha os dados solicitados, informando como título Meu primeiro relatório, como autor Seu nome e pode deixar a data sugerida. Vamos deixar marcada a opção HTML.

Após o preenchimento, clique em OK. Você verá o seguinte documento:

A figura acima trás os três componentes básicos de um documento R Markdown: YAML, chunks e o texto.

Os Metadados, escritos no cabeçalho entre o par de três traços (—), são conhecidos como YAML (Yet Another Markup Language).

O YAML é o responsável por setar as configurações dos documentos. Basicamente, estamos informando qual é o título do documento, a data de criação, o nome do autor e o tipo de output que desejamos. No exemplo acima, estamos definido como output html_document, é possível incluir ainda outras formatações como tamanhos das figuras, numerações de seções, entre outros.

Se quiséssemos um arquivo no formato Word (.docx), o output poderia ser modificado para word_document, se quiséssemos um arquivo no formato PDF, o output poderia ser modificado para pdf_document. Cada formato possui um conjunto de opções disponíveis.

Já a parte de texto, é incluída com as formatações do markdown. Esse código markdown, quando convertido, gerará a formatação desejada. Na próxima seção, detalharemos o que cada marcação faz.

Os Code Chunks (partes nos blocos em cinza, chamados de chunks) seguem a sintaxe da linguagem especificada no cabeçalho do bloco (por padrão é R). Eles são pedaços de código em R que podem ser executados para gerar resultados que serão incorporados ao documento.

Você pode inserir um chunk manualmente ou com o atalho CTRL + ALT + I. Dentro de {} é possível incluir uma série de opções relacionadas à execução do código. Manualmente, um chunk de código é criado por um par de três aspas, como em ```{r}, onde r indica a linguagem do código.

Após a criação de um documento, o passo seguinte é realizar a renderização do mesmo. A forma mais simples é feita por meio do botão knit, disponível na interface do RStudio.

Renderize o arquivo criado! Para realizar a renderização, será preciso salvarmos o arquivo inicialmente.

8.2.2 Sintaxe

Abaixo encontram-se os principais elementos de sintaxe do R Markdown. Vocês perceberão que vários são autoexplicativos. Para alguns, faremos alguns comentários:

8.2.2.1 Estilo de texto

Formatações do tipo: negrito, itálico e riscado são obtidas da seguinte forma.

Podemos escrever o texto em *itálico* (_itálico_), **negrito** (__Negrito__) ou ~~riscado~~.

Como o texto vai aparecer no relatório:

Podemos escrever o texto em itálico (itálico), negrito (negrito) ou riscado.

8.2.2.2 Código processado no texto

É possível incluir no texto o resultado de análises.

Podemos ver que a média `r mean(c(2,4,3,100))` é afetada pela presença de um valor discrepante, enquanto que a mediana `r median(c(2,4,3,100))` não é afetada.

Como o texto vai aparecer no relatório:

A média dos valores é 27.25 e a mediana dos valores é 3.5.

8.2.2.3 Inclusão de imagens

É possível incluir imagens de duas formas. Vamos apresentar as diferenças entre as mesmas.

A primeira forma é a inclusão de uma imagem por meio da linguagem Markdown, como apresentado abaixo.

![](LES.png)

Já a segunda, é feita por meio da função include_graphics do pacote knitr e deve ser incluída dentro de um chunk, como apresentado abaixo.

Como vai aparecer no relatório em ambos os casos:

Incluindo a figura por meio da função include_graphics, é possível realizarmos uma série de configurações no chunk no que diz respeito ao alinhamento da figura, acrescentar títulot tamanho da imagens, entre outras.

No relatório a figura irá aparecer da seguinte forma:

Título da figura

Figure 8.1: Título da figura

8.2.2.4 Listas

É possível incluirmos listas ordenadas e não ordenadas.

* Item a
* Item b
  * Subitem b1
  * Subitem b2

Como o texto vai aparecer no relatório:

  • Item a
  • Item b
    • Subitem b1
    • Subitem b2
  1. Item 1
  
  2. Item 2
  
  3. Item 3

Como o texto vai aparecer no relatório:

  1. Item 1

  2. Item 2

  3. Item 3

8.2.2.5 Tabelas

:——– indica que a Coluna 1 está alinhada à esquerda, :————: indica que a coluna está centralizada. Alguns pacotes do R fornecem funções para a geração de tabelas a partir de data.frames e matrizes. Veja:

País      | Número de medalhas de ouro Tokyo 2021
:------------- | :-------------:
USA  | 39
China  | 38
Brasil | 7
Fonte: COI.
País Número de medalhas de ouro Tokyo 2021
USA 39
China 38
Brasil 7

Fonte: COI.

É possível usarmos ferramentas online para gerar tabelas em Markdown (Table Generator).

Podemos também criar uma tabela por meio da função kable do pacote knitr.

No relatório irá aparecer:

pais ouro
USA 39
China 38
Brasil 7

8.2.2.7 Equação

É possível incluirmos equações nos textos.

O modelo de regressão linear simples é dado por: $y_i = \alpha + \beta x_i + e_i, i = 1, \ldots, n.$

No relatório irá aparecer:

O modelo de regressão linear simples é dado por: \(y_i = \alpha + \beta x_i + e_i, i = 1, \ldots, n.\)

Ou ainda:

A função densidade é dada por: $$f(x) = \frac{\lambda e^{-\lambda x}}{x!}, x = 0, 1, \ldots.$$

No relatório irá aparecer:

A função densidade é dada por: \[f(x) = \frac{\lambda e^{-\lambda x}}{x!}, x = 0, 1, \ldots.\]

8.2.3 Opções de chunk

Os chunks de códigos ({r, …}) possuem uma série de argumentos que manipulados apropriadamente nos rendem diferentes saídas, isto é, podemos omitir o código, podemos omitir o resultado do código, entre outras. Elencaremos aqui as principais. Para a lista completa, veja este link.

Opção Valor Padrão Descrição
eval TRUE Indica se o código deve ser executado
include TRUE Indica se o código deve ser exibido no documento final. Os resultados não serão apresentados.
collapse FALSE Indica se o código e os resultados do chunk devem ser colapsados em um bloco único.
echo FALSE Indica se o código será exibido no documento final. Os resultados serão apresentados.
error TRUE Indica se mensagens de erros serão exibidas.
message TRUE Indica se mensagens geradas pelo código serão exibidas.
warning TRUE Indica se avisos gerados pelo código serão exibidos.
fig.cap NULL Título de gráfico referente ao chunk.
fig.height 7 Altura para gráficos criados pelo código (em polegadas).
fig.width 7 Largura para gráficos criados pelo código (em polegadas).

8.2.4 Temas para R Markdown

É possível acrescentar temas já definidos para deixarmos os relatórios mais atrativos visualmente.

Vamos modificar o YAML do nosso arquivo .Rmd. A seguir iremos apresentar alguns temas.

---
title: "RMarkdown temas"
author: "Jony Arrais"
date: "2023-03-27"
output:
  prettydoc::html_pretty:
    theme: cayman
    highlight: github
---

Seu relatório terá o seguinte formato:

---
title: "RMarkdown temas"
author: "Jony Arrais"
date: "2023-03-27"
output:
  prettydoc::html_pretty:
    theme: architect
    highlight: github
---

Seu relatório terá o seguinte formato:

---
title: "RMarkdown temas"
author: "Jony Arrais"
date: "2023-03-27"
output:
  prettydoc::html_pretty:
    theme: leonids
    highlight: github
---

Seu relatório terá o seguinte formato:

8.3 Desafio

Construa um relatório para a base cases-brazil-cities-time_2022.csv, contendo as seguintes análises:

  1. Um gráfico contendo a curva de casos por semana epidemiológica para o município de Fortaleza, considerando todas as semanas epidemiológicas disponíveis.

  2. O número total de mortes e de casos para os estados da região Sul (PR, SC e RS) no ano de 2022.

  3. Escreva um parágrafo apresentando a média de novos casos por mês e a mediana de novas mortes por mês para o estado de São Paulo.

  4. Escolha uma cidade e crie um gráfico de linhas apresentando o total de óbitos por 100.000 habitantes de casos acumulados no final de cada mês ao longo do ano de 2022.

  5. Compare os novos casos de COVID-19 diariamente no mês de agosto nas cidades Niterói/RJ e Rio de Janeiro/RJ.