Módulo 5 Apresentação de dados com relatórios

library(tidyverse)

R Markdown, ou simplesmente rmarkdown, é a ferramenta perfeita para transformar suas análises em documentos, relatórios, apresentações e até mesmo dashboards de alta qualidade e de maneira programática. Foi desenvolvida para facilitar a reprodução de resultados, visto que tanto código quanto narrativa estão no mesmo documento, e os resultados são automaticamente gerados do código presente no documento.

Com R Markdown, é possível:

Compilar um documento em um relatório em diferentes formatos de saída, como PDF, HTML e Word.
Produzir slides para apresentações.
Criar dashboards interativas, com layouts atraentes e que se adaptam à tela do usuário.
Criar relatórios interativos com Shiny.
Escrever artigos científicos ou livros.
Criar blogs ou sites.

Referências:
Cheatsheet do R Markdown
Guia de referência do R Markdown
Site oficial sobre R Markdown
Livro oficial sobre R Markdown

5.1 Primeiros passos com R Markdown

No Rstudio, acesse os menus File > New File > R Markdown… e clique em OK para criar um novo documento R Markdown com formato HTML. Você verá o seguinte documento:

Na imagem acima, podem ser vistos os três componentes básicos de um documento R Markdown:

Metadados, escritos no cabeçalho entre o par de três traços (—). A sintaxe para o cabeçalho segue a sintaxe YAML;
Texto (partes em branco no exemplo), que segue a sintaxe Markdown;
Código (partes nos blocos em cinza, chamados chunks), que segue a sintaxe da linguagem especificada no cabeçalho do bloco (por padrão é R).

Um chunk de código é criado por um par de três aspas, como em ```{r}, onde r indica a linguagem do código.

5.2 Resumo da sintaxe Markdown

2.5 Markdown syntax

O R Markdown, como visto, pode ser usado como editor de textos, que seguem a sintaxe da linguagem Markdown

5.2.1 Formatação de texto

Os principais tipos de formatação de texto em Markdown e suas respectivas sintaxes são:

Textos em itálico são produzidos com um par de asteriscos *Itálico* ou de underscores _Itálico_
Textos em negrito são produzidos com dois pares de asteriscos :**Negrito**
Um par de acentos til produz texto subscrito: CO~2~ vira CO₂
Um par de acentos circunflexos produz texto sobrescrito: x^2^ vira x²
Hyperlinks são criados com a sintaxe [texto](link): Clique [aqui](https://www.google.com/) vira Clique aqui
Imagens são inseridas com a sintaxe ![texto opcional](pasta/imagem.jpg) ou ![texto opcional](link para imagem)

5.2.2 Cabeçalhos

Cabeçalhos de capítulos (seções) e subcapítulos são criadas de maneira hierárquica, de acordo com a quantidade de jogos-da-velha usados. Quanto maior o número, menor a hierarquia:

# Cabeçalho do Nível 1

## Cabeçalho do Nível 2

### Cabeçalho do Nível 3

Mais links para aprender mais sobre a linguagem Markdown:
* https://blog.da2k.com.br/2015/02/08/aprenda-markdown/
* https://github.com/luongvo209/Markdown-Tutorial/blob/master/README_pt-BR.md

5.3 Chunks

Chunks são os blocos de código que são executados quando o documento é compilado. É possível criar um novo chunk no menu Insert > R ou usando o atalho Ctrl + Alt + I.

Qualquer tipo de output pode ser produzido a partir de um chunk, como textos, tabelas ou gráficos. Caso seja necessário ter um controle maior sobre os outputs, podem ser usadas opções no cabeçalho do chunk, como no exemplo abaixo:

```{r nome-opcional-do-chunk, fig.height=7, fig.width = 11, warning = FALSE}

Com as opções acima, configuramos as dimensões de altura e largura do gráfico de output e definimos que mensagens do tipo warning (como quando o ggplot2 avisa que dados NA foram descartados) não serão mostradas no documento final.

São várias as opções de chunks. Algumas das principais são:

eval: tipo logical. Executar (TRUE) ou não (FALSE) o código do chunk.
echo: tipo logical. Incluir o código do chunk ou não no documento compilado.
warning, message e error: tipo logical. Caso error = TRUE, o documento será compilado mesmo que o chunk retorne um erro.
include: tipo logical. Controla se o chunk e o output estarão presentes no documento final.
cache: tipo logical. Controla se o chunk poderá usar cache para criar uma pasta com arquivos cacheados. Útil para chunks de códigos que levam muito tempo para rodar.

Caso você deseje que uma opção seja definida da mesma maneira para todos os chunks do documento, como para definir um tamanho padrão para os gráficos, você pode criar um chunk global no início do documento e definindo essas opções na função knitr::opts_chunk$set(), como no exemplo abaixo:

markdown{r, setup, include=FALSE} knitr::opts_chunk$set(fig.width = 8, collapse = TRUE) ```

Referências:
* Documentação completa das opções de chunks

5.4 Formatos de output

Os principais formatos, que podem ser categorizados em documentos ou apresentação, são:

beamer_presentation
html_document
ioslides_presentation
pdf_document
slidy_document
powerpoint_presentation
word_document

Cada formato de output aceita diversas opções de customização, como incluir sumário, numerar capítulos, o tema, etc. Para conhecer todas as opções de um formato de output, recomenda-se ler a documentação da respectiva função, como ?rmarkdown::html_document.

As opções do formato de output podem ser definidas no YAML do documento, como no exemplo abaixo:

output:
  html_document:
    toc: true
    number_sections: yes
  pdf_document:
    keep_tex: true

5.5 Compilando um documento rmarkdown

Após escrever o texto e criar o código desejados, o documento pode ser compilado usando o botão Knit no Rstudio ou com o atalho Ctrl + Shift + K. Ambos são um atalho para a função rmarkdown::render(). Com isso, o documento será compilado no formato de output especificado no YAML e será criado um arquivo com o mesmo nome na mesma pasta do arquivo .Rmd.

5.6 Produzindo tabelas no R Markdown

Existem três boas opções para produzir tabelas elegantes em documentos R Markdown:

A função knitr::kable()

iris %>% 
  head() %>% 
  knitr::kable()

Sepal.Length	Sepal.Width	Petal.Length	Petal.Width	Species
5.1	3.5	1.4	0.2	setosa
4.9	3.0	1.4	0.2	setosa
4.7	3.2	1.3	0.2	setosa
4.6	3.1	1.5	0.2	setosa
5.0	3.6	1.4	0.2	setosa
5.4	3.9	1.7	0.4	setosa

A função formattable::formattable():

iris %>% 
  head() %>% 
  formattable::formattable()

Sepal.Length	Sepal.Width	Petal.Length	Petal.Width	Species
5.1	3.5	1.4	0.2	setosa
4.9	3.0	1.4	0.2	setosa
4.7	3.2	1.3	0.2	setosa
4.6	3.1	1.5	0.2	setosa
5.0	3.6	1.4	0.2	setosa
5.4	3.9	1.7	0.4	setosa

A função knitr::kable() acompanhada do pacote kableExtra:

iris %>% 
  head() %>% 
  kableExtra::kable()

Sepal.Length	Sepal.Width	Petal.Length	Petal.Width	Species
5.1	3.5	1.4	0.2	setosa
4.9	3.0	1.4	0.2	setosa
4.7	3.2	1.3	0.2	setosa
4.6	3.1	1.5	0.2	setosa
5.0	3.6	1.4	0.2	setosa
5.4	3.9	1.7	0.4	setosa

Tabelas interativas com o pacote DT:

iris %>% 
  head() %>% 
  DT::datatable()

Referências: Tutorial do pacote kableExtra
Tutorial do pacote formattable
Mais um tutorial do pacote formattable
Site do pacote

5.7 Relatórios parametrizados

Uma excelente maneira de automatizar processos de geração de relatórios para diferentes variáveis é utilizando o recurso de parametrização de relatórios. Alguns exemplos de quando esse tipo de situação é útil:

Mostrar resultados apenas para um específico departamento de uma empresa, gerente, ou região geográfica.
Rodar um relatório que cobre um período de tempo específico.
Controlar globalmente algumas opções do documento, como a presença ou não do código no documento final.

5.7.1 Declarando parâmetros

Parâmetros são introduzidos e especificados usando o campo params dentro do YAML, como no exemplo abaixo:

---
title: Relatório Semestral
output: html_document
params:
  ano: 2018
  estado: SP
  arquivo: vendas.csv
---

5.7.2 Usando os parâmetros

Após a definição dos parâmetros, é criada na sessão R um objeto do tipo lista chamado params, que contem as variáveis e seus valores definidos no YAML. Para acessá-los, basta usar a sintaxe padrão de uma lista:

params$ano
params$estado

Para compilar um relatório com parâmetros definidos, a melhor maneira (num ponto de vista programático) é usar a função rmarkdown::render() definido o argumento params.

Por exemplo, suponha que criamos um documento com o YAML anterior e o salvamos no arquivo meu_relatorio.Rmd. Para compilar o documento e produzir o output final com os devidos parâmetros, usaríamos a seguinte sintaxe:

rmarkdown::render("meu_relatorio.Rmd", params = list(
  ano = 2018,
  estado = RJ
))

Note que não foi necessário definir um valor para o parâmetro arquivo pois já existe um valor default definido no YAML.

5.8 Projeto final

Vamos simular uma situação muito comum em organizações:

Você é cientista de dados na ONU e lhe foi pedido para elaborar um relatório descritivo de algumas estatísticas por países de cada continente (sem Oceania). Contudo, você deve elaborar um relatório contendo apenas dados de cada continente, criando um arquivo separado para cada.

Crie um novo arquivo .Rmd chamado relatorio_onu.Rmd
No YAML do relatório, acrescente o parâmetro continente_relatorio.
Crie um relatório que execute estas tarefas:

Carregue os pacotes tidyverse e gapminder, do pacote gapminder. Use data(gapminder).
Filtre o continente definido no parâmetro e salve no objeto chamado df_relatorio.
Crie um chunk com histograma da expectativa de vida dos países no ano de 2007.
Crie um chunk com um gráfico de linha mostrando a mediana do PIB per capita do continente por ano.
Crie um chunk com um gráfico de colunas mostrando os 10 piores países em PIB per capita em 2007. Ordene as colunas em função do PIB per capita e inverta os eixos do gráfico.
Crie um chunk com uma tabela mostrando os 10 países mais populosos em 2007.

Salve e feche o relatório. Abra um novo arquivo R script.
Carregue o dataset gapminder, extraia os nomes dos continentes presentes no dataset, salve em um vetor e exclua a Oceania (você pode usar a função stringr::str_remove() para isso). Lembre de converter o vetor de continentes para character.
Use a função rmarkdown::render() especificando o continente em params. Crie um for loop para gerar um relatório para cada continente, salvando com o respectivo nome.

5.9 R Markdown

This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see http://rmarkdown.rstudio.com.

When you click the Knit button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:

summary(cars)

##      speed           dist       
##  Min.   : 4.0   Min.   :  2.00  
##  1st Qu.:12.0   1st Qu.: 26.00  
##  Median :15.0   Median : 36.00  
##  Mean   :15.4   Mean   : 42.98  
##  3rd Qu.:19.0   3rd Qu.: 56.00  
##  Max.   :25.0   Max.   :120.00

5.10 Including Plots

You can also embed plots, for example:

Note that the echo = FALSE parameter was added to the code chunk to prevent printing of the R code that generated the plot.