Larissa Sayuri Futino C. dos Santos | 08/08/2016
RMarkdown: Just do it
Larissa Sayuri Futino C. dos Santos
11 de agosto de 2016
Introdução
Objetivos
A gente começa o Semestre 2/2016 com um grande exercício de metalinguagem. Vamos usar uma linguagem para descrever a si própria. Esse é um documento R Markdown com os objetivos de apresentar a linguagem, suas vantagens e usos e servir de modelo/base para futuras postagens do grupo.
Conceitos e História
Markdown é uma linguagem simples para formatar sintaxe de arquivos a serem escritos em HTML, PDF e Word. Trata-se de uma lightweight markup language (LML), ou seja, ela foi concebida para ser de fácil utilização a partir do uso de qualquer editor de texto genérico e de fácil leitura.
O primeiro pacote em R chamava-se markdown que tinha como objetivo principal gerar documentos em HTML. Para estatísticos, que usualmente precisam de citações, notas de rodapé e informações documentais como autor, data e título, o markdown não se mostrava uma ferramente realmente conveniente.
A necessidade de conversão para outros formatos também ficou muito recorrente e, nesses casos, recorria-se ao Pandoc. What? Trata-se de um conversor universal de documentos com possibilidade de uso de:
- notas de rodapé;
- tabelas;
- listas de definição;
- aspas, sub-escritos e super-escritos;
- listas ordenadas e
- citações automáticas e bibliografias
- sintaxe LaTeX dentre muitos outros
Entretanto, o Pandoc todo poderoso exige o uso de muitos comandos de linha. O mesmo problema do knit, que é usado conjuntamente com o primeiro.
Logo, a equipe do RStudio criou a segunda geração do R Markdown, que está sendo usada agora, com o objetivo de acrescentar uma interface amigável para customizar opções do Pandoc.
Em uma definição do R-bloggers:Vantagens
E realmente vale a pena usar o rmarkdown?
- O documento é
- auto-contido
altamente reproduzível o que o torna facilmente compartilhável
Você pode definir seus próprios templates e outputs
O código R pode ser incluído ao relatório/documento de sorte que não o primeiro não se separa do segundo. A facilidade de um documento unificado evita re-trabalho.
- Especificamente para documentos HTML:
O texto é escrito como um texto usual, ou seja, não há necessidade de conhecimento de linguagem HTML.
O output inclui figuras, blocos de códigos e/ou resultados além do próprio texto. É um arquivo fácil de enviar por email ou de postar em um website.
Um arquivo HTML facilita colaboração: É muito mais simples comentar uma análise quando o código, output e imagens estão disponíveis no mesmo arquivo.
Mãos à obra!
Pressupondo que você é um usuário RStudio, ok? Se você não é… Instale! Vale a pena.
Começando…
Criando um documento markdown
Passo 03: Você deve se deparar com um documento similar a esse. Salve-o e repare que a extensão será .Rmd e é só começar!
Compilando
Passo 04: Para gerar o seu documento de interesse basta apertar o botão knit.
Chunks, códigos, outputs, equações e gráficos
Quando o interesse é acrescentar partes do código R em meio ao documento utiliza-se o conceito de chunk de código (code chunk). Em uma tradução literal, são pedaços do código.
Inline
Se vc quer inserir um pedaço de código inline use apenas uma aspa simples para começar e terminar o chunk. Ao abrir o chunk comece pela letra ‘r’ e acrescente seu código. Botando os pingos nos i’s segue um output de código R: Mole, né? Tão fácil quanto 2 + 2 = 4.
E se fosse uma equação? É muito parecido com o Latex; entre dois cifrões ($) insere-se a expressão de interesse, por exemplo: \(t^{'} = t \frac{1}{\sqrt{ 1 -\frac{v^{2}}{c^{2}} }}\)
Entre linhas de texto
Basicão:
- Para abrir: três aspas invertidas seguidas da letra r entre chaves ({r})
- Para fechar: três aspas invertidas
A seguir, o código em um chunk e seu respectivo resultado:
## Um classico: (Repare bem! Eh assim que se comenta codigo em um chunk do rmarkdown!)
paste("Alô Mundo RMarkdown!")## [1] "Alô Mundo RMarkdown!"Um chunk pode contemplar tudo de um código R usual: Chamada de pacotes, bases de dados, declaração e uso de funções e objetos além de outputs.
Vamos fazer um pequeno script para exemplificar.
rm(list = ls())
gc()
require(googleVis)
op <- options(gvis.plot.tag="chart")
## Criando a nossa base
id <- 1:20
classif <- c(rep( "GrandMaster", 15), "Master", "GrandMaster", "Master", "GrandMaster", "Master")
exp <- c(4, 3, 3, 5, 3, 3, 5, 2, 6, 5, 4, 2, 5, 5, 3, 3, 4, 2, 5, 3)
Ouro <- c(24, 22, 18, 9, 5, 13, 18, 10, 16, 8 , 6, 6, 23, 5, 5, 3, 5, 4, 9, 7)
Prata <- c(20, 7, 20, 23, 6, 10, 14, 6, 20, 13, 25, 7, 10, 6, 5, 0 , 24, 0, 8 , 13)
Bronze <- c(18, 0, 20, 13, 4, 5, 4, 1, 12, 3, 16, 1, 5, 2, 5, 6, 9, 0, 10, 10)
pont <- c(216.177, 212.096, 193.549, 135.847, 127.354, 127.013, 121.055, 119.520, 112.719, 106.700,
105.547, 105.539, 104.601, 98.255, 97.703, 97.514, 97.309, 97.307, 90.787, 87.930)
basecompet <- data.frame(id, classif, exp, Ouro, Prata, Bronze, pont)
rm(id, classif, exp, Ouro, Prata, Bronze, pont)## Criando uma funcao
fGrafColEmpil <- function(BASE, XVAR, YVAR, TITULO){
Grafico <- gvisColumnChart(BASE,
xvar = XVAR,
yvar = YVAR,
options = list(isStacked = TRUE,
title = TITULO,
vAxes = "[{viewWindowMode:'explicit',
viewWindow:{min:0, max:70}}]",
legend ="{position: 'bottom', textStyle: {fontSize:12}}",
width = '900px', height = '400px',
colors = "['#FFD700', '#CDC5BF', '#DAA520']"))
return(Grafico)
}## Chamando a funcao
graficoColEmpil <- fGrafColEmpil(BASE = basecompet,
XVAR = "id",
YVAR = colnames(basecompet)[-c(1, 2, 3, ncol(basecompet))],
TITULO = "Distribuição do total de medalhas por competidor")
plot(graficoColEmpil)Mostrar o código e os outputs pode ser útil mas e quando esse não é o caso? Os chunks são muito flexíveis para serem discretos na medida necessária pelo autor. Vamos evitar o print de um bloco de código nas linhas a seguir.
O controle de todos os argumentos de um chunk não é imediato, você provavelmente vai procurar a sintaxe específica para o seu problema enquanto estiver trabalhando no seu documento. A vantagem é que tudo é bem documentado como por exemplo o RMarkdownReference.
Obviamente, introduzir uma equação do Latex também é possível com a vantagem de que a sintaxe é exatamente igual ao mesmo.
Bibliografia e citações
Em se tratando de referências e citações, em geral pouca dor de cabeça é coisa rara. No RMarkdown existem boas referências e uma delas chama a atenção: Bibliografia e Citações.
No diretório onde está o seu script RMarkdown, deixe um arquivo em extensão .bib com as referências do seu trabalho. Claro, há outras extensões… Mas é bom lembrar que há uma fonte fácil de referências em sintaxe .bib: o Google Scholar.
É importante notar que para ter uma seção de Referências adicionamos nas primeiras linhas do código essa informação com o respectivo nome do arquivo .bib.
Além disso, a princípio, a sequência de referências vai constar depois da última linha de código, a qual equivale propositalmente à seção de Referências.
E que, assim como no Latex, um ícone bibliográfico aparece exclusivamente quando ele é referenciado. No meu script .bib existem três referências e eu vou referenciar apenas uma delas para que conste nesse arquivo, como uma forma didática e explicativa como sempre sugerem os sábios Silva and Prates (2016).
Mãos à Obra
Fazendo jus ao título desse documento: é preciso começar!
Sugestão de Exercício: Temos uma página no github que é um tipo de identidade e a nossa voz. Cada um de nós agrega um valor muito específico em um grupo constituído exclusivamente de capital humano.
Faça uma apresentação à sua maneira em um formato de postagem para blog (HTML). Inclua seus dados, preferências, linhas de pesquisa e, se quiser, adicione algo pessoal como uma foto, seus hobbies e citações. Se todos concordarem, essas apresentações estarão na nossa página do github, ampliando nossa visibilidade individualmente e trazendo mais conhecimento sobre nós mesmos!
Trabalhos Futuros
Dominar especificidades e minúcias do uso do RMarkdown e de HTML.
Referências
Silva, Luís Gustavo Silva e, and Marcos Oliveira Prates. 2016. SpGoogle: Visualizing Spatial Data with Google. http://CRAN.R-project.org/package=spGoogle.