Lab 01 · Escrever com Quarto

Markdown, equações e citações em um documento reprodutível

Como criar e renderizar um documento Quarto no Positron: formatação Markdown, blocos de código R, equações em LaTeX, callouts e citações com BibTeX.

Parte I · Documentos e linguagem

Baixar o .qmd deste Lab

Em 2004, John Gruber publicou o Markdown, uma convenção para escrever texto formatado usando apenas sinais de pontuação: asteriscos para ênfase, cerquilhas para títulos, hifens para listas. O arquivo continua legível como texto puro e pode ser convertido em HTML por um programa. Vinte anos depois, essa convenção está em quase toda ferramenta de escrita técnica, do GitHub aos assistentes de inteligência artificial.

O Quarto leva a ideia um passo adiante. Num arquivo .qmd, o texto em Markdown convive com blocos de código R que são executados no momento da renderização; os resultados, sejam números, tabelas ou gráficos, entram no documento final. O produto é um documento reprodutível (reproducible document): qualquer pessoa com o arquivo e os dados regenera o relatório inteiro, sem copiar e colar resultados. É assim que todos os Labs desta disciplina foram escritos, e é assim que você escreverá seus relatórios.

O que você vai aprender

  • Criar um documento Quarto no Positron e renderizá-lo em HTML.
  • Formatar texto, títulos, listas, tabelas, links, imagens e notas de rodapé em Markdown.
  • Distinguir um bloco de código apenas exibido de um bloco executado pelo R.
  • Escrever equações em LaTeX, na linha e em destaque.
  • Organizar o conteúdo com callouts, divs e spans.
  • Citar referências a partir de um arquivo BibTeX.

Antes de começar

Você precisa do R e do Positron instalados. O Positron é o editor de ciência de dados da Posit, e já traz o Quarto embutido; só o R precisa ser instalado à parte.

  1. Crie a pasta do projeto: File > New Folder from Template…, escolha R Project, dê um nome sem espaços nem acentos, como labs-r, e clique em Create. O Positron abre a pasta nova.
  2. Crie o documento: File > New File… e escolha Quarto Document. Salve-o com a extensão .qmd dentro da pasta, por exemplo relatorio.qmd.
  3. No topo do cabeçalho YAML, entre as linhas de três hifens, informe title: "Meu relatório" e format: html.
  4. Clique no botão Preview no canto superior direito do editor (ou pressione Cmd+Shift+K; no Windows, Ctrl+Shift+K). O Positron executa o código, converte o Markdown e mostra o resultado no painel Viewer.

O arquivo HTML fica na mesma pasta do .qmd, com o mesmo nome: relatorio.qmd gera relatorio.html, que abre em qualquer navegador e pode ser enviado por e-mail.

ImportanteAbra sempre a pasta do projeto

A pasta aberta no Positron é a pasta de trabalho (working directory) do R: todos os caminhos de dados, imagens e scripts passam a ser relativos a ela. Um .qmd aberto solto, sem pasta, faz o R procurar os arquivos onde estiver, e o mesmo código funciona num computador e falha em outro. Uma pasta por trabalho, aberta com File > Open Folder…, e o .qmd sempre dentro dela.

O Positron mostra o .qmd como texto, com o Markdown cru, que é o que este Lab ensina. Há também um modo visual, com o texto já formatado: abra a paleta de comandos (Help > Show All Commands, ou Cmd+Shift+P) e execute Quarto: Edit in Visual Mode; o mesmo comando volta ao modo texto. Baixe o .qmd deste Lab pelo botão no topo da página, abra-o no Positron e compare o fonte com o resultado: é a forma mais rápida de aprender a sintaxe.

Formatação de texto

A ênfase é marcada com asteriscos ao redor do trecho; sobrescrito e subscrito usam acento circunflexo e til.

Sintaxe Resultado
*itálico* itálico
**negrito** negrito
***itálico e negrito*** itálico e negrito
x^2^ x2
H~2~O H2O
~~riscado~~ riscado
`código` código

Um parágrafo é separado do seguinte por uma linha em branco. Uma quebra de linha simples dentro do parágrafo desaparece no resultado; para forçar a quebra, termine a linha com uma barra invertida (\).

Títulos

Um título começa com uma ou mais cerquilhas (#) seguidas de espaço. O número de cerquilhas define o nível:

# Nível 1
## Nível 2
### Nível 3
#### Nível 4
##### Nível 5
###### Nível 6

Por convenção, o nível 1 fica reservado ao título do documento, que o Quarto gera a partir do campo title do cabeçalho. As seções do texto começam em ##, e as subseções em ###. Os títulos alimentam o sumário automático (“Nesta página”, à direita); por isso o exemplo acima está num bloco de código, e não em títulos reais, que poluiriam o sumário deste Lab.

Listas

Listas não ordenadas usam -; listas ordenadas usam números seguidos de ponto. Para aninhar, recue o item com quatro espaços.

- Sinais vitais
    - Pressão arterial
    - Frequência cardíaca
        - Em repouso
- Exame físico

1. Anamnese
2. Exame físico
    1. Inspeção
    2. Palpação
  • Sinais vitais
    • Pressão arterial
    • Frequência cardíaca
      • Em repouso
  • Exame físico
  1. Anamnese
  2. Exame físico
    1. Inspeção
    2. Palpação

Uma lista de tarefas (task list) usa - [ ] para item pendente e - [x] para item concluído:

- [x] Instalar o R e o Positron
- [ ] Criar a primeira pasta de projeto
AvisoA linha em branco antes da lista

Uma lista colada ao parágrafo anterior, sem linha em branco entre eles, é lida como continuação do parágrafo. Se os itens aparecerem emendados na mesma linha, a causa é essa.

Tabelas

A tabela pipe (pipe table) separa as colunas com barras verticais. A segunda linha, feita de hifens, marca o cabeçalho; dois-pontos nela definem o alinhamento de cada coluna: :-- à esquerda, :-: centralizado, --: à direita.

| Sinal vital         | Valor  | Unidade |
|:--------------------|-------:|:-------:|
| Pressão arterial    | 120/80 | mmHg    |
| Frequência cardíaca | 72     | bpm     |
| Temperatura axilar  | 36,5   | °C      |
| Saturação de O~2~   | 98     | %       |
Sinal vital Valor Unidade
Pressão arterial 120/80 mmHg
Frequência cardíaca 72 bpm
Temperatura axilar 36,5 °C
Saturação de O2 98 %

As barras não precisam estar alinhadas no fonte; o alinhamento visual só facilita a leitura. Números ficam melhores alinhados à direita, porque as casas decimais se sobrepõem.

Notas

Uma nota de rodapé tem duas partes: a marca no texto, [^1], e a definição, [^1]: texto, em qualquer lugar do documento. Uma nota inline dispensa a definição separada: ^[texto da nota].

O IMC foi proposto por Quetelet[^quetelet] no século XIX.
Hoje é a medida antropométrica mais usada^[E também a mais criticada.].

[^quetelet]: Adolphe Quetelet (1796–1874), astrônomo e estatístico belga.

O IMC foi proposto por Quetelet1 no século XIX. Hoje é a medida antropométrica mais usada2.

O rótulo entre colchetes pode ser um número ou uma palavra; o Quarto renumera as notas na ordem em que aparecem.

Blocos de código

Há dois tipos de bloco de código, e a diferença entre eles é o centro deste Lab.

1 · Bloco exibido

Três crases abrem e fecham o bloco; o nome da linguagem depois das crases liga o realce de sintaxe. O código é mostrado, mas não executado.

```r
peso <- 70
```
peso <- 70

Serve para mostrar código que não deve rodar: um exemplo com erro proposital, um comando de instalação como install.packages() ou um trecho de outra linguagem.

2 · Bloco executado (chunk)

Com a linguagem entre chaves, {r}, o bloco vira um chunk: o R executa o código durante a renderização e insere o resultado logo abaixo.

```{r}
peso <- 70
altura <- 1.75
peso / altura^2
```
peso <- 70
altura <- 1.75
peso / altura^2
[1] 22.85714

O código aparece com fundo cinza, e o resultado, precedido por [1], vem em seguida. Se você mudar o peso e renderizar de novo, o resultado muda junto. É isso que torna o documento reprodutível.

3 · Opções do chunk

As opções vão nas primeiras linhas do chunk, cada uma iniciada por #|. As quatro mais usadas:

  • #| label: nome dá nome ao chunk. Facilita achar erros e é obrigatório para figuras referenciadas no texto.
  • #| echo: false esconde o código e mostra só o resultado.
  • #| eval: false mostra o código e não o executa.
  • #| warning: false suprime os avisos do R na saída.

Um exemplo com echo: false: o leitor vê o resultado sem ver o código que o produziu.

```{r}
#| label: imc-oculto
#| echo: false

round(peso / altura^2, 1)
```
[1] 22.9

Observe que peso e altura continuam existindo: os chunks de um mesmo documento compartilham a sessão do R e são executados na ordem em que aparecem.

DicaNomeie os chunks

Quando a renderização falha, a mensagem de erro cita o rótulo do chunk. Com rótulos como imc-exemplo, você vai direto ao problema; sem eles, o Quarto informa algo como unnamed-chunk-7.

Há um terceiro tipo, raro: o bloco de conteúdo bruto (raw content), aberto com ```{=html}, cujo conteúdo é copiado tal como está para o arquivo final, sem passar pelo Markdown.

Equações em LaTeX

Equações usam a notação do LaTeX, o sistema de tipografia científica. Entre cifrões simples a equação fica na linha (inline): $E = mc^2$ produz \(E = mc^2\). Entre cifrões duplos ela ganha uma linha própria, centralizada (display):

$$
E = mc^2
$$

\[ E = mc^2 \]

Frações usam \frac{numerador}{denominador}; letras gregas têm nome próprio (\mu, \sigma, \pi); chaves agrupam o que vai no expoente ou no índice. A densidade da distribuição normal:

$$
f(x) = \frac{1}{\sigma \sqrt{2\pi}} \, e^{-\frac{(x - \mu)^2}{2\sigma^2}}
$$

\[ f(x) = \frac{1}{\sigma \sqrt{2\pi}} \, e^{-\frac{(x - \mu)^2}{2\sigma^2}} \]

E o índice de massa corporal, calculado no chunk acima. O comando \text{} mantém as palavras em fonte normal, em vez do itálico matemático:

$$
\text{IMC} = \frac{\text{peso}}{\text{altura}^2}
$$

\[ \text{IMC} = \frac{\text{peso}}{\text{altura}^2} \]

No HTML, quem desenha as equações é o MathJax, uma biblioteca JavaScript carregada pelo navegador. A equação continua sendo texto: pode ser selecionada, copiada e lida por leitores de tela.

AvisoO cifrão solto

O $ é o interruptor do modo matemático. Num parágrafo com dois cifrões, como valores em reais, o Quarto pode interpretar o trecho entre eles como equação e embaralhar o resultado. Para escrever um cifrão literal, escape-o com barra invertida: R\$ 50 produz R$ 50.

Divs, spans e callouts

Um div é uma região de conteúdo delimitada por linhas de três dois-pontos, com uma classe ou atributo na abertura. Um span faz o mesmo com um trecho dentro da linha: o texto entre colchetes seguido da classe entre chaves. O selo “Parte I · Documentos e linguagem” no topo deste Lab é um span com a classe .topic-badge.

::: {.border .p-3}
Este parágrafo ganha uma borda.
:::

Um trecho [em cinza e menor]{.muted} dentro da frase.

Este parágrafo ganha uma borda.

Um trecho em cinza e menor dentro da frase.

Divs e spans não fazem nada sozinhos: são ganchos para o CSS do site. O uso mais comum são os callouts, blocos de destaque com ícone e cor, que o Quarto traz prontos em cinco tipos. Cada um é um div com a classe .callout- seguida do tipo; um título de nível 2 na primeira linha vira o cabeçalho do bloco.

::: {.callout-note}
## Variáveis categóricas
No R, uma variável categórica é um **factor**. Muitas vezes é preciso
declará-la explicitamente com `as.factor()`.
:::
NotaVariáveis categóricas

No R, uma variável categórica é um factor. Muitas vezes é preciso declará-la explicitamente com as.factor(), sobretudo quando os níveis foram codificados com números.

DicaPasta antes de tudo

Crie e abra a pasta do projeto no Positron antes de começar qualquer trabalho. Ela fixa a pasta de trabalho e mantém dados, código e relatório juntos.

AvisoO decimal é o ponto

O R segue a convenção da língua inglesa: o separador decimal é o ponto. 1,75 não é um número e meio; é uma sequência de dois valores, 1 e 75.

CuidadoMaiúsculas e minúsculas

O R distingue maiúsculas de minúsculas. Uma variável chamada Sexo e outra chamada sexo são objetos diferentes, e o erro object not found costuma vir daí.

ImportantePacotes no início

Carregue com library() todos os pacotes de que o documento precisa no primeiro chunk. Evite carregar pacotes que não serão usados: funções de mesmo nome em pacotes diferentes entram em conflito.

Os papéis que este material dá a cada tipo: note para nuances, tip para lições, warning para armadilhas conceituais, caution para cuidados práticos, important para regras.

Um callout pode nascer fechado, com o atributo collapse="true"; o leitor clica no título para abrir. É o formato das respostas dos exercícios na seção Pratique.

::: {.callout-tip collapse="true"}
## Resposta
O conteúdo só aparece depois do clique.
:::

O conteúdo só aparece depois do clique.

Blockquotes

Uma citação em bloco (blockquote) começa cada linha com >. Dentro dela cabe qualquer outro elemento Markdown, inclusive títulos e ênfase.

> #### Dois lemas do R
> Everything that exists is an object.\
> Everything that happens is a function call.
>
> John Chambers, um dos criadores da linguagem S

Dois lemas do R

Everything that exists is an object.
Everything that happens is a function call.

John Chambers, um dos criadores da linguagem S

Tudo o que existe é um objeto; tudo o que acontece é uma chamada de função. O R descende da linguagem S, e os dois lemas de Chambers voltam no Lab 03, quando examinarmos objetos e funções de perto.

Caracteres especiais

Sintaxe Resultado Uso
-- – meia-risca (en dash): intervalos, como 1996–2024
--- — travessão (em dash)
... … reticências
"aspas" “aspas” aspas curvas, convertidas automaticamente
\* * asterisco literal, sem ativar o itálico
&nbsp; 10 mg espaço que não quebra linha entre número e unidade

Citações com BibTeX

Citar no Quarto exige duas coisas: um arquivo de referências e uma chave para cada obra.

1 · O arquivo .bib

O arquivo .bib é um texto no formato BibTeX, em que cada entrada tem um tipo (@book, @article, @misc), uma chave única e campos como autor, título e ano.

@book{wickham2023r4ds,
  author    = {Wickham, Hadley and Çetinkaya-Rundel, Mine and Grolemund, Garrett},
  title     = {R for Data Science},
  edition   = {2},
  publisher = {O'Reilly Media},
  year      = {2023}
}

Num documento avulso, o caminho do arquivo vai no cabeçalho YAML, ao lado do título: bibliography: referencias.bib. Neste site, ele está declarado uma única vez, no arquivo de configuração _quarto.yml, e vale para todos os Labs. Um segundo campo, csl, aponta para o estilo de citação; aqui usamos o Vancouver, padrão das revistas médicas.

2 · Formas de citar

A citação é a chave precedida de @. Os colchetes, o sinal de menos e o texto depois da vírgula mudam o que aparece no documento.

Sintaxe Resultado O que faz
[@wickham2023r4ds] (1) citação entre parênteses, no fim da frase
@wickham2023r4ds (1) citação narrativa: o autor faz parte da frase
[-@wickham2023r4ds] (1) suprime o nome do autor, quando ele já foi escrito
[@gruber2004markdown; @allaire2022quarto] (2,3) várias obras de uma vez
[@xie2018rmarkdown, p. 15] (4) com localizador de página

As três primeiras linhas produzem o mesmo resultado nesta página. O Vancouver é um estilo numérico: cada obra recebe um número na ordem em que é citada pela primeira vez, o mesmo número se repete nas citações seguintes, e o nome do autor nunca aparece na citação. A distinção entre as três formas só se vê num estilo autor-data, como o APA: [@wickham2023r4ds] vira “(Wickham et al., 2023)”, @wickham2023r4ds vira “Wickham et al. (2023)” e [-@wickham2023r4ds] vira “(2023)”.

A lista completa, formatada, é montada pelo Quarto no fim do documento, na seção “Referências”, sem que você digite uma linha dela. Se trocar o arquivo CSL, as citações e a lista mudam de formato sozinhas.

DicaDe onde vem o BibTeX

Não digite entradas à mão. O Google Scholar tem um botão “Citar > BibTeX” em cada resultado, e gerenciadores como o Zotero exportam a biblioteca inteira num .bib e o mantêm atualizado. Copie a entrada, cole no arquivo e use a chave.

Pratique

1. Crie um .qmd com o título “Meu primeiro relatório”, duas seções de nível 2 (Introdução e Métodos), uma subseção de nível 3 dentro de Métodos e uma lista aninhada com pelo menos três itens. Renderize e confira o sumário.

---
title: "Meu primeiro relatório"
format: html
---

## Introdução

Texto da introdução.

## Métodos

### Coleta de dados

- Instrumentos
    - Questionário
    - Prontuário
- Participantes

O sumário mostra Introdução e Métodos como itens de primeiro nível e Coleta de dados aninhado em Métodos. O título do documento vem do YAML, não de um #.

2. Monte uma tabela com quatro sinais vitais (pressão arterial, frequência cardíaca, frequência respiratória e temperatura), com as colunas Sinal, Valor e Unidade; a coluna de valores alinhada à direita e a de unidades centralizada.

| Sinal                   | Valor  | Unidade |
|:------------------------|-------:|:-------:|
| Pressão arterial        | 120/80 | mmHg    |
| Frequência cardíaca     | 72     | bpm     |
| Frequência respiratória | 16     | irpm    |
| Temperatura axilar      | 36,5   | °C      |
Sinal Valor Unidade
Pressão arterial 120/80 mmHg
Frequência cardíaca 72 bpm
Frequência respiratória 16 irpm
Temperatura axilar 36,5 °C

3. A pressão arterial média (PAM) é estimada por PAM = PAD + (PAS − PAD)/3, em que PAS e PAD são as pressões sistólica e diastólica. Escreva a fórmula em LaTeX na linha e em destaque, usando \frac, e calcule num chunk a PAM de um paciente com 120/80 mmHg.

Na linha: $\text{PAM} = \text{PAD} + \frac{\text{PAS} - \text{PAD}}{3}$.

Em destaque:

$$
\text{PAM} = \text{PAD} + \frac{\text{PAS} - \text{PAD}}{3}
$$

```{r}
#| label: pam

pas <- 120
pad <- 80
pad + (pas - pad) / 3
```

Na linha: \(\text{PAM} = \text{PAD} + \frac{\text{PAS} - \text{PAD}}{3}\). Em destaque:

\[ \text{PAM} = \text{PAD} + \frac{\text{PAS} - \text{PAD}}{3} \]

pas <- 120
pad <- 80
pad + (pas - pad) / 3
[1] 93.33333

A PAM fica em torno de 93 mmHg. O cálculo no chunk é o mesmo da fórmula, com / no lugar de \frac.

4. Escreva um callout warning com o título “Decimal é ponto” e um callout tip colapsado com o título “Resposta”, cada um com uma frase de sua escolha.

::: {.callout-warning}
## Decimal é ponto
No R, escreva 1.75, e não 1,75.
:::

::: {.callout-tip collapse="true"}
## Resposta
Este texto só aparece depois do clique.
:::

O tipo vai na classe (.callout-warning, .callout-tip), o título é o ## da primeira linha, e collapse="true" fecha o bloco por padrão.

5. Adicione ao seu .bib a entrada abaixo, do livro R Markdown: The Definitive Guide, e cite-a de três formas: entre parênteses, narrativa e com página. Renderize e confira a lista de referências no fim do documento.

@book{xie2018rmarkdown,
  author    = {Xie, Yihui and Allaire, J. J. and Grolemund, Garrett},
  title     = {R Markdown: The Definitive Guide},
  publisher = {Chapman and Hall/CRC},
  address   = {Boca Raton, FL},
  year      = {2018}
}
O R Markdown antecedeu o Quarto [@xie2018rmarkdown].

@xie2018rmarkdown descrevem o formato em detalhe.

A sintaxe dos chunks está no capítulo 2 [@xie2018rmarkdown, p. 15].

Com o estilo Vancouver, as três citações recebem o mesmo número, porque são a mesma obra, e a entrada aparece uma única vez na lista. Só a terceira se distingue, pelo localizador de página. Troque o csl por um estilo autor-data para ver as três formas ficarem diferentes.

Resumo

Um arquivo .qmd reúne texto em Markdown, código R executável e metadados num único documento reprodutível. O Markdown formata com sinais de pontuação: asteriscos para ênfase, cerquilhas para títulos, hifens para listas, barras verticais para tabelas. Um bloco entre crases com {r} é executado, e o resultado entra no documento; sem as chaves, o código é apenas exibido. Equações usam LaTeX entre cifrões, desenhadas pelo MathJax no navegador. Citações vêm de um arquivo BibTeX: [@chave] no texto, lista formatada no fim.

Cheatsheet

Quero Escrevo
itálico, negrito *texto*, **texto**
título de seção ## Título
lista - item ou 1. item
lista de tarefas - [ ] pendente, - [x] feito
link [texto](https://endereco)
imagem ![legenda](caminho.png){width=50%}
tabela barras verticais entre as colunas; :--, :-: e --: alinham
nota de rodapé [^1] no texto e [^1]: texto na definição
código exibido ```r … ```
código executado ```{r} … ```
equação na linha $x^2$
equação em destaque $$ x^2 $$
callout ::: {.callout-tip} … :::
citação em bloco > texto
citação bibliográfica [@chave]
vídeo {{< video https://youtu.be/... >}}

Veja também

Referências

A sintaxe apresentada aqui segue a especificação original do Markdown (2) e a documentação do Quarto (3). A ideia do documento reprodutível, com texto e código no mesmo arquivo, vem do R Markdown (4), antecessor do Quarto, e atravessa todo o livro de Wickham, Çetinkaya-Rundel e Grolemund (1), que acompanha esta disciplina.

1.
Wickham H, Çetinkaya-Rundel M, Grolemund G. R for Data Science: Import, Tidy, Transform, Visualize, and Model Data [Internet]. 2º ed. Sebastopol, CA: O’Reilly Media; 2023. Disponível em: https://r4ds.hadley.nz/
2.
Gruber J. Markdown [Internet]. Daring Fireball; 2004. Disponível em: https://daringfireball.net/projects/markdown/
3.
Allaire JJ, Teague C, Xie Y, Dervieux C. Quarto [Internet]. 2022. Disponível em: https://quarto.org
4.
Xie Y, Allaire JJ, Grolemund G. R Markdown: The Definitive Guide [Internet]. Boca Raton, FL: Chapman; Hall/CRC; 2018. Disponível em: https://bookdown.org/yihui/rmarkdown/
NotaPróximos passos

O Lab 02 apresenta o Mermaid, uma linguagem de diagramas escrita em texto que o Quarto renderiza no documento: um fluxograma de conduta clínica, um cronograma de Gantt para o projeto de pesquisa e uma linha do tempo da história do R.

Notas de rodapé

  1. Adolphe Quetelet (1796–1874), astrônomo e estatístico belga.↩︎

  2. E também a mais criticada, porque não distingue massa magra de gordura.↩︎