RMarkdown: O mínimo que você precisa saber
Estatísticos, Analistas de Dados e Cientistas de Dados atuam com dados, seja explorando-os para entender fenômenos, seja para orientar tomadas de decisão ou conceber produtos de dados.
Em meio à infinidade de características perseguidas por esses profissionais uma das soft skills (competências relacionadas ao comportamento do indivíduo, como o pessoal da Solides define) mais valorizadas é a capacidade de comunicação.
Você deve perseguir uma query eficiente, insights de negócio ou um modelo assertivo. Mas… não explicar a abstração do que você pensou, possíveis conclusões ou limitações das suas análises são limitantes enormes para um trabalho colaborativo e que exija o entendimento de outros.
Não tenho propriedade para discutir aqui comunicação em sentido amplo, mas posso falar da ferramenta/habilidade mais útil no meu processo de documentação, repasse e divulgação. Há anos, inclusive. Profissional e academicamente. Uso Markdown todos os dias e sei que no processo árduo de criação e registro a energia deve ser dispensada ao objetivo final, sendo imprescindível que a ferramenta seja flexível, fácil e convidativa a leitura.
O Markdown é uma linguagem pensada para a escrita de textos em que são criadas marcações para títulos, links, códigos de um modo conciso e legível. É tão legível que está hoje ao alcance de pessoas que não desenvolvem para ‘web’ como eu e você, possivelmente.
Todos os testes feitos abaixo foram reproduzidos no RStudio Cloud. Temos um tutorial de como usá-lo aqui.
“Prepara! Que agora é a hora”
Para começar é bem simples: No RStudio Cloud vá na barra superior. Clique em: File > New File > RMarkdown.
Caso você nunca tenha aberto essa opção antes, é possível que surja uma tela para instalação de alguns pacotes, basta clicar em sim e esperar.
Após isso, uma tela “New R Markdown” vai aparecer.
Eu selecionei a opção HTML porque faremos gráficos iterativos e adicionei o título desse documento e o meu nome como autora.
No editor do RStudio Cloud aparecerá, como de costume, um documento Untitled com o símbolo RMD à esquerda.
Esse arquivo eu salvei como index, com extensão Rmd.
O RStudio Cloud criou um template, um padrão basicão.
Nos cursos Básico e Intermediário usamos o Desafio do SQL Murder Mystery, então irei usá-lo novamente para esse tutorial.
Não faremos conexão com banco de dados nesse post então a leitura de dados será a partir de planilhas. Acesse esse repositório e faça download do arquivo sql_murder_mystery-master.zip.
No RStudio Cloud, do lado direito da tela, clique no botão Upload.
Clique em Escolher Arquivo e selecione o arquivo .zip que você baixou. Clique em ok.
O arquivo será carregado no RStudio Cloud:
Execute o comando list.files(). Na prática, você vai ficar com os seguintes arquivos:
Se você estiver fazendo o processo acima no RStudio IDE (o instalado no seu computador), você precisará definir um diretório de trabalho e colocar os arquivos descompactados dentro desse diretório. Caso você não saiba como definir Diretórios de Trabalho, nosso canal do Youtube tem um vídeo explicando como fazer isso.
Começando (real)
Para não nos confundirmos eu apaguei todo o código abaixo do cabeçalho.
Após isso, esbocei a estrutura macro do documento em Markdown. É como se eu tivesse pensado nos capítulos da história dessa análise, nomeando-os na mais alta hierarquia do texto. Para isso, eu usei # (uma hashtag).
---
title: "SQL Murder Mystery"
author: "seu_nome"
date: "03/07/2020"
output: html_document
---# Problema# Investigação# Referências# Contato
Como já fizemos essa análise antes, eu sei quais sub-divisões cabem a cada parte desse texto. Então vou inserir o equivalente a seções desse texto “descendo” um nível na hierarquia da linguagem Markdown, marcando com ## (duas hashtags).
---
title: "SQL Murder Mystery"
author: "seu_nome"
date: "01/07/2020"
output: html_document
---# Problema## Etapas## Descrição da Base# Investigação## Leitura de Dados## O assassino!# Referências# Contato
E só para reforçar vou inserir mais níveis e sub-divisão, o equivalente a sub-seções e subsub-seções, com as marcações ### e ####:
---
title: "SQL Murder Mystery"
author: "seu_nome"
date: "01/07/2020"
output: html_document
---# Problema## Etapas## Descrição da Base# Investigação### 01) Cena do Crime### 02) Quem são as Testemunhas?#### Primeira testemunha#### Segunda testemunha### 03) O que as Testemunhas falaram?### 04) Álibi## O assassino!# Referências# Contato
Aperte o botão knitr (ou ctrl + alt + k).
Nesse momento, a estrutura do texto fica definida de modo mais claro.
Contextualize, explique, conceitue: Tá fácil!
Ainda sobre texto vamos inserir a descrição desse problema. Como vai ser apenas texto tá fácil! Basta digitar. Para dar destaque para as informações mais relevantes do crime (tipo, cidade e data) vou demarcá-las em negrito, “cercando-as” com o marcador ** (dois asteriscos).
---
title: "SQL Murder Mystery"
author: "seu_nome"
date: "01/07/2020"
output: html_document
---# Problema"Aconteceu um crime e o detetive precisa da sua ajuda.
Você sabe que trata-se de um **assassinato** na **SQL City**,
ocorrido em **15 de Janeiro de 2018**.
Recupere o relatório da cena do crime do banco de dados do Departamento de Polícia, onde estão todos os detalhes necessários para investigar o mistério."## Etapas
Liste, ordene: Apresentar com clareza é o must have
As etapas de investigação podem ser descritas na ordem em que ocorrem para orientar o leitor/usuário/cliente. Vamos criar esses tópicos ordenando os passos de análise. Demarcarmos com as numerações ‘1. ’, ‘2. ’, sucessivamente.
## Etapas1. Cena do Crime
2. Testemunhas
3. Depoimentos
4. Investigação
Uma imagem vale mais que 1000 palavras e… quase nada de sintaxe
Para documentar a base com mais detalhes vamos adicionar o schema da base, uma representação visual de como as tabelas se relacionam. Ela é uma imagem, retirada do site original e vamos adicioná-la com sintaxe markdown: (  ).
## Descrição da Base# Investigação
Uma narrativa orientada por dados
E vamos ler e analisar os dados? Como para isso precisamos de funções do R vamos usar chunks. Ou seja, trechos de códigos que serão exatamente como no R.
Antes de começar a investigação propriamente dita, vamos ler os dados. Essa etapa corresponde às linhas demarcadas entre ```. Como estamos usando o R para analisar os dados, o chunk declara isso seguido de um nome (optativo) identificador do chunk (```{r leituraDados}). No primeiro trecho são (01) carregados e instalados pacotes de interesse, (02) carregados dados iniciais (cs) e (03) o ajuste da variável de data. Veja que é sintaxe do R, puramente.
Em uma análise de dados, é comum que a gente faça referência a objetos criados nas análises, ou seja, em R. Por exemplo, quando você justifica que vai excluir uma variável de uma regressão linear porque ela é altamente correlacionada com outra. Nesse caso, você, quase certamente, explicita o valor encontrado para a medida dentro de uma sentença no texto. Para isso também são utilizados chunks mas eles ficam embutidos (embedded, em inglês) no texto sendo chamados com uma expressão do tipo: `r seu_codigo_em_r`.
## Descrição da Base```{r leituraDados}
if (!require("pacman")) install.packages("pacman")
if (!require("dplyr")) install.packages("dplyr")
if (!require("plotly")) install.packages("plotly")
if (!require("lubridate")) install.packages("lubridate")
if (!require("DT")) install.packages("DT")
pacman::p_load(dplyr, plotly, lubridate, DT)diret <- "data"cs <- read.csv(file = file.path(diret, "crime_scene_report.csv"),
stringsAsFactors = FALSE)# Ajuste nas datas
cs <- cs %>%
mutate(ano_mes = substring(text = date, first = 1, last = 6),
date_compl = lubridate::ymd(date))
```
```{r quantDiversDados}
## quantidades de dadosdesc <- cs %>%
summarise(n_date = n_distinct(date),
n_ano_mes = n_distinct(ano_mes),
n_type = n_distinct(type),
n_desc = n_distinct(description),
n_city = n_distinct(city),
min_date = min(date),
max_date = max(date))
```Nesse Departamento de Polícia constam informações sobre `r nrow(cs)` ocorrências, de `r desc$n_type` tipos diferentes, entre `r desc$min_date` e `r desc$max_date`.
Gráficos. Eu quero gráficos.
E como não poderia faltar, vou incluir dois chunks: com gráfico e com tabela. Um gráfico iterativo (ainda não é o mais lindo mas pode ficar!) com a evolução do número de ocorrências por tempo e uma tabela com formatação limpa com as descrições das cenas de crime:
```{r quantDiversDados}
## quantidades de dadosdesc <- cs %>%
summarise(n_date = n_distinct(date),
n_ano_mes = n_distinct(ano_mes),
n_type = n_distinct(type),
n_desc = n_distinct(description),
n_city = n_distinct(city),
min_date = min(date),
max_date = max(date))
```Nesse Departamento de Polícia constam informações sobre `r nrow(cs)` ocorrências, de `r desc$n_type` tipos diferentes, entre `r desc$min_date` e `r desc$max_date`.Observe abaixo a evolução do número de ocorrências no tempo:```{r lineplot}evt_per_day <- cs %>%
group_by(date_compl) %>%
tally() %>%
ungroup()evt_per_day <- data.frame(
date_compl = seq(from = min(cs$date_compl),
to = max(cs$date_compl),
by = "day")
)%>%
left_join(evt_per_day) %>%
mutate(n = ifelse(is.na(n), 0, n))library(plotly)plot_ly(evt_per_day,
x = ~ date_compl, y = ~ n,
type = 'scatter', mode = 'lines+markers',
line = list(color = 'grey'),
showlegend = TRUE) %>%
layout(
title = "Crime occurrences by Day",
xaxis = list(title = "Date"),
yaxis = list(title = "Number of Occurrences"),
margin = list(l = 100)
)
```# Investigação### 01) Cena do Crime```{r descricao}
df_descrip <- cs %>%
filter(date == "20180115" & city == "SQL City" & type == "murder") %>%
select(description) %>%
mutate(description = as.character(description)) %>%
stringr::str_split(pattern = "\\..", simplify = TRUE) %>%
stringr::str_squish() %>%
tolower()%>%
as.data.frame()DT::datatable(df_descrip)
```
Referencie, cite: Fundamentar nunca é demais!
Vou aproveitar e referenciar a fonte de dados, colocando um link para a página do problema no respectivo ‘capítulo’. E inserir uma possibilidade de contato, adicionando um link para a página do Linkedin. Note que: a expressão que aparece no documento final é a que está contida entre colchetes ( [] ) e o link original fica entre parênteses ( ()) ).
# Referências[https://mystery.knightlab.com/](https://mystery.knightlab.com/)# Contato[linkedin/larissa-sayuri-santos/](https://www.linkedin.com/in/larissa-sayuri-santos/)
Não vou me estender adicionando chunk por chunk. Você já resolveu esse assassinato? Se não sugiro que o faça: é uma ótima forma de praticar! Se já sabe quem é o assassino… Faz um Markdown — simplão mesmo! — e marca o Rladies Belo Horizonte no insta e no linkedin!
“E agora, José?”
O RMarkdown parece muito flexível, né? Mas eu sei que essa versão passa longe de todo o potencial dessa ferramenta incrível. A versão com o que a gente fez até aqui fica assim:
A minha em Markdown — versão Simplão mas com a resolução completa do assassinato— tá aqui.
Algumas melhorias bem claras:
- Escolher quais chunks mostrar e o quê mostrar deles;
- Tratar as mensagens retornadas nos chunks;
- Inserir um índice lateral para facilitar a navegação;
- Usar um template bonitinho, com uma cor legal;
- Adicionar uma logo ou favicon;
- Adicionar citações;
- Acrescentar referências a sub-divisões do texto.
Algo mais parecido com isso daqui:
A ideia do post foi apresentar o Rmarkdown. Dar um “gostinho” da facilidade do seu uso.
Para saber mais… Vamos trocar uma ideia? Próximo dia 11 de Julho o Rladies BH promoverá um curso só de Markdown! Online pela Sympla Streaming, claro! Fica o meu convite. Para a gente fazer juntes um documento cheio de informação útil. Rápido. Fácil. Como deve ser!
Se você preferir tem materiais excelentes rolando por aí… Eu gosto muito do livro bookdown. Acho o mais completo! E se você for uma pessoa mais sucinta, talvez prefira esse cheatsheet.
