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:

  1. Permanentemente, modificando o cabeçalho YAML:

    title: "Tamanhos de diamante"
format: html

  2. Pontualmente, executando quarto::quarto_render() manualmente:

    quarto::quarto_render("diamond-sizes.qmd", output_format = "docx")

    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:

  1. revealjs - apresentações HTML com revealjs

  2. pptx - apresentações PowerPoint

  3. beamer - 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)

Duas caixas de input, uma acima da outra. A de cima diz "What is your name?", ou "Qual é seu nome" em inglês, e a de baixo "How old are you?" ou "Qual é a sua idade?" em inglês.

É 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 de project para book ou website 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:

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: