R Markdown é uma ferramenta que permite criar documentos dinâmicos misturando códigos de programação com texto em Markdown

Este é nosso quarto artigo da série sobre produção de documentos com Markdown, uma linguagem de marcação simples e muito útil para produzir praticamente qualquer tipo de documento técnico, acadêmico, para a Web, etc.

No primeiro artigo da série fizemos uma pequena introdução sobre linguagens de marcação, apresentamos as características principais do Markdown e sua sintaxe básica.

No segundo artigo da série apresentamos o Pandoc, que é um software gratuito e open-source conversor entre diversos tipos de linguagens de marcação e arquivos de texto, e que também possui a sua própria implementação Markdown.

No terceiro artigo da série apresentamos o Limarka, que é uma ferramenta capaz de gerar arquivos PDF de documentos acadêmicos, como artigos, dissertações e teses, em conformidade com as Normas da ABNT a partir de textos escritos em Markdown.

Neste texto iniciamos um artigo de duas partes sobre o R Markdown, que é uma ferramenta capaz de produzir documentos dinâmicos a partir da incorporação de trechos de código em R (e em outras linguagens de programação) em arquivo de texto com sintaxe Markdown.

Este texto se concentrará em apresentar o R Markdown e o RStudio, as instalações e dependências necessárias, e a estrutura básica do documento. No artigo seguinte, continuação deste, nos detemos no funcionamento e na estrutura do documento, sobretudo nas formas de inserção de código, configurações e interações, a partir de um exemplo prático.

Documentação com Markdown: Documentos dinâmicos com R Markdown 1/2

Sumário do artigo

Introdução

R Markdown é um arquivo com extensão .Rmd capaz de conter tanto texto simples com sintaxe de marcação Markdown quanto trechos de código funcionais de linguagens de programação, notadamente da linguagem R, mas também de outras linguagens, tais como Python, Julia, Shell, SQL, JavaScript, entre outras.

O R Markdown funciona a partir de um conjunto de pacotes e funcionalidades da linguagem R no software RStudio.

R

R é uma linguagem de programação de alto nível, interpretada, de script, de tipagem dinâmica forte, multiparadigma (com ênfase em programação funcional) voltada à manipulação, análise e visualização de dados.

A linguagem R é um conjunto gratuito e open-source. É uma linguagem de programação relativamente diferente das demais linguagens de programação, foi criada originalmente por Ross Ihaka e por Robert Gentleman, no departamento de Estatística da Universidade de Auckland, Nova Zelândia.

A linguagem R é utilizada principalmente por estatísticos e cientistas de dados para desenvolver softwares e sistemas de estatística e análise de dados. É a linguagem preferida na academia e é também uma das linguagens mais usadas na indústria para inteligência de dados, juntamente com a linguagem Python.

Neste texto não vamos nos aprofundar na estrutura da linguagem em si, o que não é estritamente necessário para compreensão e entendimento do funcionamento do R Markdown, nem mesmo para usufruir de grande parte de suas funcionalidades.

RStudio

O RStudio é um Ambiente de Desenvolvimento Integrado - IDE criado para a linguagem R, mas que em suas versões atuais também trabalha com outras linguagens.

O RStudio funciona como uma interface que torna o R - muito - mais amigável. O IDE inclui um console, um editor com realce de sintaxe que oferece suporte à execução direta de código, bem como ferramentas para plotagem, histórico, depuração e gerenciamento de espaço de trabalho.

RStudio é um empresa privada, que desenvolve alguns diferentes produtos, tanto em versões comerciais e pagas quanto em versões de código aberto e gratuitas. O RStudio Desktop Open Source Edition é totalmente gratuito e inclui basicamente todas as funcionalidades necessárias para uso pessoal, e é a versão que utilizaremos neste artigo (A versão Pro - e paga - do mesmo software possui funcionalidades adicionais que fazem sentido principalmente para clientes corporativos).

Além disso, também existe uma versão baseada na nuvem do RStudio chamada RStudio Cloud. O RStudio Cloud permite criar R Markdown sem instalar nenhum software, apenas com um navegador Web.

Pacotes

O R é mundialmente reconhecido por sua comunidade extremamente ativa e inclusiva. A linguagem é dotada de um poderoso ambiente de gerenciamento de “pacotes”.

Os pacotes - ou packages - consistem em um “empacotamento” de funções, arquivos de dados, arquivos de ajuda e eventualmente outros pacotes, que estendem as funções do R.

No ambiente R existem pacotes para as mais diversas finalidades.

Knitr

knitr é um mecanismo para geração de relatórios dinâmicos com R. É um pacote do R que permite a integração do código R em documentos LaTeX, LyX, HTML, Markdown, AsciiDoc e reStructuredText, a priori.

Algumas das extensões do knitr, por sua vez, incluem o formato R Markdown, além de cache, gráficos TikZ e suporte a outras linguagens como Python, Perl, C++, scripts Shell, CoffeeScript, e assim por diante.

O pacote knitr “executa” os “pedaços” - ou chunks - de código e renderiza um arquivo .md (Markdown) com os códigos e seus resultados (outputs).

O knitr é oficialmente suportado no IDE RStudio para R, LyX, Emacs / ESS.

O Knitr não precisa ser instalado ou carregado explicitamente, pois o RStudio já o inclui em sua instalação básica.

Rmarkdown

O pacote rmarkdown ajuda a criar documentos de análise dinâmica que combinam código, saída renderizada (como figuras) e texto em Markdown. O utilizador insere seus dados, código e narrativas, e o pacote inclui os mecanismos necessários para renderizar o conteúdo em um documento final bem acabado.

O pacote rmarkdown é uma espécie de extensão do Knitr e não precisa ser instalado ou carregado explicitamente, pois o RStudio fará isso automaticamente quando for necessário pela primeira vez, eventualmente requerendo apenas uma confirmação do usuário.

Pandoc

O Pandoc, conversor universal de documentos e formatos que apresentamos em nosso segundo artigo desta serie, é a ferramenta utilizada para converter o arquivo .md intermediário produzido pelo Knitr para a linguagem ou formato desejado, gerando o documento de saída escolhido (.html, .docx, .pdf, .odt, etc.).

O IDE RStudio já inclui uma versão “empacotada” do Pandoc em sua instalação básica, de modo que não é necessário instalá-lo separadamente.

Processo de renderização

A estrutura básica do fluxo de trabalho para um documento R Markdown é mostrada na Figura 1:

workflow-rmarkdown

Diagrama que ilustra como um documento R Markdown é convertido no documento final de saída

O documento R Markdown original é um arquivo .Rmd que contém uma combinação de YAML (metadados), texto com sintaxe Markdown e blocos de código de linguagens de programação.

A principal função para renderizar documentos R Markdown é a função render() (do pacote rmarkdown). A função render() é uma “wrapper” (poderíamos traduzir para “invólucro” ou algo assim) que internamente chama a função knit() (do pacote Knitr) e posteriormente converte o documento para o formato de saída utilizando o Pandoc.

Primeiro o knitr é usado para “executar” todo o código embutido no arquivo .Rmd e preparar a saída (output) deste código a ser exibida no documento final. Estes outputs são convertidos na linguagem de marcação e passam a estar contidos em um arquivo .md temporário intermediário.

Em seguida, o arquivo .md é processado pelo Pandoc, que leva em consideração quaisquer parâmetros especificados no cabeçalho YAML do documento (por exemplo: título, autor e data) para converter o documento para o formato de saída especificado no parâmetro próprio para isso (como html_document para saída HTML, por exemplo).

Se o formato de saída for PDF então há uma “camada adicional” de processamento, uma vez que o Pandoc converterá o arquivo .md intermediário em um arquivo .tex intermediário. Este arquivo é então processado pelo LaTeX (o MikTeX, ou outra distribuição) para gerar o documento PDF final.

Instalações necessárias

Para produzir documentos R Markdown as únicas instalações efetivamente necessárias de serem feitas de forma explícita são a da linguagem R e do software RStudio Desktop.

Instalação do R

A instalação do ambiente R é fácil de ser realizada em qualquer sistema operacional, embora requeira uma pequena jornada de “cliques”.

Primeiro deve-se acessar o site oficial do R. Na página inicial deve-se clicar em CRAN, na coluna à esquerda, abaixo da palavra download.

Então, na página denominada CRAN Mirrors, a Rede de Distribuição do R, há uma lista com links para diversos repositórios do R distribuidos pelo mundo. Pode-se escolher qualquer um, o conteúdo será o mesmo. Em tese, se escolher um repositório geograficamente mais próximo o download será mais rápido.

Após clicar no link do repositório escolhido deve-se clicar no link referente ao sistema operacional utilizado, os links estarão bem visíveis, no meio e no alto do site, no quadro “Download and Install R”.

Depois disso, pelo menos no Windows, abre-se uma nova página com uma lista de subdiretórios, deve-se clicar no primeiro deles, chamado base.

E então, finalmente, uma nova e derradeira página se abre, logo acima e de forma bem destacada está um link para o última versão estável do pacote base do R para o sistema operacional selecionado. Basta fazer o download e instalar como qualquer outro software.

Instalação do R Studio

A instalação do RStudio também é bastante simples. Primeiro deve-se acessar o site oficial do RStudio.

Na página inicial, na guia superior, deve-se selecionar Products e então, no menu que se abre, no grupo Open Source deve-se clicar em RStudio.

Na página que se abre, deve-se localizar a seção RStudio Desktop e fazer o download da Open Source Edition. O site abrirá outra página na qual deve-se optar novamente pela versão RStudio Desktop - Open Source - Free. Basta fazer o download e instalar como qualquer outro software.

Instalação do Pandoc e do MikTeX

Ainda que o RStudio já inclua uma versão “empacotada” do Pandoc em sua instalação básica, é possível instalar uma cópia separada do Pandoc por conta própria.

Embora seja desnecessário na maioria dos casos, pode ser útil. A versão empacotada do Pandoc geralmente não é a mais recente ou pode não ser a versão exata que, por qualquer razão, se deseje.

Também pode ser útil possuir uma versão independente do Pandoc para o caso de se desejar fazer conversões que não sejam nativamente suportadas “dentro” do RStudio. Desta forma seria possível transformar o arquivo R Markdown .Rmd em Markdown .md no RStudio através do Knitr e então utilizar o Pandoc “fora” do RStudio, o que permitiria, por exemplo, utilizar o Limarka, que apresentamos no terceiro artigo desta série, para produzir documentos acadêmicos em conformidade com as Normas ABNT.

Instalar uma distribuição TeX/LaTeX (como o MikTeX) também será necessário, uma vez que, como já vimos, o Pandoc utiliza o LaTeX para gerar arquivos PDF. O RStudio provavelmente fará automaticamente a instalação de uma distribuição LaTeX quando for necessária pela primeira vez, caso não exista uma instalada no computador, eventualmente requerendo apenas uma confirmação do usuário. Para utilizar o Pandoc “fora” do RStudio, entretanto, será necessário instalá-la separadamente.

Já apresentamos a instalação do Pandoc e do MikTeX em nosso segundo artigo desta série, que é importante que seja lido antes deste, bem como o primeiro artigo, no qual apresentamos a sintaxe básica do Markdown e trouxemos uma introdução a respeito de linguagens de marcação.

Interface do RStudio

A interface do RStudio quando o abrimos pela primeira vez será como mostrada na figura 2 a seguir. Ela é constituída por uma barra superior com menus e botões e a parte de baixo dividida em três blocos, um para Console, outro para Environment, History, Connections e Tutorial e mais outro para Files, Plots, Packages, Help e Viewer.

rstudio-02

Interface do RStudio

Ao painel de Environment, History e Connections podem ser acrescentadas outras abas, dependendo do tipo de trabalho que se esteja desenvolvendo, como por exemplo a aba Presentations, quando se está produzindo slides ou a aba Build quando se está construindo e testando um pacote R. Como não é o objetivo deste texto tratar da estrutura da linguagem R, ou mesmo do RStudio em si, vou descrever apenas sucintamente esta interface inicial.

  • No bloco Console, à esquerda, está “rodando” a versão do R instalada, qualquer comando que for digitado ali será executado. O R “base” é basicamente o equivalente a este console;

  • No bloco superior direito:

    • A aba Environment mostra todos os objetos - ou variáveis - que forem carregados na memória, que poderão ser acessados a partir do momento em que forem carregados;
    • A aba History mostra o histórico de comandos que foram utilizados, em sequência;
    • A aba Connections serve para se conectar com bancos de dados e outras fontes de dados;

  • No bloco inferior direito:

    • A aba Files é basicamente um gerenciador de arquivos, que mostra os arquivos que estão na pasta de trabalho utilizada e permite criar, mover, renomear arquivos e pastas, etc;
    • A aba Plots mostra os gráficos que tenham sido criados;
    • A aba Packages mostra todos os pacotes que estão instalados com o R, e permite que sejam carregados, atualizados, etc;
    • A aba Help apresenta a documentação do R, que possui uma página de ajuda para cada comando, que explica com detalhes como utilizá-lo;
    • A aba Viewer, por fim, permite visualizar relatórios. Ao utilizar o R Markdown, por exemplo, pode-se visualizar a versão “renderizada” do documento nesta aba.

Estes três blocos iniciais não são toda a interface do R, a partir do botão “novo arquivo”, na barra de ferramentas, o primeiro botão à esquerda, pode-se abrir um novo painel para um Script R, um notebook R ou um documento R Markdown, por exemplo, dependendo do que se pretenda fazer.

R Markdown no RStudio

Para criar um documento R Markdown, finalmente, deve-se clicar no botão “novo arquivo / new file” (1) e então clicar em “R Markdown” (2), conforme Figura 3 a seguir.

rstudio-03

Interface do RStudio - criar novo arquivo

Na sequência aparecerá uma janela semelhante à da Figura 4. Deve-se selecionar a opção “Document” (1) no quadro à esquerda, digitar o título do documento e, opcionalmente, o nome do autor nos campos à direita (2) e, por fim, clicar em “OK” (3).

Em Default Option Format, deve-se escolher qual o formato do documento de saída, para o qual será convertido, ao final, o arquivo R Markdown que está sendo criado: HTML, PDF ou Word, por padrão está marcado HTML. O que quer que se selecione aqui pode ser alterado depois no cabeçalho YAML do próprio arquivo R Markdown, inclusive para outros formatos que não estes três, como simplesmente Markdown por exemplo, de modo que esta seleção não é tão relevante.

rstudio-04

RStudio - criar documento R Markdown

Será criado, então, um novo bloco na porção superior esquerda da interface do RStudio, como podemos ver na Figura 5.

Este novo bloco é um editor de código que contém nosso arquivo R Markdown, onde podemos escrever texto com sintaxe Markdown misturado com código R ou de outras linguagens de programação.

Na primeira vez, após a instalação do RStudio, que for criado um arquivo R Markdown o próprio RStudio irá oferecer a instalação de alguns pacotes adicionais necessários, basta aceitar e aguardar a instalação automática.

rstudio-05

RStudio - editor R Markdown

O documento recém criado vem “preenchido” com o cabeçalho YAML que contém os dois parâmetros de metadados que definimos no momento de criação do documento: o título e o formato do documento de saída. Conforme mencionado, podemos modificar estes parâmetros neste cabeçalho.

O documento também possui, após o cabeçalho YAML, uma espécie de “template” exemplificativo, contendo alguns trechos de texto em Markdown e código R. Podemos alterar ou apagar isso livremente.

Ainda é necessário salvar o arquivo R Markdown e dar um nome a ele. O nome que foi dado no momento de criação do arquivo corresponde ao título do Documento ou Relatório que será criado, mas não ao nome do arquivo.

Para salvar o arquivo basta clicar no ícone em forma de disquete (1) que fica na barra de ferramentas do próprio bloco do editor R Markdown (não confundir com a barra de ferramentas do RStudio em si, que fica logo acima e também tem um outro botão de salvar idêntico), conforme Figura 6.

rstudio-06

RStudio - salvar arquivo R Markdown

Após salvarmos e nomearmos o arquivo, e antes de tratar da estrutura de um arquivo R Markdown, podemos testar o funcionamento básico da conversão e visualizarmos este arquivo com um template exemplificativo em seu formato final de saída. Para isto para clicar no botão “Knit” (1) na barra de ferramentas do editor do R Markdown, conforme Figura 7.

rstudio-07

RStudio - Knit

E então, após uns instantes de processamento, o arquivo é renderizado e aberto em uma nova janela, conforme podemos ver na Figura 8. Neste caso é um arquivo HTML aberto numa janela que faz as vezes de um navegador Web.

rstudio-08

RStudio - documento R Markdown renderizado em HTML

Quando clicamos no botão “Knit” no editor do R Markdown o RStudio chama a função rmarkdown::render(), do pacote rmarkdown, já com todos os atributos necessários. É possível ver, no Console, a função sendo executada, mas não é necessário entender sua sintaxe, uma vez que existe um botão para isso.

O atalho de teclado ctrl+shift+k (no Windows e Linux) ou Command+shift+k (no MacOS) tem a mesma utilidade do botão “Knit” em um arquivo R Markdown.

Estrutura do arquivo R Markdown

A estrutura de um arquivo R Markdown .Rmd é composta por três elementos básicos: metadados, corpo do texto e código.

Metadados

Os metadados são inseridos no início do documento R Markdown através de um cabeçalho YAML (também chamado de YAML front matter).

Um bloco de metadados YAML é um objeto YAML válido, delimitado por uma linha de três --- (hifens) na parte superior e uma linha de três --- (hifens) ou três ... (pontos) na parte inferior. A sintaxe YAML é essencialmente um conjunto de chaves e valores no formato chave: "valor".

O bloco de metadados YAML não é exclusividade do R Markdown, esta forma de adicionar metadados ao arquivo também é padrão no Pandoc, conforme apresentamos no segundo artigo desta série, que é importante que seja lido antes deste.

Os metadados YAML serão processados ​​em vários estágios do processo de renderização do documento. Ele será lido pelo Pandoc e pelos pacotes rmarkdown e knitr. As informações contidas no cabeçalho YAML podem afetar o código, o conteúdo e o processo de renderização.

Como foi possível observar na Figura 5, o cabeçalho YAML do nosso arquivo R Markdown recém criado possui apenas duas linhas:

---
title: "Inteligência Urbana"
output: html_document
---

Foram inseridos apenas os metadados de título (title) e formato do documento de saída (output), que foram especificados no momento de criação do documento, na janela da Figura 4.

Se quisermos acrescentar, por exemplo, um subtítulo, um autor e uma data para o documento basta acrescentarmos as chaves subtitle, author e date, e seus respectivos valores, da seguinte forma:

---
title: "Inteligência Urbana"
subtitle: "Dados urbanos em R Markdown"
author: "Elson Fabiano Alves"
date: "11/09/2021"
output: html_document
---

O formato de saída (output) do documento, o formato para o qual ele será convertido - ou “renderizado” - quando o botão “Knit” for clicado, está definido como HTML, que foi o formato selecionado no momento de criação do documento, quando era possível escolher entre HTML, PDF e Word, conforme Figura 4. Todavia, isto pode ser livremente alterado, e a quantidade de formatos possíveis, entre documentos e apresentações, é bem maior que as opções disponíveis na janela inicial. No momento, a lista de formatos disponíveis é a seguinte:

  • beamer_presentation
  • context_document
  • github_document
  • html_document
  • ioslides_presentation
  • latex_document
  • md_document
  • odt_document
  • pdf_document
  • powerpoint_presentation
  • rtf_document
  • slidy_presentation
  • word_document

Além disso, pode ser definido mais de um formato de saída simultaneamente, e algumas configurações e definições adicionais podem ser acrescentas utilizando a estrutura hierárquica da sintaxe YAML. Por exemplo:

---
title: "Inteligência Urbana"
subtitle: "dados urbanos em R Markdown"
author: "Elson Fabiano Alves"
date: "11/09/2021"
output:
   html_document:
      toc: TRUE
   pdf_document:
      keep_tex: TRUE
   md_document:
      variant: "markdown_phpextra"
      preserve_yaml: FALSE
---

O cabeçalho YAML acima estaria definindo que fossem gerados, simultaneamente, um documento HTML, um PDF e um documento Markdown .md.

Adicionalmente, está sendo definido para o documento HTML que deve ser produzida uma Tabela de Conteúdos (Table of Contents - ToC), que é um sumário gerado automaticamente a partir dos títulos do documento; está sendo definido para o documento PDF que o arquivo .tex (LaTeX) gerado como formato intermediário na conversão, seja mantido; e está sendo definido para o documento Markdown que seja utilizada a variante - ou sabor, ou dialeto - chamada Markdown PHPExtra e que o cabeçalho YAML do documento R Markdown não seja mantido no documento de saída.

O R Markdown fornece muitas opções de formatos para compilar - ou renderizar - o documento, como vimos acima, mas uma dica útil seria manter o output como html_document durante o processo de produção do documento. Isso porque renderizar o trabalho como PDF, Word ou algum tipo de apresentação pode levar muito mais tempo do que compilar em HTML. Por esse motivo, geralmente é mais prático produzir o documento tendo HTML como output, o que permite visualizá-lo facilmente e rapidamente em um navegador Web. Esta configuração padrão pode economizar tempo, e então quando estiver próximo de um produto acabado, é só alterar a saída (output) para o formato desejado e eventualmente realizar os retoques finais.

Inúmeros outros elementos e aspectos do documento podem ser configurados através do bloco de metadados YAML. Em artigos futuros nos deteremos mais sobre isso a partir de exemplos específicos, assinem nossa newsletter para receber atualizações.

Corpo do texto

Através de Markdown podem ser inseridos virtualmente todos os elementos necessários a um documento, tais como títulos, parágrafos, quebras de linha, listas, blocos de citação, blocos de código, links, imagens, tabelas, expressões matemáticas, notas, citações, etc.

Para os elementos do corpo do texto do documento R Markdown utiliza-se a sintaxe Markdown com os elementos da sintaxe estendida Pandoc’s Markdown, que apresentamos detalhadamente no primeiro e no segundo artigos desta série, que como já dissemos, é importante que sejam lidos antes.

Código

Existem duas formas de inserir código em meio a um documento R Markdown: Blocos de código executável, que são chamados de Chunks, e expressões de código R inline, que podem ser inseridas no meio do documento, mesclado aos elementos.

A sintaxe para inserção de um Chunk de código consiste em “cercá-lo” com três ``` (crases, ou backtricks), antes e depois do código. Ao lado do primeiro trio de crases ```, entre chaves {}, deve vir necessariamente a informação de qual linguagem está sendo utilizada no chunk (haja vista que o R Markdown suporta diversas outras linguagens além do R).

A sintaxe para incorporar um código R inline é simplesmente `r `, entre crases simples, com a letra r logo após a primeira crase e o código em si separado da letra r por apenas um espaço.

Conforme o seguinte trecho de documento R Markdown:

##Exemplo

Este é um parágrafo em **Markdown**.

```{r}
aqui <- "Um chunk de código R"

# um comentário do código
```

Aqui é outro parágrafo Markdown. Dois mais dois é igual a `r 2 + 2`. Com um código R *inline*

Após a renderização, o trecho de documento R Markdown acima produziria um documento de saída semelhante a este:

Exemplo

Este é um parágrafo em Markdown.

aqui <- "Um chunk de código R"

# um comentário do código

Aqui é outro parágrafo Markdown. Dois mais dois é igual a 4. Com um código R inline

Caso o trecho de código dentro do Chunk produza um output, este output será renderizado na sequência do código em si.

Isto conclui a primeira parte do artigo. Na segunda parte deste artigo, que pode ser acessada aqui, apresentamos de forma mais detida o funcionamento e as formas de inserção de código no documento, as configurações e interações possíveis.

Conclusão

Neste artigo apresentamos o R Markdown, uma ferramenta capaz de produzir documentos dinâmicos a partir da incorporação de trechos de código de linguagens de programação em arquivo de texto com sintaxe Markdown. Esta foi a primeira parte de um artigo de duas partes, e apresentamos o software RStudio, as instalações necessárias e a estrutura de um documento R Markdown.

Além do blog, a plataforma Inteligência Urbana disponibiliza páginas com referências para livros, cursos e leis e normas relacionadas aos temas que tratamos aqui. Caso você tenha interesse pode conferir nossos serviços oferecidos e entrar em contato quando quiser. Se quiser ser alertado da publicação de material novo pode assinar a nossa newsletter, e muito obrigado pela atenção até aqui!

Principais referências

Categorias: