quarto::quarto_render("diamond-sizes.qmd", output_format = "docx")
29 ✅ Formatos para Quarto
29.1 Introdução
Até agora você viu o Quarto sendo usado para produzir documentos HTML. Este capítulo dá uma visão geral de alguns dos muitos outros tipos de saída (output) que você pode produzir com Quarto.
Há duas formas de configurar a saída do documento:
-
Permanentemente, modificando o cabeçalho YAML:
title: "Tamanhos de diamante" format: html
-
Pontualmente, executando
quarto::quarto_render()
manualmente:Isso é útil quando se deseja programaticamente produzir múltiplos tipos de saída ja que o argumento
output_format
também pode receber uma lista de valores.quarto::quarto_render("diamond-sizes.qmd", output_format = c("docx", "pdf"))
29.2 Opções de saída
O Quarto oferece uma ampla variedade de formatos de saída. É possível achar a lista completa em https://quarto.org/docs/output-formats/all-formats.html. Muitos formatos compartilham configurações de seu resultado (por exemplo, toc: true
para incluir um sumário), mas outros têm configurações que são específicas do formato (por exemplo, code-fold: true
colapsa os blocos de código em uma tag HTML <details>
de modo que o usuário possa exibí-lo quando quiser, e não é aplicável a um documento PDF ou Word).
Para sobrescrever as opções padrão, é necessário usar um campo format
extendido. Por exemplo, se quiser renderizar um html
com um sumário flutuante, é necessário usar:
format:
html:
toc: true
toc_float: true
É possível ainda renderizar múltiplas saídas fornecendo uma lista de formatos:
format:
html:
toc: true
toc_float: true
pdf: default
docx: default
Note a sintaxe especial (pdf: default
) caso não queira sobrescrever nenhuma das opções padrão.
Para renderizar todos os formatos especificados no YAML do documento, use output_format = "all"
.
quarto::quarto_render("diamond-sizes.qmd", output_format = "all")
29.3 Documentos
O foco do capítulo anterior era a saída padrão html
. Existem diversas variações básicas nesse tema, gerando diferentes tipos de documentos. Por exemplo:
pdf
produz um PDF com LaTeX (um systema de diagramação/layout de código aberto/open-source), que precisará ser instalado. O RStudio emitirá um aviso se ainda não estiver instalado.docx
para um documento Microsoft Word (.docx
).odt
para um documento OpenDocument Text (.odt
).rtf
para um documento Rich Text Format (.rtf
).gfm
para um documento GitHub Flavored Markdown (.md
).ipynb
para um caderno Jupyter (.ipynb
).
Lembre-se que ao gerar um documento para compartilhar com tomadores de decisão é possível inativar a exibição padrão de código configurando opções globais no YAML do documento:
execute:
echo: false
Para documentos html
, outra opção é fazer com que os blocos de código fiquem escondidos por padrão, mas visíveis se clicados:
format:
html:
code: true
29.4 Apresentações
Também é possível usar o Quarto para produzir apresentações. O controle visual é menor do que se teria usando uma ferramenta como Keynote ou Powerpoint, mas inserir automaticamente resultados do seu código em R nas apresentações pode economizar muito tempo. Em apresentações o conteúdo do trabalho é dividido em slides, com um novo slide começando em cada marcador de título de nível 2 (##
). Além disso, títulos de nível 1 (#
) indicam o começo de uma nova seção com um slide de título de seção que, por padrão, fica centralizado no meio do slide.
Uma variedade de formatos de apresentação têm suporte em Quarto, incluindo:
revealjs
- apresentações HTML com revealjspptx
- apresentações PowerPointbeamer
- apresentações PDF com LaTeX Beamer.
Leia mais sobre a criação de apresentações com Quarto em https://quarto.org/docs/presentations.
29.5 Interatividade
Assim como em qualquer documento HTML, documentos nesse formato criados com Quarto podem conter elementos interativos também. Aqui introduzimos duas opções para incluir interatividade em seus documentos Quarto: htmlwidgets e Shiny.
29.5.1 htmlwidgets
HTML é um formato interativo e é possível aproveitar essa qualidade com htmlwidgets, funções de R que produzem visualizações interativas em HTML. Por exemplo, veja o mapa leaflet abaixo. Se você está vendo essa página na internet, é possível mover o mapa, aumentar ou diminuir o zoom, etc. Obviamente isso não é possível em um livro, entao uma visualização estática é automaticamente inserida pelo Quarto.
library(leaflet)
leaflet() |>
setView(174.764, -36.877, zoom = 16) |>
addTiles() |>
addMarkers(174.764, -36.877, popup = "Maungawhau")
Uma ótima notícia sobre htmlwidgets é que você não precisa saber nada de HTML ou de JavaScript para usá-las. Todos os detalhes são incluídos no pacote, então não precisa se preocupar sobre isso.
Há muitos pacotes que fornecem htmlwidgets, incluindo:
dygraphs para visualizações de séries temporais interativas.
DT para tabelas interativas.
threejs para gráficos 3D interativos.
DiagrammeR para diagramas (como diagramas de fluxo ou diagramas simples de nó e aresta – grafos).
Para aprender mais sobre htmlwidgets e ver uma lista completa de pacotes que os fornecem, visite https://www.htmlwidgets.org.
29.5.2 Shiny
htmlwidgets fornecem interatividade client-side (do lado do cliente ou, em liguagem comum, do usuário) — toda a interatividade ocorre no navegador, independente do R. Por um lado, isso é ótimo porque é possível distribuir o arquivo HTML sem qualquer conexão com R. No entanto, isso limita fundamentalmente o que se pode fazer ao que foi implementado em HTML e JavaScript. Uma abordagem alternativa é usar shiny, um pacote que permite criar interativamente usando R em vez de JavaScript.
Para fazer chamadas de código Shiny em um documento Quarto, inclua server: shiny
no cabeçalho YAML:
title: "Shiny Web App"
format: html
server: shiny
Depois você pode usar as funções “input” para adicionar componentes interativos ao documento:
library(shiny)
textInput("name", "What is your name?")
numericInput("age", "How old are you?", NA, min = 0, max = 150)
É necessário também um bloco de código com a opção context: server
que contém o código que precisa ser executado em um servidor Shiny.
Você pode fazer referência aos valores com input$name
e input$age
, fazendo com que o código que os usa seja novamente executado toda vez que são alterados.
Não podemos mostrar um app shiny sendo executado porque as interações ocorrem no server-side (do lado do servidor). Isso significa que é possível escrever apps interativos sem saber JavaScript, mas é necessário um servidor para hospedá-los. Isso introduz um problema logístico: aplicativos Shiny precisam de um servidor Shiny para serem executados online. Quando se executa aplicativos Shiny em seu próprio computador, um servidor Shiny é automaticamente configurado para você, mas é necessário um servidor de acesso público se quiser publicar esse tipo de interatividade on-line. Essa é a troca fundamental de shiny: qualquer coisa que você faria em R você pode fazer em um documento shiny, mas isso requer alguém executando R.
Para aprender mais sobre Shiny, recomendamos a leitura do livro Mastering Shiny por Hadley Wickham, https://mastering-shiny.org.
29.6 Sites e livros
Com um pouco de infraestrutura adicional é possível usar o Quarto para gerar um site completo ou um livro:
Coloque seus arquivos
.qmd
em um único diretório.index.qmd
se tornará a página principal — a home page.-
Adicione um arquivo YAML chamado
_quarto.yml
que fornece a navegação para o site. Nesse arquivo, ajuste o tipo deproject
parabook
ouwebsite
para livro ou site respectivamente:project: type: book
Por exemplo, o arquivo _quarto.yml
a seguir cria um site a partir de três arquivos: index.qmd
(a página inicial), viridis-colors.qmd
, e terrain-colors.qmd
.
project:
type: website
website:
title: "A website on color scales"
navbar:
left:
- href: index.qmd
text: Home
- href: viridis-colors.qmd
text: Viridis colors
- href: terrain-colors.qmd
text: Terrain colors
O arquivo _quarto.yml
necessário para um livro é estruturado de forma muito similar. O exemplo a seguir mostra como é possível criar um livro com quatro capítulos que renderizam três tipos diferentes de output (html
, pdf
, e epub
). Mais uma vez os arquivos fonte são arquivos .qmd
.
project:
type: book
book:
title: "A book on color scales"
author: "Jane Coloriste"
chapters:
- index.qmd
- intro.qmd
- viridis-colors.qmd
- terrain-colors.qmd
format:
html:
theme: cosmo
pdf: default
epub: default
Recomendamos que você use um projeto do RStudio para seus sites e livros. Baseado no arquivo _quarto.yml
o RStudio reconhecerá o tipo de projeto em que está trabalhado, adicionará uma aba Build à IDE que você pode usar para renderizar e visualizar prévias de seus sites e livros. Tanto sites como livros também podem ser renderizados usando quarto::render()
.
Leia mais em https://quarto.org/docs/websites sobre sites Quarto e em https://quarto.org/docs/books sobre livros.
29.7 Outros formatos
Quarto oferece ainda mais formatos de output:
Você pode escrever artigos usando Quarto Journal Templates: https://quarto.org/docs/journals/templates.html.
Você pode transformar documentos Quarto em formato de notebooks do Jupyter com
format: ipynb
: https://quarto.org/docs/reference/formats/ipynb.html.
Veja https://quarto.org/docs/output-formats/all-formats.html para uma lista com ainda mais formatos.
29.8 Resumo
Neste capítulo apresentamos uma variedade de opções para comunicar seus resultados com Quarto, de documentos estáticos e interativos a apresentações, sites e livros.
Para aprender mais sobre comunicação efetiva nesses diferentes formatos, recomendamos os seguintes recursos:
Para melhorar suas habilidades de apresentação, experimente Presentation Patterns por Neal Ford, Matthew McCollough, e Nathaniel Schutta. O recurso fornece um conjunto de padrões efetivos (de alto e baixo nível) que você pode adotar para melhorar suas apresentações.
Se você dá palestras acadêmicas, você pode gostar de Leek group guide to giving talks.
Não experimentamos pessoalmente, mas ouvimos coisas boas sobre o curso online de Matt McGarrity’s sobre apresentação ao público: https://www.coursera.org/learn/public-speaking.
Se você está criando muitos painéis (dashboards), leia Information Dashboard Design: The Effective Visual Communication of Data de Stephen Few. Isso ajudará a criar painéis que são realmente úteis, não apenas agradáveis de olhar.
Conhecimento sobre design gráfico muitas vezes beneficia a comunicação efetiva das suas ideias. The Non-Designer’s Design Book de Robin Williams é um ótimo lugar para começar.