Criando um documento dinâmico com Markdown e R

No exemplo anterior, escrevemos um documento em Markdown (.md) e inserimos códigos do R, que são apenas apresentados no documento final. Desse forma temos um documento estático, pois os códigos não são interpretados. Para fazermos esse documento ser dinâmico, vamos usar o pacote knitr a nosso favor, fazedo com que ele interprete e retorne resultados dos códigos que inserimos. Vamos denominar genericamente essa combinação de texto em Markdown e códigos do R de “R Markdown”.

Arquivos escritos em R Markdown não podem ser compilados usando ferramentas padrão de conversão de Markdown. O código R deve ser avaliado antes da conversão usando o Pandoc, por exemplo. R Markdown pode ser convertido para Markdown através do knitr. Os resultados de códigos do R são inseridos entre o texto em Markdown, que pode então ser convertido para HTML usando o Pandoc.

O uso do R Markdown para criar documentos dinâmicos tem se tornado uma ferramenta chave atualmente em literate statistical programming, e substituiu largamente ferramentas anteriores como o Sweave.

Os detalhes e opções do pacote knitr serão descritas mais adiante. Por enquanto, o que precisamos fazer para tornar esse documento dinâmico é alterar a extensão do arquivo de .md para .Rmd, e alterar a forma dos blocos de código. Os blocos de códigos (ou chunks) agora devem conter uma marcação especial para indicar que devem ser interpretados pelo R, através do knitr. Para isso, colocamos {r} no início de cada bloco, que agora ficam

```{r}
x <- rnorm(30)
```

Usando o mesmo exemplo anterior, vamos renomear o arquivo Exemplo1.md para Exemplo1-knitr.Rmd e incluir a marção {r} nos blocos de código.

Também é possível colocar códigos do R para serem renderizados na própria linha de texto com `r `. Por exemplo, `r 2+2` gera o resultado 4 no documento.

Veja o arquivo Exemplo1-knitr.Rmd.

# Um documento em Markdown

## Sobre o Markdown

O Markdown é uma linguagem de marcação muito simples, desenvolvida por
John Gruber.

A ideia básica por trás da linguagem é fazer com que o escritor se
preocupe mais com o **conteúdo** do texto do que com a *formatação*.

## Mais um título

Aqui vamos tentar descrever uma análise.

## Simulando variáveis aleatórias

No R podemos simular valores de uma distribuição normal padrão através
da função `rnorm()`.

Seja $X \sim \text{N}(0,1)$, então para gerar 30 valores dessa variável
aleatório normal, fazemos

```{r}
(x <- rnorm(30))
```

## Comentários

Com o resultado dessa simulação, podemos calcular a média e a variância
dessa VA $X$ para conferir se o resultado fica próximo de 0 e 1,
respectivamente.

## Visualização

Também podemos fazer um histograma dessa VA $X$ simulada

```{r}
hist(x)
```

Agora usamos o knitr, através da função knit() para compilar o documento .Rmd em um documento com sintaxe Markdown .md

knit("exemplos/Exemplo1-knitr.Rmd", output = "exemplos/Exemplo1-knitr.md")

O resultado da compilação pode ser vista no arquivo Exemplo1-knitr.md.

# Um documento em Markdown

## Sobre o Markdown

O Markdown é uma linguagem de marcação muito simples, desenvolvida por
John Gruber.

A ideia básica por trás da linguagem é fazer com que o escritor se
preocupe mais com o **conteúdo** do texto do que com a *formatação*.

## Mais um título

Aqui vamos tentar descrever uma análise.

## Simulando variáveis aleatórias

No R podemos simular valores de uma distribuição normal padrão através
da função `rnorm()`.

Seja $X \sim \text{N}(0,1)$, então para gerar 30 valores dessa variável
aleatório normal, fazemos

```r
(x <- rnorm(30))
```

```
##  [1] -0.51874950 -0.27979155  1.00745738 -0.46956995  0.29789704
##  [6] -0.41779443 -0.85038078  0.68904619 -0.46019619  1.34818438
## [11]  0.44307138 -0.15092619  0.45554886 -0.04015468  0.45612104
## [16] -0.40842503 -2.13649386  0.15682192  0.66004890 -0.98183441
## [21] -1.11364370 -0.43734768 -0.51611125  0.41899599  0.13415544
## [26]  1.03468645  1.65350323 -0.01794682 -0.02420332  0.25024690
```

## Comentários

Com o resultado dessa simulação, podemos calcular a média e a variância
dessa VA $X$ para conferir se o resultado fica próximo de 0 e 1,
respectivamente.

## Visualização

Também podemos fazer um histograma dessa VA $X$ simulada

```r
hist(x)
```

![plot of chunk unnamed-chunk-2](figure/unnamed-chunk-2-1.png)

Agora temos um documento em Markdown com os códigos do R avaliados. Mas ainda precisamos processar esse arquivo para gerar o arquivo .html através do Pandoc

pandoc(input = "exemplos/Exemplo1-knitr.md", format = "html")
executing pandoc   -t html -o exemplos/Exemplo1-knitr.html 'exemplos/Exemplo1-knitr_utf8.md'
[1] "exemplos/Exemplo1-knitr.html"

que gera o arquivo Exemplo1-knitr.html que pode ser visualizado no navegador.

R Markdown e knitr

O pacote knitr, como já mencionado, é uma combinação de várias ideias desenvolvidas separadamente em pacotes do R para literate programming, especialmente o Sweave. Este pacote suporta \(\LaTeX\), Markdown e HTML como linguagem de documentação, e algumas linguagens de programação, além do R, como por exemplo shell e Python. O resultado destes documentos pode ser exportado para PDF, HTML, ou até mesmo arquivos do MS Word. Daqui em diante, o nosso foco será no uso do knitr com Markdown e R, pela simplicidade e versatilidade dessa linguagem, gerando documentos dinâmicos em HTML. No entanto, a maioria das opções e o funcionamento geral do pacote é similar para \(\LaTeX\) (e compilação para PDF) e HTML.

Na seção anterior, nós criamos um arquivo com a extensão .Rmd, que é apropriada para documentos escritos em Markdown com R. Nós também usamos as funções knitr() para converter o documento para Markdown, e posteriormente a função pandoc() para gerar o HTML resultante. Esse é o processo básico para gerar documentos dinâmicos no R. No entanto, podemos estender esse processo para incorporar mais controle tanto sob os códigos que são gerados, quanto na apresentação do documento final.

Para facilitar a criação de documentos dinâmicos no R, a equipe do RStudio desenvolveu o pacote rmarkdown, que é baseado no knitr e Pandoc, e contém opções padrão para gerar documentos em vários formatos de maneira mais aprimorada.

A principal função para gerar documentos em R Markdown do pacote rmarkdown é a render(). A função render() é uma wrapper que internamente chama a knitr::knit() e posteriormente converte o documento para .html usando o Pandoc. A diferença é que, além de ser um processo mais direto, a saída em formato HTML utiliza temas mais amigáveis, como o Twitter Bootstrap, que possibilita grandes opções de configuração mais avançada.

Para usar esse função você precisa:

  1. Instalar o pacote rmarkdown com install.packages("rmarkdown")
  2. Instalar o Pandoc no seu sistema

No RStudio, esse pacote já vem instalado, assim como uma versão embutida do Pandoc.

Usando o exemplo anterior, vamos compilar o arquivo Exemplo2-knitr.Rmd. O primeiro argumento da função é o nome (e local) do arquivo, e o segundo argumento é o formato de saída, que por padrão é HTML.

library(rmarkdown)
render("exemplos/Exemplo2-knitr.Rmd",  output_format = "html_document")


processing file: Exemplo2-knitr.Rmd

  |                                                                       
  |                                                                 |   0%
  |                                                                       
  |.............                                                    |  20%
  ordinary text without R code


  |                                                                       
  |..........................                                       |  40%
label: unnamed-chunk-1

  |                                                                       
  |.......................................                          |  60%
  ordinary text without R code


  |                                                                       
  |....................................................             |  80%
label: unnamed-chunk-2

  |                                                                       
  |.................................................................| 100%
  ordinary text without R code
output file: Exemplo2-knitr.knit.md
/usr/bin/pandoc +RTS -K512m -RTS Exemplo2-knitr.utf8.md --to html --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash --output /home/fpmayer/GitHub/prr/exemplos/pandoc3d7539f01368.html --smart --email-obfuscation none --self-contained --standalone --section-divs --template /home/fpmayer/R/library/rmarkdown/rmd/h/default.html --variable 'theme:bootstrap' --include-in-header /tmp/RtmpBGUn4C/rmarkdown-str3d754cdd263d.html --mathjax --variable 'mathjax-url:https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' --no-highlight --variable highlightjs=/home/fpmayer/R/library/rmarkdown/rmd/h/highlight --variable navigationjs=/home/fpmayer/R/library/rmarkdown/rmd/h/navigation-1.1 

Output created: Exemplo2-knitr.html

E o resultado pode ser visto no arquivo Exemplo2-knitr.html.

No RStudio, esse processo todo pode ser feito pelo botão Knit.

Metadados

Uma opção interessante ao utilizar o Pandoc é incluir metados no formato YAML (Yet Another Markup Language). Os metadados em YAML são escritos em formato de lista aninhada, e o Pandoc usa essas informações para incluir, por exemplo, título, autor, e data em um documento.

A opção mais importante para o rmarkdown é o campo output, que permite especificar o formato desejado de saída, o mesmo especificado no argumento output_format = da função render().

Os metadados em YAML são colocados sempre no início de um documento, e são delimitados por ---. Um exemplo típico seria:

---
title: "Meu primeiro documento em R Markdown"
author: "Fernando Mayer & Walmes Zeviani"
date: Maio, 2016
output: html_document
---

Com isso, não é mais necessário especificar o argumento output_format = na chamada da função render().

Veja o arquivo Exemplo1-yaml.Rmd. Para renderizar esse aquivo, usamos:

render("exemplos/Exemplo1-yaml.Rmd")


processing file: Exemplo1-yaml.Rmd

  |                                                                       
  |                                                                 |   0%
  |                                                                       
  |................                                                 |  25%
  ordinary text without R code


  |                                                                       
  |................................                                 |  50%
label: unnamed-chunk-1

  |                                                                       
  |.................................................                |  75%
  ordinary text without R code


  |                                                                       
  |.................................................................| 100%
label: unnamed-chunk-2
output file: Exemplo1-yaml.knit.md
/usr/bin/pandoc +RTS -K512m -RTS Exemplo1-yaml.utf8.md --to html --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash --output /home/fpmayer/GitHub/prr/exemplos/pandoc3d751f23de8a.html --smart --email-obfuscation none --self-contained --standalone --section-divs --template /home/fpmayer/R/library/rmarkdown/rmd/h/default.html --variable 'theme:bootstrap' --include-in-header /tmp/RtmpBGUn4C/rmarkdown-str3d7572fc9e14.html --mathjax --variable 'mathjax-url:https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' --no-highlight --variable highlightjs=/home/fpmayer/R/library/rmarkdown/rmd/h/highlight --variable navigationjs=/home/fpmayer/R/library/rmarkdown/rmd/h/navigation-1.1 

Output created: Exemplo1-yaml.html

O resultado final pode ser visto no arquivo Exemplo1-yaml.html.

Convertendo R Markdown para outros formatos

Por padrão, a função render() gera um arquivo .html, mas existem outros formatos finais possíveis graças ao Pandoc.

O pacote rmarkdown possui uma série de formatos de saída, que possuem os sufixos _document para documentos, e _presentation para apresentações (slides). Alguns deles:

  • Documentos:
    • html_document
    • pdf_document
    • word_document
  • Apresentações:
    • ioslides_presentation
    • slidy_presentation
    • beamer_presentation

Podemos converter um documento em R Markdown para PDF com

render("exemplos/Exemplo1-knitr.Rmd", output_format = "pdf_document")

O resultado é o arquivo Exemplo1-knitr.pdf. A função render() usa o Pandoc para converter Markdown para \(\LaTeX\), e depois para PDF.

Um documento do Word pode ser gerado com

render("exemplos/Exemplo1-knitr.Rmd", output_format = "word_document")


processing file: Exemplo1-knitr.Rmd

  |                                                                       
  |                                                                 |   0%
  |                                                                       
  |.............                                                    |  20%
  ordinary text without R code


  |                                                                       
  |..........................                                       |  40%
label: unnamed-chunk-1

  |                                                                       
  |.......................................                          |  60%
  ordinary text without R code


  |                                                                       
  |....................................................             |  80%
label: unnamed-chunk-2
Warning in (knit_hooks$get("plot"))(file, reduce_plot_opts(options)): Chunk
options fig.align, out.width, out.height, out.extra are not supported for
Word output

  |                                                                       
  |.................................................................| 100%
  ordinary text without R code
output file: Exemplo1-knitr.knit.md
/usr/bin/pandoc +RTS -K512m -RTS Exemplo1-knitr.utf8.md --to docx --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash --output /home/fpmayer/GitHub/prr/exemplos/pandoc3d7556084288.docx --highlight-style tango 

Output created: Exemplo1-knitr.docx

Para gerar Exemplo1-knitr.docx.

Apresentações em slides HTML podem ser geradas em diversos formatos, um deles é o ioslides

render("exemplos/Exemplo1-knitr.Rmd",
       output_format = "ioslides_presentation",
       output_file = "Exemplo1-knitr-ioslides.html")


processing file: Exemplo1-knitr.Rmd

  |                                                                       
  |                                                                 |   0%
  |                                                                       
  |.............                                                    |  20%
  ordinary text without R code


  |                                                                       
  |..........................                                       |  40%
label: unnamed-chunk-1

  |                                                                       
  |.......................................                          |  60%
  ordinary text without R code


  |                                                                       
  |....................................................             |  80%
label: unnamed-chunk-2

  |                                                                       
  |.................................................................| 100%
  ordinary text without R code
output file: Exemplo1-knitr.knit.md
/usr/bin/pandoc +RTS -K512m -RTS Exemplo1-knitr.utf8.md --to html --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash --output /home/fpmayer/GitHub/prr/exemplos/pandoc3d7568309a32.html --smart --email-obfuscation none --self-contained --variable transition=0.4 --template /home/fpmayer/R/library/rmarkdown/rmd/ioslides/default.html --mathjax --variable 'mathjax-url:https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' --variable ioslides-url=/home/fpmayer/R/library/rmarkdown/rmd/ioslides/ioslides-13.5.1 
/usr/bin/pandoc +RTS -K512m -RTS Exemplo1-knitr.utf8.md --to ioslides_presentation.lua --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash --output /tmp/RtmpBGUn4C/ioslides-output3d75321cc3bd.html --slide-level 2 

Output created: Exemplo1-knitr-ioslides.html

Veja o resultado em Exemplo1-knitr-ioslides.html.

Apresentações em Beamer também podem ser geradas com

render("exemplos/Exemplo1-knitr.Rmd",
       output_format = "beamer_presentation",
       output_file = "Exemplo1-knitr-beamer.pdf")

Com resultado no arquivo Exemplo1-knitr-beamer.pdf.

Opções do knitr

O pacote knitr possui diversas opções para controlar a saída dos resultados de códigos do R. Estas opções funcionam igualmente em blocos de código inseridos entre texto escrito em Markdown ou \(\LaTeX\).

Para controlar a saída de código de um único chunk, coloque as opções individualmente

```{r, opt1=val1, opt2=val2}
# código
```

Para controlar globalmente todos os chunks de um documento, use a função knitr::opts_chunk$set():

```{r, echo=FALSE}
knitr::opts_chunk$set(opt1 = val1,
                      opt2 = val2
)
```

As opções mais importantes são:

  • eval = FALSE para não avaliar o código, apenas mostrar
  • echo = FALSE para não mostrar o código, apenas as saídas
  • results = "hide" para não mostrar as saídas
  • warning = FALSE e message = FALSE para suprimir as mensagens de aviso
  • fig.width = 5 and fig.height = 5 para alterar o tamanho dos gráficos gerados pelo R (em polegadas)
  • cache = TRUE para armazenar os resultados, e evitar com que eles sejam executados todas as vezes que o documento é compilado

Tabelas podem ser também geradas automaticamente a partir de resultados de funções do R. Para gerar uma tabela a partir de um objeto do R, podemos usar a função knitr::kable(). Para isso, também é necesário utilizar a opção results = "asis" no chunk, para que o resultado seja tratado como texto literal em Markdown.

```{r, results="asis"}
kable(head(iris))
```
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 lista completa de opções está em http://yihui.name/knitr/options.

Utilizando a opção output: um cabeçalho YAML, podemos informar mais de um formato para ser gerado ao mesmo tempo pelo rmarkdown. Por exemplo, para gerar documentos de saída em HTML e PDF, podemos especificar

---
title: "Meu primeiro documento em R Markdown"
author: "Fernando Mayer & Walmes Zeviani"
date: Maio, 2016
output: html_document
output:
  html_document: default
  pdf_document: default
---

E compilar todos eles ao mesmo tempo com

render("exemplos/Exemplo1-yaml2.Rmd", output_format = "all")

Veja Exemplo1-yaml2.html, e Exemplo1-yaml2.pdf.

Licença Creative Commons 4.0

Este conteúdo está disponível por meio da Licença Creative Commons 4.0