Rmarkdown1. o que é Markdown1.1 o que é Rmarkdown1.2 usando Rmarkdown no Rstudio1.4 formatação básica do Rmarkdown1.5 Links e Imagens em Rmarkdown1.5.1 Links1.5.2 Imagens1.6 Tabelas1.7 Equações2.0 Executando comandos R2.1 O bloco R (chunk) e algumas opções2.1.1 O Bloco R2.1.2 Opções do bloco R2.2 Incluído gráficos do R2.3 formatando tabelas2.4 Um exemplo em Rmarkdown e considerações finaisREFERENCIAS
Rmarkdown
1. o que é Markdown
Markdown é uma linguagem simples de marcação (markup language). Ela foi influenciada por diversas linguagens principalmente pelo HTML. desenvolvido em 2004 por John Gruber e Aaron Swartz.
O Markdown permite que seus elementos sejam definidos usando marcações de texto, sem a necessidade de tags com outras linguagens. Seu arquivo fonte é em formato texto e mesmo com os marcadores de formatação o texto continua legível.
Veja a frase abaixo
O R pode ser baixado do site do Mirror do CRAN localizado na FIOCRUZ
em HTML :
<p>O <b>R</b> pode ser baixado do <i> site</i> do <ahref="http://cran.fiocruz.br " & g t; Mirror do CRAN, target="_blank" > localizado na <em>Fiocruz</em></p>em Markdown teríamos :
xxxxxxxxxxO **R** pode ser baixado do *site* do [Mirror do CRAN](cran.fiocruz.br) localizado na **FIOCRUZ**Como vemos no pequeno exemplo acima o markdown é simples, usa símbolos para fazer formatações como negrito, Itálico , links etc..., como você pode deduzir da linha acima, texto entre um * estará em negrito , já entre apenas um * estará em itálico .
O markdown é uma ferramenta muito prática para o dia a dia e seu conteúdo pode ser convertido facilmente em diversos formatos , HTML, PDF , EPUB (ebook) e ate mesmo MS WORD DOC.
1.1 o que é Rmarkdown
O Rmarkdown é uma extensão do markdown que adiciona ao R um ambiente integrado para
- Realização de analises ,
- Documentação de scripts
- Geração de relatórios
Essas características fazem do RMarkdown uma ferramenta única possibilitando uma expansão e inovação na maneira que usamos o R. As características apontadas acima tornam o R uma ferramenta de excelência , facilitado a produção de análises, mantende e documentando de uma forma mais amigável os scripts em R e, por fim, gerando relatórios complexos integrando facilmente , textos gráficos e tabelas e gerando documentos em qualidade de editoração
usando o Rmarkdown podemos facilmente formatar
- textos em negrito e itálico
- listas
- cabeçalhos (títulos, sub-títulos etc...)
- hyperlinks
- gráficos e tabelas
- equações matemáticas
- bibliografia e citações
- etc...
em resumo tudo que voce necessita para um relatório técnico, trabalho de fim de curso ou até mesmo um artigo científico
1.2 usando Rmarkdown no Rstudio
Apesar de não ser obrigatório fazer o rmarkdown no Rstudio, ele nos facilita muito a tarefa de criar, editar e gerar o formato de saída.
Antes de entrarmos nos detalhes do markdown vamos ilustrar o processo do Rstudio para que fique mais claro como é o processo.
Após iniciar o Rstudio clique na opção file em seguida new file e, por fim, no menu lateral a opção Rmarkdown
so para ficar mais claro
Apos selecionar Rmarkdown o seguinte menu vai aparecer
Informe o Título do documento , o nome do Autor e o formato de saída.
ATENÇÃO Nesse curso vamos lidar somente com HTML , como se pode ver é necessária a instalação de programas adicionais para implementar a saída em PDF
Apos clicar em OK o rstudio cria uma aba no editor com um código de exemplo
Para gerar o documento devemos clicar no pequeno botão onde está escrito knit
caso ainda não tenha salvo o arquivo o rstudio vai solicitar um nome, de um nome para o arquivo (a extensão dele será *.Rmd )
Em seguida você vera no console do R o arquivo sendo transformado para o formato html e exibido em uma janela de apresentação do próprio rstudio
A janela de apresentação é um ambiente de visualizar o html, mas se quiser clilcar no botão open in Browser a página será exibida no navegador default do seu sistema operacional.
Vamos a segui conhecer um pouco mais da sintaxe do Rmarkdown
1.4 formatação básica do Rmarkdown
Vamos apresentar os elementos basicos de formatação do Rmarkdown, note que muitas vezes existem mais de uma maneira de especificar um formato.
x*italico* **negrito**_italico __negrito__Existem 6 níveis de cabeçalho
xxxxxxxxxx# cabeçalho 1 ## cabeçalho 2### cabeçalho 3#### cabeçalho 4##### cabeçalho 5###### cabeçalho 6Importante notar que o símbolo # deve estar na primeira coluna, nenhum espaço ou tabulação antes dele
Para criar listas use * ou -
xxxxxxxxxx* item 1- item 2* item 3 - sub item 3.1 - sub item 3.2- item 4Atenção aos sub itens , que devem ter uma tabulação ou espaços antes do símbolo * ou -
Para listas numeradas
xxxxxxxxxx1. um 4. dois 3. tres + sub 3a + sub 3b2. quatro Repare que mesmo estando fora de ordem, o Rmarkdown vai ordenar corretamente os itens
Linha separadora
Em muitas ocasiões pode ser útil ter uma linha separando pedaços do texto. em rmarkdown basta fazer uma linha com 3 asteriscos para se obter:
xxxxxxxxxx***Bloco de citações (block quotation)
xxxxxxxxxx> “essentially, all models are wrong, > but some are useful” > George P. Box Vamos testar esses elementos que vimos acima. Crie no rstudio um novo documento do tipo Rmarkdown, apague totalmente o conteúdo e cole o conteúdo abaixo. em seguida crie o arquivo de saída (neste caso html) clicando no botão knitr
Quebrando parágrafos e forçando quebra de linhas
Para inserir uma quebra entre parágrafos inclua uma linha totalmente em branco
Para forçar uma quebra de linha, ponha dois espaços
em branco no final da linha.
xxxxxxxxxxQuebrando parágrafos e forçando quebra de linhasPara inserir uma quebra entre parágrafos inclua uma linha totalmente em brancopara forçar uma quebra de linha, ponha dois espaços em branco no final da linhaObserve que a primeira no incio do arquivo gerado pelo rstudio temos
xxxxxxxxxx---title: “Exemplo de formatos em Rmarkdown”author: ""date: ""output: html_document---
Esse início é denominado cabeçalho YAML , onde se setam opções que serão passadas a um programa chamado pandoc que é o responsável por transformar o Rmarkdown no formato desejado!
xxxxxxxxxx---title: “Exemplo de formatos em Rmarkdown”author: ""date: ""output: html_document--- Os tipos de cabeçalho são : # cabeçalho 1 ## cabeçalho 2 ### cabeçalho 3 #### cabeçalho 4 ##### cabeçalho 5 ###### cabeçalho 6***#### Formatação: Texto Normal*Itálico* **Negrito** #### Listas: * item 1- item 2* item 3- sub item 3.1- sub item 3.2- item 4#### Listas Numeradas1. um 4. dois 3. três + sub 3a + sub 3b2. quatro Ronald Fisher em 1938 disse:>"To call in the statistician after the experiment is done may be no more than asking him to perform a post-mortem examination: he may be able to say what the experiment died of." Observe o documento gerado, agora experimente, por exemplo, colocar um espaço antes de uma # , ou remover a linha entre "Ronald Fisher em 1938 disse" e o resto da citação.
1.5 Links e Imagens em Rmarkdown
1.5.1 Links
Criar um link é bem simples, vamos criar um link apontando para o site da Fiocruz
xxxxxxxxxxAcesse o site da [Fiocruz](http://www.fiocruz.br)Neste caso teremos somente o link que esta entre [] e o endereço da URL não vai aparecer. já no formato abaixo o link sera exibido e estará ativo .
xxxxxxxxxxAcesse o site da Fiocruz em (http://www.fiocruz.br)Pode-se combinar o link a vários outros elementos, uma lista por exemplo.
xxxxxxxxxxLista de Sites* [ENSP](http://www.ensp.fiocruz.br)* [PROCC](http://www.procc.fiocruz.br)* [INI](www.ini.fiocruz.br)Uma vez mais precisamos estar atentos ao espaço. Não pode haver espaçamento entre as chaves e os parêntesis.
Tente incluir um link no nome de Ronald Fisher apontando para https://pt.wikipedia.org/wiki/Ronald_Fisher
1.5.2 Imagens
Para imagens temos um processo semelhante. para incluir por exemplo o logo do PROCC buscando a imagem através da rede.
xxxxxxxxxx
Note que o texto entre os colchetes diferente dos links não aparece, então na prática
xxxxxxxxxx
Caso a imagem esteja local, você deve apenas apontar para o caminha do imagem, por exemplo
xxxxxxxxxx
ou por exemplo como abaixo caso esteja no mesmo diretorio que seu arquivo .Rmd
xxxxxxxxxx
Modifique o arquivo Rmarkdown criado anteriormente e insira os links abaixo como figuras!
http://images.memes.com/meme/836717
http://blog.revolutionanalytics.com/downloads/datasaurus.gif
Como vimos vários formatos gráficos podem ser usados
- jpeg, jpg
- png
- tiff
- gif, gif animados
- svg (formato vetorial)
- etc...
Mas note que o tamanho depende do tamanho original da imagem! Assim para ajustar o tamanho deve-se fazer o download da imagem e alterar localmente o tamanho. Outras linguagens de marcação como por exemplo HTML ou LaTex possuim opções para se ajustar o tamanho.
xxxxxxxxxx
1.6 Tabelas
Vamos falar brevemente sobre tabelas básicas em Rmarkdown. Antes de mais nada, aqui estamos falando de tabelas implementadas em markdown e não as tabelas geradas por um comando no R.
Veja o código abaixo
xxxxxxxxxx| Nome | Sexo | Idade | Grupo || :---- | :--: | ----: | ----- || João | M | 34 | A || Maria | F | 29 | A || Ana | F | 32 | B |ele vai gerar a seguinte tabela:
| Nome | Sexo | Idade | Grupo |
|---|---|---|---|
| João | M | 34 | A |
| Maria | F | 29 | A |
| Ana | F | 32 | B |
Repare que a coluna Nome temos na segunda linha :---- , o que faz com que a coluna seja alinhada à esquerda. Já a coluna sexo :---: indicando que estará centralizada , Idade está ----: significando alinhada à direita e por fim a coluna Grupo que estão na opção default que é alinhada à esquerda.
Alguns elementos podem ser combinados dentro da tabela, como negrito, itálico, links e imagens!
| Fiocruz | PROCC |
|---|---|
 |  |
Esse seria o código para reproduzir essa tabela. No entanto lembre-se que vai precisar das imagens e de configurar o caminho para refletir a localização das imagens na sua máquina. Outro fato a ser notado é que não ha a necessidade de estar tudo alinhado, já que temos como separador o símbolo |.
xxxxxxxxxx| [Fiocruz](http://www.fiocruz.br) | [PROCC](http://www.procc.fiocruz.br) || :------------------------------: | :----------------------------------: ||  |  |1.7 Equações
A formatações das equações existentes no Rmarkdown seguem o padrão LaTeX. Existem basicamente duas maneiras de se escrever uma equação no Rmarkdown , no formato chamado inline e na forma de blocos.
Por exemplo podemos escrever dos Brasileiros tem sobre peso ou obesidade! ou ainda o parâmetro obtido foi e ainda algo como , as letras gregas , símbolos especiais como , operadores matemáticos e lógicos como ou ainda
veja o fonte do paragrafo acima:
xxxxxxxxxxPor exemplo podemos escrever $\frac{2}{3}$ dos Brasileiros tem sobre peso ou obesidade! ou ainda o parâmetro obtido foi $\hat{\lambda}=1.02$ e ainda algo como $\sqrt{4}=2$ , as letras gregas $\alpha, \beta, \gamma...$ , símbolos especiais como $a \pm $ , operadores matemáticos e lógicos como $x \ge 15$ ou ainda $a_i \ge 0~~~\forall i$ O modo inline permite que misturemos fórmulas, letras gregas, símbolos junto ao texto. Para isso usamos o $ para abrir e fecha o trecho com o formato Matemático.
Já no modo bloco devemos escrever uma ou mais equações dentro de um bloco iniciado por $$ e fechado pelo mesmo comando. por exemplo
xxxxxxxxxxA equação de segundo grau é dada por:$$x=\frac{-b \pm \sqrt{bˆ2-4ac}}{2a}$$A equação de segundo grau é dada por:
ou ainda a forma da variância é
xxxxxxxxxx$$cov_{x,y} = \frac{\sum\limits_{i=1}^{n}{(x_i-\overline{x}) \cdot (y_i-\overline{y})} }{n-1}$$Podemos também definir bloco de matrizes
xxxxxxxxxx$$\begin{bmatrix} x_{11} & x_{12} & x_{13} & \dots & x_{1n} \\ x_{21} & x_{22} & x_{23} & \dots & x_{2n} \\ x_{d1} & x_{d2} & x_{d3} & \dots & x_{dn}\end{bmatrix}$$O formato Para compreender algumas das possibilidades desse formato veja Aqui e Aqui para intruções sobre como usar equações no formato Rmarkdown e Aqui para instruções gerais do formato matemático usado na linguagem LaTeX.
2.0 Executando comandos R
Ate aqui vimos como lidar com o formato do Rmarkdown mas ainda não vimos como integrar com o R.
Aqui também existem duas maneiras de utilizar o R, o modo inline e o modo de bloco de código R, que também vamos chamar de chunk .
o modo inline é simples , podemos, por exemplo, escrever a seguinte linha em qualquer pedaço.
104 graus fahrenheit são 40 graus Celsius
xxxxxxxxxx104 graus fahrenheit são `r (104 - 32)*5 /9` graus Celsius
Repare que o acento grave ` para criar o código inline, também é necessário usar o r minúsculo após o primeiro acento grave.
Tente rodar o rmarkdown abaixo
xxxxxxxxxx---title: "R inline"author: ""date: ""output: html_document---Hoje é `r format(Sys.Date(), 'Rio de Janeiro, %d de %B de %Y') ` Estou usando o `r R.version$version.string` no sistema operacional `r R.version$os`Posso afirmar que $\pi \approx$ `r pi` O uso do comando inline do R e deve ser restrito a pequenos cálculos e formatação de strings, pois essa maneira não permite comandos mais complexos e nem gráficos.
2.1 O bloco R (chunk) e algumas opções
Antes de falarmos sobre os blocos há algumas considerações importantes a serem feitas:
- O espaço de trabalho workspace da sua sessão de R não é compartilhado com o rmarkdown , ou seja, todos os objetos , pacotes que estão carregados não serão passados ao rmarkdown
- Nenhum objeto será exportado por default, a não ser que seja explicitamente salvo
- O arquivo produzido como saída pelo rmarkdown, quer seja uma página HTML, um PDF ou um DOC no formato Word pode ser salvo.
2.1.1 O Bloco R
Os blocos de comandos em R (chunk) usados no rmarkdown são usados para fazer o processamento em R, produzir resultados, gráficos ou simplesmente para ilustrar o código quando se prepara uma aula ou se quer deixar o código visível em um relatório pro exemplo.
um exemplo de bloco em rmarkdown , note que a repetição de 3 acentos graves seguidos de {r} marcam o início do bloco e informam que aquele bloco contem código em R. Para fechar o bloco são necessários 3 acentos graves. O código
xxxxxxxxxx---title: "Bloco de código em R"author: ""date: ""output: html_document---## Exemplo de bloco de comandos em **R** ```{r}summary(mtcars)```Ao executar o comando acima teremos em nossa janela de saída a seguinte figura. de agora em diante vou omitir a parte relativa ao YAML.
Note que temos duas regiões,
A) com um fundo cinza claro, onde existe o eco do comando R contido no bloco
B) a saída da função summary que estava no bloco precedida por ## em cada linha
E se quisermos incluir mais um bloco? Poderíamos digitar todos os comandos para criar o bloco, no entanto o editor do rstudio oferece um atalho para isso.
No canto superior direito do editor do rstudio clique em insert e em seguida na opção R. esse comando vai criar um bloco vazio na posição do cursor.
Insira dentro desse bloco o seguinte comando:
xxxxxxxxxxcolMeans(mtcars)
de maneira que tenha um código mais ou menos como esse
xxxxxxxxxx## Exemplo de bloco de comandos em **R** ### Estatística sumária de todas as variáveis do data.frame mtcars```{r}summary(mtcars)```### Somente as media das variáveis ```{r}colMeans(mtcars)```Execute o rmarkdown e observe como fica o resultado.
Apague e tente agora o seguinte código.
xxxxxxxxxx### Somente as media das variáveis ```{r}media <- colMeans(mtcars)```### Desvio padrão```{r}desvio <- apply(mtcars, 2, sd)```o que aconteceu? Porque? Como fazer que os resultados obtidos sejam exibidos?
xxxxxxxxxx### Calcula a media e DP das variáveis ```{r}media <- colMeans(mtcars)desvio <- apply(mtcars, 2, sd)```Vamos fazer mais um exemplo, desta vez
xxxxxxxxxx```{r} library(dplyr)mtcars %>% as_tibble() %>% mutate( kpl = (mpg /3.78541) *1.6 , disp = disp * 0.0163871, wt = (wt * 0.45352)*1000, am = factor(am,label=c('Manual','Automatico')), name = rownames(mtcars), mpg = NULL )```Note que ao carregarmos um pacote ou qualquer outra mensagem de aviso tambem será ecoada para a saída. Podemos silenciar a saída da função library() usando as seguintes opções.
library(dplyr,warn.conflicts = FALSE,quietly = TRUE)
2.1.2 Opções do bloco R
Cada bloco R pode ter um nome, isso ajudar quando temos muitos blocos e ajuda também na detecção de erros pois o nome do bloco. O nome é opcional mas nunca deve se repetir.
xxxxxxxxxx---title: "Modelo GLM"author: ""date: ""output: html_document---```{r setup}library(MASS)``````{r transforma} bwt <- with(birthwt, {race <- factor(race, labels = c("white", "black", "other"))ptd <- factor(ptl > 0)ftv <- factor(ftv)levels(ftv)[-(1:2)] <- "2+"data.frame(low = factor(low), age, lwt, race, smoke = (smoke > 0), ptd, ht = (ht > 0), ui = (ui > 0), ftv)})``````{r modelo}modelo <- glm(low ~ ., family=binomial, data=bwt)summary(modelo)```Repare que cada bloco tem um nome único.
Suponha que no exemplo acima queremos suprimir a exibição dos blocos setup e transformação , bastaria introduzir a opção echo=FALSE no início do bloco.
```{r transforma,echo=FALSE}
e
```{r modelo,echo=FALSE}
faça isso para os dois blocos e rode novamente. A opção echo portanto controla se o comando R dentro do bloco sera exibido ou não.
Experimente alterar novamente esse bloco e adicionar a opção eval=FALSE e volte echo para TRUE
```{r transforma,echo=TRUE,eval=FALSE}
o que ocorreu?
A opção eval controla se o comando será executado (evalueted) ou não , mas repare que ele foi exibido mas não executado! Então veja que esse parâmetro é util para exibir o código sem de fato executa-lo.
agora vá no block setup e coloque a opção include=FALSE.
```{r setup,include=FALSE}
essa opção faz com que o bloco não apareça, que não haja output nenhum. a diferenção para a opção echo e que nesta o código não é mostrado mas o output é
existem muitas outras opções , para saber mais veja no pacote knitr na sessão Code Evaluation e saiba mais sobre essas e outras opções disponiveis.
algumas mas mais frequentes estão abaixo.
| opção | default | descrição |
|---|---|---|
| eval | TRUE | executa o código R dentro do bloco |
| echo | TRUE | exibe o código R contido no bloco e também seu output |
| warning | TRUE | exibe mensagens de aviso ocorridas no bloco |
| error | FALSE | exibe mensagens de erro ocorridas no bloco |
| message | TRUE | exibe mensagens ocorridas durante a execução |
| tidy | FALSE | reorganiza o texto no output |
| result | "markup" | formato do output "markup", "asis", "hold", or "hide" |
| cache | FALSE | cria um cache para armazenar os dados (aumenta velocidade em multiplas execuções) |
| comment | "##" | caracteres exibidos antes de cada linha de output para desligar comment=NA ou commnet="" |
| include | TRUE | inclui ou não o bloco no output final do documento, quando FALSE nada sera exibido mas o código será executado assim mesmo. |
2.2 Incluído gráficos do R
Até aqui vimos formatos de output de texto, vamos ver como fazer gráficos e conhecer as principais opções para controlar sua exibição.
xxxxxxxxxx```{r}# Modo baseplot(cars$speed,cars$dist)``````{r}# Usando ggplot2library(ggplot2) #poderia estar em no bloco setup por exemploggplot(cars, aes(speed, dist)) + geom_point()```Vamos altera um pouco o gráfico usando as opções do bloco. As principais opções são as seguintes:
| opção | default | descrição |
|---|---|---|
| fig.width | 7 polegadas | largura da figura |
| fig.height | 5 polegadas | altura da figura |
| fig.retina | 2 | qualidade da figura, 1 = baixa, 2 = alta |
| out.width | NA | largura que pode ser especificado em valor o em % por exemplo out.width = "20%" |
| out.height | NA | idem a descrição acima aplicada a altura. |
| dpi | 96 | pontos por polegada, alta= 300 DPI |
Vamos especificar a largura em apenas 2.5 " (polegadas)
xxxxxxxxxx```{r fig.width=2.5}# Usando ggplot2library(ggplot2) #poderia estar em no bloco setup por exemploggplot(cars, aes(speed, dist)) + geom_point()```Vamos controlar a altura e largura
```{r fig.height=5,fig.width=7}
ggplot(iris, aes(x = Sepal.Length, y = Sepal.Width,color=Species)) +
geom_jitter(alpha = 0.6) +
facet_grid(. ~ Species)
```
Especificando o percentual da largura
xxxxxxxxxx```{r, out.width = "20%"}# tamanho de 20% do originalggplot(cars, aes(speed, dist)) + geom_point()```Com as opções out.width e out.height é possível controlar qualquer tipo de output gráfico, Lembram-se da figura grande do logo do R?
```{r, out.width = "50%"}
library(knitr)
include_graphics("https://www.r-project.org/logo/Rlogo.png")
```
Esses são algumas das opções mais usadas nos output gráficos, no entanto existem outros parâmetros gráficos, como, por exemplo, margens que também devem ser levados em consideração.
2.3 formatando tabelas
Para melhorar o aspecto na apresentação de tabelas, existem varios pacotes que nos ajudar, vamos ver dois deles.
O primeiro é o pacote knitr que já deve estar instalado pois junto com o rmarkdown é um dos principais pacotes para a implementação do markdown no R.
Vamos usar a função kable que vai formatar a tabela um html , para que ela possa ser renderizadas vamos usar a opção result="asis" .
xxxxxxxxxx```{r echo = FALSE, results = 'asis'}library(knitr)kable(mtcars[1:5, ], caption = "Tabela usando a Knitr")```Um outro pacote que permite formatar tabelas e até mesmo as saídas de modelos é o pacote pander. Caso esse pacote não esteja instalado é necessário instalar ou pelo menu do rstudio ou
xxxxxxxxxxinstall.packages("pander")em seguida teste o comando.
xxxxxxxxxx```{r echo = FALSE, results = 'asis'}library(pander)pandoc.table(mtcars[1:5, ], style = "rmarkdown", caption = "Tabela usando Pander")```E por fim vamos usar o pacote pander para formatar o resultado de uma regressão logística.
xxxxxxxxxx```{r echo = FALSE, results = 'asis'}library(pander)modelo <- glm(low ~ ., family=binomial, data=MASS::birthwt)pander(modelo)```2.4 Um exemplo em Rmarkdown e considerações finais
O link abaixo contem trechos de uma aula em rmarkdown onde vários elementos podem ser encontrados.
O rmarkdown possui muitos recursos e extensões que podem ser utilizadas. Um dos pontos importantes e que por vezes você precisa de antemão saber que tipo de documento quer produzir, se HTML , PDF, etc... pois em alguns comandos avançados podem ser específicos para cada documento.
É possível injetar comandos HTML caso deseje ter esse tipo de documento ou ainda comandos em LaTeX caso quera um PDF.
Existe até um pacote chamado bookdown que permite editar livros, que podem ser hospedados na nuvem. Existem alguns livros já disponíveis nesse formato, vários deles sobre Data Science explore esses livros em (https://bookdown.org/).
REFERENCIAS
- R Markdown - Dynamic Documents for R
- O website do knitr
- O manual do knitr
- Pander
- awesome_table_in_html