Curso
Relatórios com R Markdown
4 h
46K
Neste artigo, vamos explorar um pacote essencial e muito útil para ciência de dados que todo usuário de R precisa conhecer — o R Markdown. Você vai aprender o que é o R Markdown, quais benefícios oferece, para que é usado, como instalá-lo, quais recursos ele traz para trabalhar com código, texto e gráficos, qual sintaxe utiliza, quais são os formatos de saída de documentos em R Markdown e como gerar esses documentos e compartilhá-los com seus colaboradores.
Como o R Markdown é especialmente adaptado ao ambiente de desenvolvimento integrado (IDE) RStudio, vamos usar esse IDE ao longo do artigo. O tutorial de RStudio traz as orientações necessárias para instalar o RStudio e começar a usá-lo.
Vamos lá!
O que é R Markdown?
R Markdown é um pacote gratuito e de código aberto do R que oferece um espaço de trabalho para criar projetos de ciência de dados. Sua grande vantagem é permitir combinar código, texto e visualizações em um único documento refinado, compartilhável e totalmente reprodutível, que pode ser gerado em uma ampla variedade de formatos de saída, estáticos e interativos.
Entre os formatos de saída mais usados estão HTML, PDF, Microsoft Word, apresentações, aplicativos, sites, dashboards, relatórios, templates, artigos, livros e muito mais.
Além disso, o R Markdown facilita o controle de versão e dá suporte a várias linguagens de programação além de R, incluindo Python e SQL.
Se quiser se aprofundar na criação de relatórios dinâmicos com R Markdown, o curso Reporting with R Markdown é o ponto de partida ideal.
Instalando o R Markdown
Ao usar R Markdown fora do RStudio, a instalação é como a de qualquer outro pacote do R a partir do repositório CRAN (Comprehensive R Archive Network):
install.packages("rmarkdown")Depois de instalar, é preciso carregar o pacote no ambiente de trabalho do R:
library(rmarkdown)Já ao trabalhar com R Markdown dentro do RStudio — como faremos neste tutorial — não é necessário instalar e carregar explicitamente o pacote rmarkdown. Ao clicar em File — New File — R Markdown na barra de menu do RStudio, um novo documento R Markdown será aberto. Nessa etapa, você pode receber a notificação Install Required Packages, como abaixo:
Após confirmar a instalação dos pacotes necessários, na nova janela pop-up, informe o título do documento e o nome do autor (ambos opcionais, mas recomendados), mantenha as demais configurações e clique em OK:
Documento padrão do R Markdown
Na seção anterior, abrimos um novo documento R Markdown no RStudio. Ele aparece assim:
Note que ele inclui o título, o nome do autor, a data atual e o formato de saída padrão que definimos na janela pop-up ao abri-lo. Em seguida, há alguns exemplos da sintaxe básica usada no R Markdown, como adicionar e formatar trechos de código (code chunks), inserir cabeçalhos, links, ênfases no texto e gerar gráficos.
Vamos analisar com mais detalhes várias funcionalidades do R Markdown e sua sintaxe. Por ora, salve esse arquivo padrão e depois gere o documento no formato de saída selecionado (no nosso caso, HTML) para ver como fica.
Para salvar o arquivo, clique em File — Save As... na barra de menu do RStudio.
OBS: o nome do documento R Markdown que informamos antes não é o mesmo que o nome do arquivo. É preciso salvar o arquivo no diretório do projeto e, depois, lembrar de salvá-lo regularmente (File — Save) enquanto trabalha nele.
Para gerar o arquivo salvo no formato de saída escolhido (HTML), clique em Knit na barra de ferramentas do arquivo:
Veja como nosso documento R Markdown padrão fica em HTML:
Formatação de texto no R Markdown
Com frequência, o texto é a maior parte de um projeto de ciência de dados. Por isso, é importante saber como formatá-lo no R Markdown para que fique fácil de ler, eficiente e envolvente.
Se você quer aprender a usar R para análise e ciência de dados e desenvolver suas habilidades tanto de programação em R quanto de ciência de dados, confira estas trilhas de carreira para iniciantes e completas:
Cabeçalhos
Você pode adicionar diversos níveis de cabeçalhos ao documento R Markdown usando o símbolo #. A sintaxe é:
# Cabeçalho 1 (título principal)
## Cabeçalho 2 (seção)
### Cabeçalho 3 (subseção)
etc.
Ao gerar o documento, os cabeçalhos ficam assim:
Ênfase no texto
O R Markdown permite adicionar diferentes tipos de ênfase ao texto, como itálico, negrito, tachado, sobrescrito e subscrito, por exemplo:
- *itálico* ou _itálico_
- **negrito** ou __negrito__
- ~~tachado~~
- texto^sobrescrito^
- texto~subscrito~
Veja abaixo como esses estilos aparecem no documento gerado:
Listas
Para criar uma lista não ordenada, você pode usar uma destas três sintaxes:
* Item 1* Item 2* Item 3
ou:
- Item 1- Item 2- Item 3
ou:
+ Item 1+ Item 2+ Item 3
Em todos os casos, o resultado gerado será o mesmo:
Para criar uma lista ordenada, use a seguinte sintaxe:
1. Item 12. Item 23. Item 3
O resultado será semelhante, com indentação antes de cada número.
Observe que, se você deletar um item de uma lista numerada, adicionar um novo item ou errar algum número (por exemplo, escrever 20. em vez de 2. no exemplo acima), a numeração será corrigida automaticamente e exibida como deveria:
Citações em bloco
Para criar uma citação em bloco, use o símbolo > antes do primeiro caractere do texto a ser citado:
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam hendrerit nisi sed sollicitudin pellentesque. Nunc posuere purus rhoncus pulvinar aliquam. Ut aliquet tristique nisl vitae volutpat. Nulla aliquet porttitor venenatis. Donec a dui et dui fringilla consectetur id nec massa. Aliquam erat volutpat. Sed ut dui ut lacus dictum fermentum vel tincidunt neque.
Isso será gerado assim:
Adicione uma linha vazia após a citação para encerrá-la.
Links
Se quiser incluir um link como caminho direto, coloque o endereço entre os símbolos < e >. Por exemplo, a construção:
será gerada como:
Já para ancorar um link a uma palavra ou pequeno trecho de texto, use a sintaxe a seguir (usando o Google como exemplo):
[Google](https://www.google.com/)
Isso será exibido como:
Imagens
Para inserir uma imagem no texto, use um dos caminhos abaixo:
- Para adicionar uma imagem da Internet:
- Se o arquivo da imagem estiver salvo na pasta do projeto (onde está o documento R Markdown):
- Se o arquivo da imagem estiver no seu computador, mas fora da pasta do projeto:
O texto alternativo (alt text) descreve brevemente o que aparece na imagem e é exibido quando, por algum motivo, o usuário não consegue vê-la na página.
Vamos ver o primeiro caso em ação com uma imagem do Pixabay, cujo URL é https://cdn.pixabay.com/photo/2018/12/02/10/07/web-3850917_1280.jpg:
Ao gerar o documento, a imagem é exibida:
Quebras
Existem vários tipos de quebras no R Markdown:
- Quebra de linha — para iniciar uma nova linha. Feita ao terminar a linha anterior com uma barra invertida (\).
- Quebra de parágrafo — para iniciar um novo parágrafo. Feita ao terminar o parágrafo anterior com dois espaços.
- Quebra de slide — para iniciar um novo slide nos formatos de apresentação baseados em slides ou uma nova seção nos demais formatos. Feita inserindo uma régua horizontal (***) no documento.
- Quebra de página — para iniciar uma nova página, quando o formato de saída comporta isso (ex.: Microsoft Word). Feita inserindo o comando \newpage no documento.
Vamos colocar em prática os três primeiros tipos. Abaixo está um trecho de Lorem ipsum com símbolos de quebra do R Markdown adicionados:
Lorem ipsum dolor sit amet, consectetur adipiscing elit.\Nam hendrerit nisi sed sollicitudin pellentesque.
Nunc posuere purus rhoncus pulvinar aliquam.
***
Ut aliquet tristique nisl vitae volutpat.
Veja como isso é gerado em um documento HTML:
Lorem ipsum dolor sit amet, consectetur adipiscing elit.Nam hendrerit nisi sed sollicitudin pellentesque.
Nunc posuere purus rhoncus pulvinar aliquam.
Ut aliquet tristique nisl vitae volutpat.
Formatação e execução de código no R Markdown
Código é outro componente essencial de qualquer projeto de ciência de dados. No R Markdown, você pode executar código (não apenas em R), exibir o código e sua saída, mostrar só o código e ocultar a saída, mostrar apenas a saída e ocultar o código-fonte e muito mais.
A trilha de carreira para iniciantes R Programmer e a trilha de habilidade R Programming são ótimos recursos para aprender, praticar e aprimorar suas habilidades de código em R.
Code chunks
Para formatar e executar um bloco de código em R no R Markdown, envolva-o por três crases, sendo que as primeiras três crases são seguidas por r entre chaves. Exemplo:
```{r}
print("Hello, World!")
```Se você gerar o documento sem executar o código, o code chunk aparecerá assim:
Linguagem do código
Ao trabalhar com R Markdown, você não fica limitado ao R, já que o pacote também suporta muitas outras linguagens. Para executar um trecho em outra linguagem, informe o nome dessa linguagem no lugar de R entre chaves. Além disso, pode ser necessário instalar e carregar pacotes adicionais no ambiente do R.
Por exemplo, para usar Python no R Markdown, é preciso instalar e carregar o pacote reticulate, que permite comunicação bidirecional (como criar e acessar variáveis) entre Python e R no mesmo documento R Markdown.
Vamos reescrever o trecho da seção anterior em Python (depois de instalar e carregar o reticulate):
```{python}
print("Hello, World!")
```
Execução de code chunks
Para executar um code chunk (ou linhas selecionadas) ao trabalhar com R Markdown no RStudio, clique no botão Run na barra de ferramentas do documento e selecione a opção desejada na lista:
Na imagem acima, você vê que cada opção de execução tem seu atalho, que pode ser usado sem abrir o menu sempre.
Nomeando code chunks
Embora não seja obrigatório, é uma boa prática nomear os code chunks. Isso ajuda em vários casos: referenciar trechos ao longo do documento, depurar código, alternar entre chunks etc. Nomear torna-se especialmente importante em documentos longos com muitos chunks.
Adicione o nome do chunk entre chaves, logo após o nome da linguagem, separado por um espaço. O nome não pode conter espaços.
No exemplo abaixo, adicionamos o nome hello_world ao chunk:
```{r hello_world}
print("Hello, World!")
```Opções de code chunk
As opções de chunk permitem controlar avaliação do código, saída, decoração, cache, animação (quando aplicável) e gráficos (quando aplicável) — tudo isso para cada chunk individual. Você pode adicionar várias opções ao mesmo chunk. Em termos de sintaxe, coloque as opções entre chaves logo após o nome do chunk (se houver; caso contrário, após o nome da linguagem), separando por vírgulas.
Há muitas opções disponíveis no R Markdown. Cada uma tem um valor padrão, mas, quando decidimos usá-las, geralmente queremos um valor diferente. Veja as opções mais populares e valores que podem nos interessar:
echo=FALSE— o código não será exibido no documento final, apenas sua saída.eval=FALSE— o código dentro do chunk não será executado.include=FALSE— o chunk será executado, mas não incluído no documento final.results— o padrão é "markup"; outros valores:- "hide" — a saída do código ficará oculta no documento final
- "hold" — a saída será mostrada somente após todo o chunk ser executado
- "asis" — a saída do código será passada sem reformatar.
message=FALSE— mensagens produzidas pelo código não serão exibidas.error=FALSE— erros produzidos pelo código não serão exibidos.warning=FALSE— avisos produzidos pelo código não serão exibidos.highlight=FALSE— o código não será destacado no documento final.prompt=TRUE— o símbolo > será adicionado ao início de cada linha de código exibida no documento final.
Abaixo estão alguns exemplos de code chunks que foram executados no RStudio e depois gerados no documento final:
Código no R Markdown:
Saída no documento final:
Código inline
Com código inline, você insere pequenos trechos de código diretamente no texto do documento R Markdown — eles serão executados e suas saídas aparecerão embutidas no texto. A sintaxe é r <code>.
Veja um exemplo simples de texto com código inline:
There are `r 1+6` colors of the rainbow.
e como isso é exibido no documento final:
There are 7 colors of the rainbow.
Na prática, código inline é útil para agregar informações sobre os dados e ajuda a evitar erros que podem acontecer ao inserir números manualmente ou quando os dados mudam.
Plotando no R Markdown
Plotar no R Markdown significa executar código que gera gráficos. Portanto, tudo o que vimos até aqui sobre formatação e execução de código no R Markdown, exceto o código inline, também se aplica a gráficos. A principal diferença é que a saída será gráfica, não apenas texto e números.
A trilha de habilidade Data Visualization with R ajuda você a desenvolver as competências para analisar e visualizar dados em R e, assim, contar histórias melhores baseadas em dados.
Para personalizar gráficos no R Markdown, como no R "puro", use as ferramentas dos pacotes de visualização de dados do R, além da função plot() da base do R.
Já para controlar o comportamento dos gráficos em um documento R Markdown, você pode usar opções de chunk específicas para plotagem. A maioria é bem específica e, portanto, está fora do escopo deste guia introdutório. Vamos ver algumas opções básicas que ajudam ao plotar no R Markdown:
fig.show— o padrão é "asis"; outros valores:- "hide" — os gráficos serão gerados, mas não incluídos no documento final
- "hold" — os gráficos serão mostrados apenas após todo o chunk ser executado
- "animate" — todos os gráficos do chunk serão combinados em uma animação.
fig.width— largura do gráfico em polegadas; padrão: 7.fig.height— altura do gráfico em polegadas; padrão: 7.fig.align— alinhamento dos gráficos no documento final: "left", "center" ou "right".fig.cap— legenda da figura como uma string de caracteres.fig.path— caminho para o diretório onde os arquivos de gráfico criados pelo chunk devem ser salvos.fig.ext— extensão dos arquivos de gráfico criados pelo chunk.
A seguir, alguns exemplos de uso de chunks específicos para plotagem no R Markdown, incluindo o código-fonte e a saída gerada:
Código no R Markdown:
Saída no documento final:
Formatos de saída
Até agora, consideramos apenas o documento HTML (html_document) como formato de saída. No entanto, o R Markdown oferece muitos outros formatos, incluindo Microsoft Word, Microsoft PowerPoint, PDF, R notebooks interativos, dashboards etc.
Por exemplo, para criar documentos, os formatos disponíveis incluem html_document, pdf_document, word_document, github_document, html_notebook, html_vignette etc. Já para apresentações, você pode usar: powerpoint_presentation, ioslides_presentation, slidy_presentation e beamer_presentation.
Para definir o formato de saída do seu documento R Markdown, atribua o valor correspondente à opção output no cabeçalho do documento (também conhecido como cabeçalho YAML — yet another markup language). No nosso documento, o formato de saída está definido como html_document, que também é o padrão no R Markdown:
Para mudar, substitua html_document pelo formato desejado (pdf_document, word_document, powerpoint_presentation etc.). Agora, ao clicar em Knit na barra de ferramentas do arquivo, seu documento será gerado no formato escolhido.
Publicando documentos R Markdown
Para publicar um documento R Markdown, clique em File — Publish na barra de menu do RStudio e escolha onde deseja publicá-lo:
Depois, siga as instruções conforme sua escolha e clique em Publish. Pronto: seu documento está preparado para ser compartilhado com colaboradores.
Conclusão
Para fechar, neste artigo você viu como dar os primeiros passos com R Markdown. Definimos o que é e para que serve, falamos sobre como instalar, como formatar texto e seus componentes, como formatar e executar código, como gerar gráficos, quais formatos de saída o R Markdown oferece, como gerar um documento em um desses formatos e como publicar o documento final para compartilhamento com colegas.
Para praticar na prática o uso do R Markdown, confira nosso curso Reporting with R Markdown, que vai ajudar você a extrair insights dos dados e apresentar suas descobertas em PDF, arquivo HTML ou aplicativo Shiny.
Tópicos
