Iniciação ao RMarkdown

Introdução
Sintaxe do Markdown
Criando um Documento Dinâmico
Referências

Introdução

“Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to humans what we want the computer to do.”

Donald Knuth

Markdown é uma linguagem de marcação simplificada para escrever textos de maneira que o autor foque no texto e não na formatação, diferente de outras linguagens de marcação como HTML e \(LaTeX\) que fazem uso de muitas tags, o que dificulta a leitura do código fonte.

O RMarkdown permite entrelaçar códigos LaTeX e HTML com códigos R e de outras linguagens como Phyton e C++ podendo gerar textos em vários formatos: HTML, PDF e DOC.

O preço a se pagar pela versatilidade em gerar tantos formatos com o mesmo código é a perda de funcionalidades, pois existem coisas que não são iguais nos formatos citados anteriormente. Mas isto pode ser contornado com a funcionalidade de entrelaçar códigos, logo caso não seja possível gerar algo com o markdown para um documento HTML, é possível usar a tag HTML correspondente para obter o resultado esperado, o mesmo vale para o caso PDF que basta utilizar o código \(LaTeX\) correspondente.

O RMarkdown pode ser utilizado para fazer apresentações em slides, documentos dinâmicos, criação de páginas web e outras aplicações.

Este post será focado na sintaxe e confecção de um relatório dinâmico em RMarkdown.

Sintaxe do Markdown

Títulos/Subtítulos ou Seções/Subseções

A importância do título será dada pela quantidade de #:

# Título 1
## Título 2
### Título 3
#### Título 4
##### Título 5
###### Título 6

Itálico

_itálico_ ou *itálico*

itálico ou itálico

Negrito

__negrito__ ou **negrito**

negrito ou negrito

Tachado

~~tachado~~

~~tachado~~

Sobrescrito

texto^sobrescrito^

texto^sobrescrito

Parágrafo

Para gerar um novo parágrafo é necessário pular uma linha ou dar três espaços(pressionar duas vezes a tecla TAB) ao final do parágrafo:

Parágrafo

Novo parágrafo

Parágrafo

Novo parágrafo

Parágrafo   
Novo parágrafo

Parágrafo
Novo parágrafo

Lista Não-Ordenada

- Primeiro item
- Segundo item
- Terceiro item

Primeiro item
Segundo item
Terceiro item

Lista Ordenada

1. Primeiro item
2. Segundo item
3. Terceiro item

Primeiro item
Segundo item
Terceiro item

Lista com Sublista

Usa-se quatro espaços(duas vezes a tecla TAB) abaixo de um item para criar um sub-item:

1. Item
    - Um sub-item
    - Outro sub-item

Item
- Um sub-item
- Outro sub-item

Tabela

Para gerar uma tabela, são usados ao menos 3 --- para separar o nome da coluna das linhas e | para delimitar as colunas, sempre mantendo a identação como a seguir.

Cabeçalho | Cabeçalho 2
--------- | -------------
Célula    | Célula 2
Célula 3  | Célula 4

Cabeçalho	Cabeçalho 2
Célula	Célula 2
Célula 3	Célula 4

Para alinhar as colunas:

. Alinhar à esquerda: :---;
. Alinhar ao centro: :---:;
. Alinhar à direita: ---:.

 Esquerda | Centro      | Direita 
:-------- | :----------:| ----------:
  Célula  | Célula      | Célula

Esquerda	Centro	Direita
Célula	Célula	Célula

Link

Para um link usa-se a seguinte sintaxe:

[nome do link](endereço do link)
[Site do PET](https://pet-estatistica.github.io/site/)

Se quiser que o nome do link seja ele próprio:

https://pet-estatistica.github.io/site/

https://pet-estatistica.github.io/site/

Pode ser um link com título, que é o nome que aparece se o cursor for deixado em cima do link:

[Link com título](https://pet-estatistica.github.io/site/ "Site do PET")

Link com título

No caso em que se sabe que um link será usado mais vezes num mesmo documento ou por comodidade, é possível escrever o link no fim do documento [tag do link]: link e chamá-lo no meio do documento da seguinte maneira:

site da UFPR [aqui][UFPR]
         
         ...

...fim do documento...
[UFPR]: http://www.ufpr.br/portalufpr/

site da UFPR aqui

Imagem

Para usar uma imagem da web:

#![legenda da imagem](link da imagem)
#![Logo do R](http://developer.r-project.org/Logo/Rlogo-5.png)

Logo do R

Para usar uma imagem do computador:

![legenda da imagem](/caminho/da/imagem.png)

legenda da imagem

Imagens também podem ser referenciadas como os links:

![Imagem referenciada][imagem]
         
         ...

...fim do documento...
[imagem]: http://developer.r-project.org/Logo/Rlogo-5.png

Imagem referenciada

É possível colocar parâmetros na imagem. Como exemplo o símbolo do R será aumentado e reduzido:

Imagem Aumentada

Imagem redizida

É possível fazer com que uma imagem contenha um link:

[![legenda da imagem](caminho da imagem)](link)

Citação em Bloco

> citação de alguma frase impactante de autor famoso 
e bem conceituado.

citação de alguma frase impactante de autor famoso e bem conceituado.

Também pode ser em níveis como nos títulos:

> citação nível 1

>> citação nível 2

>>> citação nível 3

citação nível 1

citação nível 2

citação nível 3

Ancoragem Interna

É possível ancorar num documento markdown como é feito em um HTML da seguinte maneira:

[pular para lista com sublista](#lista-com-sublista)

pular para lista com sublista

Mas existem restrições. o nome da seção ou subseção que se quer ancorar deve ser precedida de uma #, ser escrita em caixa baixa, se tiver mais que uma palavra elas devem ser separadas por - e não funcionará se tiver caracteres especiais, como ~, ^ e ç. Este problema pode ser contornado ignorando caracteres especiais. Como exemplo, vamos ancorar a Introdução:

Primeiro título^[1](#introducao)^

Primeiro título¹

Régua Horizontal

***

Criando um Documento Dinâmico

O primeiro passo é instalar o pacote rmarkdown:

install.packages("rmarkdown")

Cabeçalho

O cabeçalho do seu documento que terá os metadados que controlarão a formatação do documento e é feito no formato YAMl num estilo lista aninhada delimitada por ---, como no exemplo a seguir:

title: "Título do Documento"
author: "Nome do Autor"
date: "20 de maio, 2019" 
output: html_document

Com algumas variações e mais opções:

title: "Título do Documento"
author:                         # No caso de ter mais de um autor
- Autor 1
- Autor 2
- Autor 3
date: r Sys.Date() entre "``" # Para pegar automaticamente a data do computador                                
output:          # No caso de se ter opções para o formato do output
  pdf_document
    fontsize: 11pt        # Muda o tamanho da fonte
    highlight: "zenburn"  # A forma que os textos destacados aparecerão
    number_sections: true # Numerar as seções
    toc: TRUE             # Adiciona um sumário ao documento
    toc_depth: 2          # O número mínimo de '#' para gerar um item no sumário

OBS: dependendo do tipo de output, algumas opções não funcionarão.

OBS2: A identações são muito importantes.

Chunks e Códigos em Linha

Chunks de código são ambientes para inserir códigos que serão executados durante a compilação do documento e o mesmo pode ser feito com código em linha.

Sintaxe do chunk

paste("Olá Mundo!")

## [1] "Olá Mundo!"

Sintaxe do código em linha

Olá Mundo!

Também existem opções de chunk:

echo =:
- TRUE o código fonte será mostrado no documento final;
- FALSE o códico fonte é omitido do documento final.

paste("Olá Mundo!")

## [1] "Olá Mundo!"

results =:
- hide os outputs do código serão omitodos do documento final;
- hold os outputs do chunk serão mostrado somente ao final do chunk;
- asis os outputs não serão formatados para o documento final;
- markup marca os outputs.

paste("Olá Mundo!")

[1] “Olá Mundo!”

Podem ser usadas mais que uma opção de chunk ao mesmo tempo, basta separa-las por ,.

Para maia opções de preâmbulo e chunk, segue o Guia de Referência

Exemplo

Vamos a um pequeno exemplo de como funciona o dinamismo do RMarkdown. Usando uma base de dados serão oferecidas diferentes respostas baseadas nas médias dos dados e também uma breve análise exploratória com um gráfico e uma tabela.

Criando a base, objetos e tabela a serem usadas:

x <- c(1,2,3,4,5,6,7,8)
y <- c(-1,-2,-3,4,-5,6,7,-8)
dados <- data.frame(var1 = x, var2 = y)
mvar1 <- mean(dados$var1)
mvar2 <- mean(dados$var2)
teste <- function(x){
  if(x > 0){
    out <- "tem média maior que zero"
  }
  else{
    out <- "tem média menor que zero"
  }
  return(out)
}
tab <- kableExtra::kable(dados, format = "markdown")