42  Painéis (Dashboards) com R Markdown

Esta página cobrirá o uso básico do pacote flexdashboard. Este pacote permite que você formate facilmente a saída do R Markdown como um painel com painéis e páginas. O conteúdo do painel pode ser texto, figuras / tabelas estáticas ou gráficos interativos.

Vantagens do flexdashboard:

Desvantagens do flexdashboard:

Tutoriais muito abrangentes sobre o uso do flexdashboard que informaram esta página podem ser encontrados na seção Recursos. Abaixo descrevemos os principais recursos e damos um exemplo de construção de um painel para explorar um surto, usando os dados da lista de linha do caso.

42.1 Preparação

Carregar pacotes

Neste manual, enfatizamos p_load() de pacman, que instala o pacote se necessário e o carrega para uso. Você também pode carregar pacotes instalados com library() de base R. Veja a página em Introdução ao R para mais informações sobre pacotes R.

pacman :: p_load(
  rio, # importação / exportação de dados     
  here, # localize arquivos
  tidyverse, # gerenciamento e visualização de dados
  flexdashboard, # versões de painel de relatórios R Markdown
  shiny, # figuras interativas
  plotly # figuras interativas
)

Importar dados

Importamos o conjunto de dados de casos de uma simulação de epidemia de Ebola. Se você quiser acompanhar, clique para baixar o “clean” linelist (as .rds file). Importe dados com a função import() do pacote rio (ele lida com muitos tipos de arquivo como .xlsx, .csv, .rds - veja a página Importar e exportar para detalhes).

# importar a linelist
linelist <- import("linelist_cleaned.rds")

As primeiras 50 linhas da linelist são exibidas abaixo.

42.2 Criar novo R Markdown

Depois de instalar o pacote, crie um novo arquivo R Markdown clicando em Arquivo> Novo arquivo> R Markdown.

Na janela que se abre, selecione “Do modelo” (From template) e selecione o modelo “Flex Dashboard”. Em seguida, você será solicitado a nomear o documento. No exemplo desta página, nomearemos nosso R Markdown como “outbreak_dashboard.Rmd”.

42.3 O script

O script é um script R Markdown e, portanto, tem os mesmos componentes e organização descritos na página Relatórios com R Markdown. Nós os revisamos brevemente e destacamos as diferenças de outros formatos de saída do R Markdown.

YAML

No topo do script está o cabeçalho “YAML”. Isso deve começar com três traços --- e deve fechar com três traços ---. Os parâmetros YAML vêm em pares chave: valor. O recuo e a colocação dos dois pontos em YAML são importantes - os pares chave: valor são separados por dois pontos (e não sinais de igual!).

O YAML deve começar com metadados para o documento. A ordem desses parâmetros YAML primários (não recuados) não importa. Por exemplo:

title: "Meu documento"
author: "Eu"
date: "` r Sys.Date() `"

Você pode usar o código R em valores YAML escrevendo-o como código in-line (precedido por r dentro de crases), mas também entre aspas (veja o exemplo acima para date:).

Um parâmetro YAML necessário é output:, que especifica o tipo de arquivo a ser produzido (por exemplo, html_document,pdf_document, word_document oupowerpoint_presentation). Para flexdashboard este valor de parâmetro é um pouco confuso - ele deve ser definido como output: flexdashboard :: flex_dashboard. Observe os dois pontos simples e duplos e o sublinhado. Este parâmetro de saída YAML é frequentemente seguido por dois pontos adicionais e subparâmetros indentados (veja os parâmetros orientação: e vertical_layout: abaixo).

title: "Meu painel"
author: "Eu"
date: "` r Sys.Date() `"
output:
  flexdashboard::flex_dashboard:
    orientation: rows
    vertical_layout: scroll

Conforme mostrado acima, recuos (2 espaços) são usados para subparâmetros. Neste caso, não se esqueça de colocar dois pontos adicionais após o primário, como chave: valor:.

Se apropriado, os valores lógicos devem ser fornecidos em YAML em letras minúsculas (true,false, null). Se dois pontos fizerem parte do seu valor (por exemplo, no título), coloque o valor entre aspas. Veja os exemplos nas seções abaixo.

Blocos de código

Um script R Markdown pode conter vários “pedaços” (chunks) de código - essas são áreas do script onde você pode escrever código R de várias linhas e funcionam como mini scripts R.

Os trechos de código são criados com três marcas invertidas e chaves com um “r” minúsculo dentro. O pedaço é fechado com três crases. Você pode criar um novo bloco digitando-o você mesmo, usando o atalho de teclado “Ctrl+Alt+i” (ou Cmd+Shift+r no Mac) ou clicando no ícone verde ‘inserir um novo bloco de código’ no topo do seu editor de script. Muitos exemplos são fornecidos a seguir.

Texto narrativo

Fora de um “bloco” de código R, você pode escrever um texto narrativo. Conforme descrito na página em Relatórios com R Markdown, você pode colocar o texto em itálico circundando-o com um asterisco (*) ou em negrito circundando-o com dois asteriscos (**). Lembre-se de que os marcadores e os esquemas de numeração são sensíveis a novas linhas, recuo e acabamento de uma linha com dois espaços.

Você também pode inserir o código R nas próprias linhas de texto (in-line), conforme descrito na página Relatórios com R Markdown, circundando o código com crases e iniciando o comando com “r”: `1 + 1`(veja o exemplo com data acima).

Títulos

Diferentes níveis de título são estabelecidos com diferentes números de símbolos hash ou jogo da velha, conforme descrito na página Relatórios com R Markdown.

Em flexdashboard, um título principal (#) cria uma “página” do painel. Títulos de segundo nível (##) criam uma coluna ou uma linha dependendo do seu parâmetro orientação: (veja os detalhes abaixo). Títulos de terceiro nível (###) criam painéis para plotagens, gráficos, tabelas, texto, etc.

# Título de primeiro nível (página)

## Título de segundo nível (linha ou coluna)  

### Cabeçalho de terceiro nível (painel para plot, gráfico, etc.)

42.4 Atributos da seção

Como em uma marcação R normal, você pode especificar atributos a serem aplicados a partes do seu painel, incluindo opções key = value após um título, entre chaves {}. Por exemplo, em um relatório HTML R Markdown típico, você pode organizar subtítulos em guias com ## Meu título {.tabset}.

Observe que esses atributos são escritos após um título em uma parte do texto do script. Elas são diferentes das opções do knitr inseridas no topo dos blocos de código R, como out.height =.

Os atributos de seção específicos para flexdashboard incluem:

  • {data-orientation=} Defina para linhas oucolunas. Se o seu painel tiver várias páginas, adicione este atributo a cada página para indicar a orientação (mais explicado em seção de layout).
  • {data-width =} e {data-height =} definem o tamanho relativo dos gráficos, colunas, linhas dispostas na mesma dimensão (horizontal ou vertical). Tamanhos absolutos são ajustados para melhor preencher o espaço em qualquer dispositivo de exibição graças ao mecanismo flexbox.
    • A altura dos gráficos também depende de você definir o parâmetro YAML vertical_layout: fill ou vertical_layout: scroll. Se configurado para rolar, a altura da figura refletirá a opção tradicional fig.height = no fragmento do código R.
    • Consulte a documentação de tamanho completa no site do flexdashboard
  • {.hidden} Use isto para excluir uma página específica da barra de navegação
  • {data-navbar =} Use isso em um título de nível de página para aninhá-lo dentro de um menu suspenso da barra de navegação. Forneça o nome (entre aspas) do menu suspenso. Veja o exemplo abaixo.

42.5 Layout

Ajuste o layout do seu painel (dashboard) das seguintes maneiras:

  • Adicione páginas, colunas / linhas e gráficos com títulos R Markdown (por exemplo, #, ## ou ###)
  • Ajuste o parâmetro YAML orientation: para rows oucolumns
  • Especifique se o layout preenche o navegador ou permite rolagem
  • Adicionar guias a um título de seção específico

42.5.1 Imagens

Os títulos de primeiro nível (#) no R Markdown representarão as “páginas” do painel. Por padrão, as páginas aparecerão em uma barra de navegação na parte superior do painel.

Você pode agrupar páginas em um “menu” na barra de navegação superior adicionando o atributo {data-navmenu =} ao título da página. Tenha cuidado - não inclua espaços ao redor do sinal de igual, caso contrário, não funcionará!

Aqui está o que o script produz:

Você também pode converter uma página ou coluna em uma “barra lateral” no lado esquerdo do painel, adicionando o atributo {.sidebar}. Ele pode conter texto (visualizável em qualquer página) ou, se você tiver uma interatividade shiny integrada, pode ser útil manter os controles de entrada do usuário, como controles deslizantes ou menus suspensos.

Aqui está o que o script produz:

Orientação

Defina o parâmetro orientation: yaml para indicar como os cabeçalhos do R Markdown de segundo nível (##) devem ser interpretados - como orientation: columns ou orientação: rows.

Títulos de segundo nível (##) serão interpretados como novas colunas ou linhas com base nesta configuração de orientation.

Se você definir orientation: columns, os cabeçalhos de segundo nível criarão novas colunas no painel. O painel abaixo possui uma página, contendo duas colunas, com um total de três painéis. Você pode ajustar a largura relativa das colunas com {data-width =} conforme mostrado abaixo.

Aqui está o que o script produz:

Se você definir orientation: rows, os cabeçalhos de segundo nível criarão novas linhas em vez de colunas. Abaixo está o mesmo script acima, mas com orientation: rows para que os títulos de segundo nível produzam linhas em vez de colunas. Você pode ajustar a altura relativa das linhas com {data-height =} conforme mostrado abaixo.

Aqui está o que o script produz:

Se o seu painel tiver várias páginas, você pode designar a orientação de cada página específica adicionando o atributo {data -idance =} ao cabeçalho de cada página (especifique rows oucolumns sem aspas).

Tabs

Você pode dividir o conteúdo em guias com o atributo {.tabset}, como em outras saídas HTML R Markdown.

Basta adicionar este atributo após o título desejado. Os subtítulos sob esse título serão exibidos como guias. Por exemplo, no script de exemplo abaixo da coluna 2 à direita (##) é modificado para que a curva epidêmica e os painéis da tabela (###) sejam exibidos em guias.

Você pode fazer o mesmo com linhas se sua orientação for linhas.

Aqui está o que o script produz:

42.6 Adicionando conteúdo

Vamos começar a construir um painel (dashboard). Nosso painel simples terá 1 página, 2 colunas e 4 painéis. Vamos construir os painéis peça por peça para demonstração.

Você pode incluir facilmente saídas R padrão, como texto, ggplots e tabelas (consulte a página Tabelas para apresentação). Simplesmente codifique-os dentro de um fragmento de código R, como faria para qualquer outro script R Markdown.

Observação: você pode baixar o script Rmd finalizado e a saída do painel HTML - consulte a página Baixar manual e dados.

Texto

Você pode digitar o texto do Markdown e incluir o código in-line como para qualquer outra saída do R Markdown. Consulte a página Relatórios com R Markdown para obter detalhes.

Neste painel (dashboard), incluímos um painel de texto de resumo que inclui um texto dinâmico mostrando a última data de hospitalização e o número de casos relatados no surto.

Tabelas

Você pode incluir blocos de código R que imprimem saídas, como tabelas. Mas a saída terá uma aparência melhor e responderá ao tamanho da janela se você usar a função kable() do knitr para exibir suas tabelas. As funções flextable podem produzir tabelas que são reduzidas / cortadas.

Por exemplo, abaixo, alimentamos linelist() por meio de um comando count() para produzir uma tabela de resumo de casos por hospital. Por fim, a tabela é direcionada para knitr :: kable() e o resultado tem uma barra de rolagem à direita. Você pode ler mais sobre como personalizar sua tabela com kable() e kableExtra [aqui] (https://cran.r-project.org/web/packages/kableExtra/vignettes/awesome_table_in_html.html).

Aqui está o que o script produz:

Se você deseja mostrar uma tabela dinâmica que permite ao usuário filtrar, classificar e / ou clicar nas “páginas” do quadro de dados, use o pacote DT e sua função datatable(), como no código abaixo.

O código de exemplo abaixo, a linelist do quadro de dados é impressa. Você pode definir rownames = FALSE para conservar espaço horizontal efilter = "top"para ter filtros no topo de cada coluna. Uma lista de outras especificações pode ser fornecida para options =. Abaixo, definimos pageLength = para que 5 linhas apareçam e scrollX = para que o usuário possa usar uma barra de rolagem na parte inferior para rolar horizontalmente. O argumento class = 'white-space: nowrap' garante que cada linha seja uma linha (não várias linhas). Você pode ler sobre outros argumentos e valores possíveis aqui ou inserindo ?Datatable

DT :: datatable(linelist, 
              rownames = FALSE,
              options = list(pageLength = 5, scrollX = TRUE),
              class = 'white-space: nowrap' )

Gráficos

Você pode imprimir gráficos em um painel de controle como faria em um script R. Em nosso exemplo, usamos o pacote incidence2 para criar uma “epicurva” por faixa etária com dois comandos simples (consulte a página Curvas epidêmicas). No entanto, você pode usar ggplot() e imprimir um gráfico da mesma maneira.

Aqui está o que o script produz:

Gráficos interativos

Você também pode passar um ggplot padrão ou outro objeto de gráfico para ggplotly() do pacote plotly (consulte a página Gráficos Interativos). Isso tornará seu gráfico interativo, permitirá que o leitor “amplie” e mostre o valor de cada ponto de dados (neste cenário, o número de casos por semana e a faixa etária na curva).

age_outbreak <- incidence(linelist, date_onset, "week", groups = age_cat)
plot(age_outbreak, fill = age_cat, col_pal = muted, title = "") %>% 
  plotly::ggplotly()

Aqui está a aparência disso no painel (gif). Essa funcionalidade interativa ainda funcionará mesmo se você enviar por e-mail o painel como um arquivo estático (não online em um servidor).

Ferramentas (Widgets) HTML

HTML widgets for R são uma classe especial de pacotes R que permitem maior interatividade utilizando bibliotecas JavaScript. Você pode incorporá-los nas saídas do R Markdown (como um flexdashboard) e nos painéis do Shiny.

Alguns exemplos comuns desses widgets incluem:

  • Plotly (usado nesta página do manual e na página Gráficos interativos)
  • visNetwork (usado na página Cadeias de transmissão deste manual)  
  • Leaflet (usado na página Noções básicas de GIS deste manual)  
  • dygraphs (úteis para mostrar dados de séries temporais de forma interativa)  
  • DT (datatable()) (usado para mostrar tabelas dinâmicas com filtro, classificação, etc.)

Abaixo, demonstramos como adicionar uma cadeia de transmissão epidêmica que usa visNetwork ao painel. O script mostra apenas o novo código adicionado à seção “Coluna 2” do script R Markdown. Você pode encontrar o código na página Cadeias de transmissão deste manual.

Aqui está o que o script produz:

42.7 Organização de código

Você pode optar por ter todo o código dentro do script R Markdown flexdashboard. Como alternativa, para ter um script de painel mais limpo e conciso, você pode optar por chamar códigos / figuras que são hospedados ou criados em scripts R externos. Isso é descrito com mais detalhes na página Relatórios com R Markdown.

42.8 Shiny

A integração do pacote R shiny pode tornar seus painéis (dashboards) ainda mais reativos à entrada do usuário. Por exemplo, você pode fazer com que o usuário selecione uma jurisdição ou um intervalo de datas e os painéis reajam à sua escolha (por exemplo, filtrar os dados exibidos). Para incorporar a reatividade shiny ao flexdashboard, você só precisa fazer algumas alterações no script R Markdown do flexdashboard.

Você pode usar shiny para produzir aplicativos / painéis sem flexdashboard também. A página do manual em Dashboards with Shiny oferece uma visão geral dessa abordagem, incluindo instruções sobre sintaxe shiny, estrutura de arquivo de aplicativo e opções para compartilhamento / publicação (incluindo opções de servidor gratuitas). Essa sintaxe e dicas gerais também se traduzem no contexto do flexdashboard.

Incorporar shiny em flexdashboard é, no entanto, uma mudança fundamental em seu flexdashboard. Ele não produzirá mais uma saída HTML que você pode enviar por e-mail e qualquer pessoa pode abrir e visualizar. Em vez disso, será um “aplicativo”. O botão “Knit” na parte superior do script será substituído por um ícone “Executar documento”, que abrirá uma instância do painel interativo localmente em seu computador.

Compartilhar seu painel agora exigirá que você:

  • Envie o script Rmd para o visualizador, ele o abre em R no computador e executa o aplicativo ou
  • O aplicativo / painel é hospedado em um servidor acessível ao visualizador

Portanto, há benefícios em integrar shiny, mas também complicações. Se o compartilhamento fácil por e-mail for uma prioridade e você não precisar de recursos reativos shiny, considere a interatividade reduzida oferecida por ggplotly() conforme demonstrado acima.

Abaixo, damos um exemplo muito simples usando o mesmo “outbreak_dashboard.Rmd” acima. A documentação extensa sobre a integração do Shiny no flexdashboard está disponível online aqui.

Configurações

Habilite shiny em um flexdashboard adicionando o parâmetro YAML runtime: shiny no mesmo nível de indentação queoutput:, como abaixo:

---
title: "Painel de controle do Outbreak (demonstração Shiny)"
output: 
  flexdashboard::flex_dashboard:
    orientation: columns
    vertical_layout: fill
runtime: shiny
---

Também é conveniente habilitar uma “barra lateral” para conter os widgets de entrada shiny que coletarão informações do usuário. Como explicado acima, crie uma coluna e indique a opção {.sidebar} para criar uma barra lateral no lado esquerdo. Você pode adicionar texto e pedaços R contendo os comandos shiny entrada dentro desta coluna.

Se seu aplicativo / painel está hospedado em um servidor e pode ter vários usuários simultâneos, nomeie o primeiro fragmento de código R como global. Inclua os comandos para importar / carregar seus dados neste bloco. Esse fragmento com nome especial é tratado de maneira diferente e os dados importados dentro dele são importados apenas uma vez (não continuamente) e estão disponíveis para todos os usuários. Isso melhora a velocidade de inicialização do aplicativo.

Exemplo trabalhado

Aqui, adaptamos o script flexdashboard “outbreak_dashboard.Rmd” para incluir shiny. Adicionaremos a capacidade de o usuário selecionar um hospital em um menu suspenso e fazer com que a curva de epidemia reflita apenas os casos desse hospital, com um título de gráfico dinâmico. Fazemos o seguinte:

  • Adicione runtime: shiny ao YAML
  • Renomeie o trecho de configuração como global
  • Crie uma barra lateral contendo:
    • Código para criar um vetor de nomes de hospitais exclusivos
    • Um comando selectInput() (menu suspenso shiny) com a escolha de nomes de hospitais. A seleção é salva como hospital_choice, que pode ser referenciada no código posterior comoinput$hospital_choice
  • O código da curva epidêmica (coluna 2) está dentro de renderPlot({}), incluindo:
    • Um filtro no conjunto de dados restringindo a coluna hospital ao valor atual de input$hospital_choice
    • Um título de um gráfico dinâmico que incorpora input$hospital_choice

Observe que qualquer código que faça referência a um valor input$ deve estar dentro de uma função render({}) (para ser reativo).

Aqui está o topo do script, incluindo YAML, parte global e barra lateral:

Aqui está a Coluna 2, com o gráfico de epicurva reativa:

E aqui está o painel:

Outros exemplos

Para ler um exemplo relacionado à saúde de um Shiny - flexdashboard usando a interatividade shiny e o widget de mapeamento de leaflet, consulte este capítulo do livro online Dados de saúde geoespaciais: Modelagem e Visualização com R-INLA e Shiny.

42.9 Compartilhamento

Os painéis que não contêm elementos Shiny produzirão um arquivo HTML (.html), que pode ser enviado por e-mail (se o tamanho permitir). Isso é útil, pois você pode enviar o relatório de “painel” e não precisa configurar um servidor para hospedá-lo como um site.

Se você tiver incorporado shiny, não poderá enviar uma saída por e-mail, mas pode enviar o próprio script para um usuário R ou hospedar o painel em um servidor conforme explicado acima.

42.10 Recursos

Excelentes tutoriais que informaram esta página podem ser encontrados abaixo. Se você revisar isso, provavelmente dentro de uma hora poderá ter seu próprio painel.

https://bookdown.org/yihui/rmarkdown/dashboards.html

https://rmarkdown.rstudio.com/flexdashboard/

https://rmarkdown.rstudio.com/flexdashboard/using.html

https://rmarkdown.rstudio.com/flexdashboard/examples.html