R Notebook é um modo de execução de documentos R Markdown como uma interface de notebook para literate programming

Este é o nosso sexto artigo da série sobre produção de documentos com Markdown, uma linguagem de marcação simples e muito útil para produzir praticamente qualquer tipo de documento técnico, acadêmico, para a Web, etc.

No primeiro artigo da série fizemos uma pequena introdução sobre linguagens de marcação e apresentamos a sintaxe básica.

No segundo artigo apresentamos o Pandoc, que é um conversor entre diversos tipos de linguagens e formatos de documento, que também possui uma implementação Markdown.

No terceiro artigo apresentamos o Limarka, uma ferramenta capaz de gerar arquivos PDF de documentos acadêmicos conforme as Normas da ABNT a partir de textos em Markdown.

No quarto e no quinto artigos da série apresentamos o R Markdown, que é uma ferramenta capaz de produzir documentos dinâmicos a partir da mistura de trechos de código em R (e outras linguagens de programação) com texto Markdown.

Neste artigo apresentamos o R Notebook, que é uma espécie de modo de execução específico de documentos R Markdown, com características e funcionalidades sutilmente diferentes que lhe conferem casos de uso próprios.

Documentação com Markdown: Literate programming com R Notebook

Sumário do artigo

Introdução

R Notebook é, em certo sentido, uma forma de trabalhar num documento R Markdown, que mistura texto em Markdown com trechos de código executável em linguagem R e em outras linguagens de programação, conforme já apresentamos nos artigos anteriores desta série.

O R Markdown é um componente central do R notebook (que também pode ser chamado de R Markdown Notebook). O RStudio define o notebook como:

“um documento R Markdown com chunks que podem ser executados de forma independente e interativa, com a saída visível imediatamente abaixo da entrada”.

R notebooks são uma implementação de literate programming que permite a interação direta com R em um ambiente de computational notebook interface simultaneamente à produção de um documento reproduzível com qualidade de publicação.

Para melhor compreensão da natureza de um documento R notebook entendo que seja necessária uma sucinta introdução conceitual a respeito de literate programming e computational notebook interface.

Literate Programming

Literate programming (que poderia ser traduzido para “programação letrada” ou “programação literária”, mas vamos ficar com o anglicismo neste caso), é um paradigma concebido por Donald Knuth em 1984.

Concretamente, literate programming consiste na produção de documentos que “entrelaçam” texto e código. O texto é legível para humanos e o código é legível para máquinas. O documento é composto por uma série trechos de texto e blocos de código (code chunks).

Nas palavras de Donald Knuth:

“Em vez de imaginar que nossa principal tarefa é instruir um computador sobre o que fazer, vamos nos concentrar em explicar aos humanos o que queremos que o computador faça”. (KNUTH, 1992)

O paradigma de literate programming, conforme concebido por Knuth, representa um afastamento da escrita de algoritimos na forma e ordem “impostas” pelo computador e, em vez disso, permite que os programadores desenvolvam programas de acordo com a lógica e o fluxo de seus pensamentos. Os programas ou documentos “literate programming” são escritos como uma exposição ininterrupta da lógica em uma linguagem humana comum, muito similar ao texto de um ensaio.

Na prática, literate programming consiste na combinação da documentação (legível por humanos) e código (legível pela máquina) em um único arquivo fonte, de modo a manter uma correspondência próxima entre a documentação e o código fonte. A ordem e a estrutura desse arquivo são especificamente projetadas para auxiliar a compreensão humana: código e documentação juntos são organizados em ordem lógica e/ou hierárquica. Ao mesmo tempo, a estrutura e o formato dos arquivos fonte interagem com utilitários externos que geram a documentação do programa e/ou extraem o código legível por máquina dos mesmos arquivos fontes (para processamento subsequente).

Para ser possível um sistema como este é necessário uma linguagem de marcação pra o texto e documentação (como LaTaX ou Markdown, por exemplo), e uma linguagem de programação que será compilada com o documento (como R ou Python, por exemplo).

O primeiro “ambiente” de literate programming desenvolvido foi chamado de WEB, criado pelo próprio Donald Knuth em 1981 para seu sistema de tipografia TeX. O WEB mistura a linguagem de programação Pascal com a linguagem de marcação TeX para tipografia e documentação.

Atualmente existem muitos outros sistemas e ferramentas que misturam código com texto, com uso de diferentes linguagens de marcação e de programação.

Computational Notebook Interface

Computational Notebook Interface (que poderia ser traduzido para “interface computacional de bloco de notas”, mas vamos manter o anglicismo também neste caso) é um ambiente de notebook virtual usado com o paradigma literate programming.

O core da ideia de notebook é o de um conjunto de ferramentas capazes de viabilizar o paradigma de literate programming na medida em que permitam a organização das partes de um programa em qualquer ordem e sejam capazes de extrair documentação e código a partir do mesmo arquivo de origem.

O conceito moderno de Computational Notebook Interface parte desta abordagem e a eleva a um novo nível, adicionando algumas funcionalidades gráficas e foco na interatividade. Segundo Stephen Wolfram:

“A ideia de um notebook é ter um documento interativo que misture livremente código, resultados, gráficos, texto e tudo mais”. (WOLFRAM, 2018)

Os notebooks são tradicionalmente usados ​​nas ciências como “cadernos eletrônicos” para documentar procedimentos de pesquisa, dados, cálculos e descobertas. Com o uso dos notebook é possível “acompanhar” a metodologia para tornar mais fácil a reprodução de resultados e cálculos com diferentes conjuntos de dados. Na educação, a interface de notebook fornece um ambiente de aprendizagem digital, particularmente útil para o ensino do pensamento computacional.

Devido à sua capacidade de exibir dados visualmente e recuperar dados de diferentes fontes, modificando o código e o próprio texto, os notebooks também estão entrando no campo dos softwares de inteligência de negócios, além dos documentos de inteligência de dados em geral. Um laudo de avaliação imobiliária ou um relatório de estudo de viabilidade econômica, por exemplo, podem ser construídos a partir da mistura de texto, código e seus resultados em um ambiente de Computational Notebook Interface.

R Markdown e R notebook

R notebook e R Markdown são a mesma coisa em muitos sentidos, mas não exatamente a mesma coisa. Tecnicamente R Markdown refere-se ao tipo de arquivo - com extensão .Rmd e capaz de conter tanto texto simples com sintaxe de marcação Markdown quanto trechos de código executáveis de linguagens de programação - enquanto R Notebook é uma forma específica de trabalhar com arquivos R Markdown.

Embora o R Markdown em si já seja um tipo de implementação do paradigma literate programming e a sua utilização no software Rstudio tenha características suficientes para ser considerada uma computational notebook interface, são estes conceitos que “diferenciam” o R Markdown do R notebook, sendo o R Notebook uma implementação de literate programming em uma interface de computational notebook mais conceitualmente alinhada com o significado destes termos.

A mistura entre texto e código está na raiz do que é o R Markdown e o R Notebook (que tecnicamente é um tipo de documento R Markdown) e também dos dois conceitos acima citados (literate programming e notebook interface). Numa tentativa grosseira e simplificada de diferenciá-los conceitualmente, poderíamos dizer que:

  • R Markdown (ou seja, um documento R Markdown que não sejam um R Notebook) teria como foco a produção de um documento que “também” inclua código executável misturado aos parágrafos e outros elementos, de modo que possa ser um documento dinâmico;

  • R Notebook teria como foco o desenvolvimento do código em si, para programação, computação científica ou análise de dados em um ambiente interativo (notebook interface) e a partir de uma abordagem ou paradigma de desenvolvimento que trata o algoritmo como literatura compreensível por seres humanos (literate programming) de forma que “também” se configure como um documento reproduzível.

Dentre outras características, um R Notebook é um documento R Markdown que permite a execução independente e interativa dos chunks de código, o que permite avaliar visualmente a saída à medida que se desenvolve o documento, análise ou programa, sem ter que “dar Knit” em todo o documento para ver a saída. Os recursos interativos do “modo notebook” o tornam bastante útil para escrever documentos “R Markdown notebook” e iterar o código.

Um R notebook pode ser considerado, portanto, um modo de execução especial para documentos R Markdown.

É importante mencionar que qualquer documento R Markdown pode ser usado como um R notebook e todos os R notebook podem ser renderizados para outros formatos de documento de saída suportados pelo R Markdown.

Neste artigo vamos nos concentrar nas particularidades do R notebook em relação a um documento R Markdown “normal”, cuja anatomia é essencialmente a mesma, de modo que é importante que os dois artigos anteriores desta série, nos quais apresentamos as instalações necessárias e a estrutura básica do documento R Markdown e também as formas de inserção de código, configurações e interações sejam lidos antes, além, é claro, dos artigos anteriores a estes, no quais apresentamos a sintaxe básica Markdown e o Pandoc.

R e RStudio

R é uma linguagem de programação de alto nível, interpretada, de script, de tipagem dinâmica forte, multiparadigma (com ênfase em programação funcional) voltada à manipulação, análise e visualização de dados.

Neste artigo vamos abordar a utilização do R notebook no software RStudio que, conforme já tratamos é um Ambiente de Desenvolvimento Integrado - IDE criado para a linguagem R, mas que em suas versões atuais também trabalha com outras linguagens.

É relevante mencionar que, em que pese o software RStudio forneça um conjunto de ferramentas integradas para a criação de R notebooks, o formato de arquivo notebook em si é separado do RStudio, e funciona a partir de várias funções fornecidas pelo pacote rmarkdown, de modo que seria possível ler e gravar R notebooks fora do RStudio.

Para utilizar um R notebook é necessário, evidentemente, ter instalado o R e os mesmos pacotes e dependências necessárias para o R Markdown, notadamente o Knitr e o rmarkdown.

Na primeira parte do artigo sobre R Markdown já tratamos das instalações necessárias e como fazê-las.

Funcionamento do R notebook

Objetivamente, um documento R notebook é um arquivo R Markdown cujo parametro de output em seu cabeçalho de metadados YAML possua o valor html_notebook, que gera como formato de documento de saída um arquivo em extensão .nb.html, que é um tipo de documento HTML cujas características discutiremos mais adiante.

Como vimos no artigo sobre R Markdown um documento R Markdown permite o estabelecimento de diferentes formatos de saída (output), que são o formato para o qual o arquivo R Markdown será convertido quando clicarmos no botão Knit na interface do editor R Markdown do Rstudio ou utilizamos o atalho de teclado ctrl+shift+k. Diferentes valores de output em um arquivo R Markdown “normal” não alteram o comportamento do arquivo .Rmd enquanto o estamos produzindo, apenas definem o formato de saída após a renderização.

Quando estabelecemos o output html_notebook, entretanto, o comportamento do arquivo R Markdown é alterado ligeiramente (mesmo antes da “conversão”), e é esta ligeira alteração de comportamento que confere ao documento as características de um R notebook (além do arquivo de saída .nb.html que é produzido).

Como criar um R notebook

A forma mais simples e direta de criar um documento R notebook no RStudio é muito similar à forma de criar um arquivo R Markdown.

Na barra de ferramentas da interface do RStudio, deve-se clicar no primeiro botão à esquerda, “novo arquivo / new file” (1) e então, no menu que se abre, clicar em “R notebook” (2), conforme Figura 1 a seguir.

rstudio-01

Interface do RStudio - criar R notebook

Será criado, então, um novo painel na porção superior esquerda da interface do RStudio, como podemos ver na Figura 2.

Este novo bloco é um editor de código que contém nosso documento R notebook.

Na primeira vez que for criado um arquivo R notebook (ou R Markdown), o próprio RStudio irá oferecer a instalação de alguns pacotes adicionais necessários, basta aceitar e aguardar a instalação automática.

rstudio-02

Interface do RStudio - R notebook criado

O documento recém criado possui um cabeçalho YAML com dois parâmetros de metadados: o título (que é apenas “R Notebook”, e evidentemente pode ser modificado) e o formato do documento de saída output, com o valor html_notebook que, conforme já dissemos, é o que faz com que este seja um documento R notebook.

Assim como ocorre com um arquivo R Markdown “normal”, o documento também possui, após o cabeçalho YAML, uma espécie de template exemplificativo, contendo alguns trechos de texto em Markdown e código R, que podem ser apagados ou alterados livremente.

É necessário salvar o arquivo R notebook e dar um nome a ele. Para salvar o arquivo basta clicar no ícone em forma de disquete (1) que fica na barra de ferramentas do próprio bloco do editor do R notebook (não confundir com a barra de ferramentas do RStudio em si, que fica logo acima e também tem um outro botão de salvar idêntico), conforme Figura 3.

rstudio-03

Interface do RStudio - salvar R notebook

Uma primeira diferença que pode ser notada no editor do R notebook em relação ao editor do R Markdown é que, em sua barra de ferramentas, no mesmo local onde existe um botão “Knit” no R Markdown há um botão “Preview” (1) no R notebook, conforme Figura 4.

Outra coisa que também pode ser observada, após salvar o documento R notebook, é que foi criado, em conjunto com o arquivo .Rmd um arquivo .nb.html (2), com o mesmo nome, também conforme Figura 4. O arquivo .nb.html pode ser visto no painel Files no bloco inferior esquerdo da interface do RStudio.

rstudio-04

Interface do RStudio - R notebook salvo

Ainda a respeito do botão “Preview”, se clicarmos na seta à sua direta, no menu que se abre, podemos observar que as opções de “Knit” permanecem lá, iguais às opções que existem sob o menu do botão “Knit” em um arquivo R Markdown, com o acréscimo da opção “Preview notebook”, conforme Figura 5.

rstudio-05

Interface do RStudio - R notebook - opções “preview” e “knit”

Vamos tratar a respeito deste “Preview” e do arquivo .nb.html mais adiante. Antes vamos ver outra forma de criar um R notebook e também de transformá-lo em R Markdown e vice-versa.

Transformar R notebook em R Markdown

Como já dissemos, o que determina que um documento R notebook se comporte como R notebook é o valor html_notebook em seu parâmetro output. Neste sentido, se simplesmente editarmos nosso cabeçalho YAML e substituirmos o valor html_notebook por outro formato de saída suportado pelo R Markdown, pdf_document por exemplo, e salvarmos o arquivo, então o documento se “transforma” em um R Markdown. Conforme Figura 6

rstudio-06

Interface do RStudio - R notebook transformado em R Markdown

Como podemos observar na Figura 5 o botão “Preview” desapareceu e foi substituído pelo botão “Knit” (1), demonstrando tratar-se de um arquivo R Markdown agora.

Transformar R Markdown em R notebook

Como já pode ser deduzido a esta altura, o processo para transformar um arquivo R Markdown em R notebook é precisamente o mesmo, substituir o valor do parametro output de qualquer outro formato para html_notebook, conforme Figura 7.

rstudio-07

Interface do RStudio - R Markdown transformado em R notebook novamente

Como podemos ver na Figura 7, nosso exemplo agora é - novamente - um arquivo R notebook (o botão “preview” demonstra isso).

R notebook com múltiplos formatos de saída

É possível ter multiplos valores para o parâmetro output, de modo a produzir diferentes formatos de saída a partir de um mesmo arquivo R Markdown/notebook. Para que o arquivo se comporte como um R notebook basta que o primeiro valor do parâmetro output seja html_notebook, conforme o seguinte exemplo:

---
title: "R Notebook"
output:
  html_notebook: default
  odt_document: default
  md_document: default
  powerpoint_presentation: default
---

O cabeçalho YAML acima manterá o documento como um R notebook, mas permitirá produzir documentos de saída no formato .odt (OpenDocument), .md (Markdown) e .pptx (apresentação Power Point), além do arquivo .nb.html, conforme Figura 8.

rstudio-08

Interface do RStudio - R notebook com múltiplos formatos de saída

Quaisquer formatos suportados pelo R Markdown (pelo Knitr, mais especificamente) podem ser estipulados, basta que o primeiro seja html_notebook e o documento se comportará como um R notebook.

Se clicarmos em “Preview” teremos um preview apenas do arquivo .nb.html (é para isso que este botão serve), mas se clicarmos na seta ao lado do botão “Preview” podemos observar que temos a opção de dar “Knit” para cada um dos formatos especificados no cabeçalho YAML, conforme Figura 9.

rstudio-09

Interface do RStudio - R notebook com múltiplos formatos de saída

Caso o objetivo seja renderizar simultaneamente todos os formatos de saída especificados no cabeçalho YAML basta chamar a função rmarkdown::render() (a mesma função que é chamada quando clicamos no botão “Knit” ou utilizamos o atalho ctrl+shift+k em um arquivo R Markdown) manualmente, digitando no console, e acrescentando o parâmetro output_format="all", da seguinte forma:

rmarkdown::render("inteligencia_urbana.Rmd", output_format="all")

É relevante mencionar que em um arquivo R notebook, o atalho de teclado ctrl+shift+k substitui a função do botão “Preview” e não do botão “Knit”, mesmo que existam outros valores de output estabelecidos. De modo quando se quiser renderizar o arquivo em quaisquer dos formatos de saída deve-se utilizar na opção “Knit” específica no menu que se abre a partir da seta ao lado do botão “Preview” (conforme Figura 9) ou chamar a função rmarkdown::render() “manualmente” no console.

Outputs inline

O comportamento padrão de um arquivo R notebook é mostrar o output de um chunk de código (um tabela ou gráfico, por exemplo) logo na sequência do chunk, dentro do próprio arquivo .Rmd ainda não renderizado, conforme Figura 10, este comportamento é chamado de “notebook mode”.

rstudio-10

Interface do RStudio - R notebook com outputs dos chunks inline

O comportamento “tradicional” e adotado como padrão pelas versões anteriores do R Studio para documentos R Markdown consistia em exibir os outputs de chunks executados apenas no painel específico do RStudio ou no console, inserindo o output na sequencia do bloco de código apenas no documento de saída renderizado, como na Figura 11.

rstudio-11

Interface do RStudio - R Markdown com outputs dos chunks no console e painel Plots

Nas versões mais recentes do RStudio, por padrão, é habilita a saída inline (o “modo Notebook”) em todos os documentos R Markdown, no sentido de se interagir com qualquer documento R Markdown como se fosse um notebook.

Todavia, se preferir usar o “método tradicional” de interação no console, é possível desabilitar o “modo notebook” clicando no botão em forma de engrenagem na barra de ferramentas do editor e, no menu que se abre, escolher a opção Chunk Output in Console. Neste mesmo menu também é possível alternar entre visualizar o documento de saída no painel de visualização ou em uma janela. Conforme Figura 12.

rstudio-12

Interface do RStudio - opções do documento atual

É relevante mencionar tanto o comportamento padrão do documento R notebook pode ser alterado para o “método tradicional” de interação com o console, quanto o comportamento padrão de um arquivo R Markdown pode ser definido ou mantido como “modo notebook”.

Execução do código dos chunks

Para executar o código dos chunks de um documento R notebook existem as mesmas opções de botões e atalhos em relação a um documento R Markdown “normal”, conforme já apresentamos na segunda parte do artigo sobre R Markdown.

Na parte superior direita de cada chunk existem três botões, o botão mais à direita, em forma de seta verde, chama-se “Run current chunk” e serve para executar o chunk atual, enquanto o botão logo à esquerda deste - “Run all chunks above” - serve para executar todos os chunks do documento até o chunk atual.

Também existe um botão “Run” na barra de ferramentas do editor R notebook, que possui as mesmas opções de execução de lotes de chunks que o mesmo botão quando em um arquivo R Markdown.

Uma diferença de comportamento no “modo notebook” de execução é que, ao executar chunks em um documento R Markdown todo o código é enviado ao console de uma vez, ao passo que em um R notebook apenas uma linha de cada vez é enviada, o que permite que a execução pare se uma linha gerar algum erro. Isso trás o aspecto de interatividade característico da “interface de notebook”.

Na execução de um chunk de código no modo notebook, um indicador de progresso aparecerá à esquerda de cada linha para mostrar o andamento da execução. As linhas de código enviadas para o R são marcadas em verde escuro e as linhas que ainda não foram enviadas para o R são marcadas em verde claro. Se pelo menos um chunk seguinte estiver aguardando para ser executado, será mostrado um medidor de progresso na barra de status do editor, na parte inferior do painel. É possível clicar neste medidor a qualquer momento para pular para a parte atualmente em execução ou clicar no quadrado vermelho à sua direita para interromper a execução. A Figura 13 mostra estes indicadores de progresso.

rstudio-13

Interface do RStudio - indicadores de progresso da execução do código dos chunks

Se ocorrer um erro durante a execução de alguma parte do código de algum chunk, as linhas restantes do chunk onde o erro ocorreu, bem como todos os demais chunks não serão executados, a tela do editor irá rolar até o erro e o indicador de progresso à esquerda da linha que causou o erro ficará vermelho. Podemos observar este comportamento na Figura 14, onde também podemos observar que a mensagem de erro é mostrada tanto no console quanto abaixo do chunk no próprio documento, onde também seria exibido o eventual output, motivo pelo qual em geral não é necessário manter o console “aberto” durante a produção no “modo notebook”.

rstudio-14

Interface do RStudio - erro durante a execução do código dos chunks

Conforme já mencionamos, nas versões mais recentes do software RStudio, este “modo notebook” não é uma exclusividade dos documentos R notebook, mas também será o comportamento padrão de um arquivo R Markdown que tenha a opção “Chunk Output Inline” marcada.

Notebook HTML (.nb.html)

Enquanto a construção de um documento .Rmd em “modo notebook” não é mais uma característica padrão exclusiva de um R notebook, uma vez que este tipo de comportamento foi estendido também aos arquivos R Markdown, uma característica fundamental permanece diferenciando um documento R notebook: o seu documento de saída (que não é exatamente “apenas” um documento de “saída”) com extensão .nb.html, o notebook HTML.

Quando um documento R notebook é salvo, um arquivo com extensão .nb.html é criado junto com ele. Este arquivo é um arquivo HTML “autocontido” que contém todos os chunks de código (e de forma que possam ser recolhidos ou expandidos) e seus respectivos outputs.

É possível visualizar este notebook HTML (.nb.html) diretamente em qualquer navegador, além de compartilhá-lo com outras pessoas, que também podem visualizá-lo em qualquer navegador sem necessidade de ter instalado nenhum software específico.

O documento notebook HTML é uma variação do formato de saída HTML, o resultado renderizado é muito semelhante, mas o propósito é diferente. Um documento HTML se concentra na comunicação com tomadores de decisão ou público em geral, enquanto o notebook HTML se concentra na colaboração com outros cientistas de dados. Esses diferentes propósitos levam ao uso do documento HTML e do notebook HTML de maneiras diferentes. Ambos conterão a saída totalmente renderizada, mas o notebook HTML (.nb.html) também contém o “código-fonte” completo. Isso significa que é possível usar o notebook HTML gerado pelo R notebook de duas maneiras principais:

  1. Visualizá-lo em um navegador Web
    A saída renderizada, ao contrário formato de saída HTML, sempre inclui uma cópia incorporada do “código-fonte” que o gerou;

  2. Editá-lo no RStudio
    Quando se abre um arquivo .nb.html, o RStudio “recria” automaticamente o arquivo .Rmd que o gerou, e extrai os outputs dos chunks do arquivo .nb.html e os coloca nos locais apropriados no editor.

Durante a produção do documento R notebook, o notebook HTML pode ser pré-visualizado clicando-se no botão “Preview” na barra de ferramentas do editor. Conforme a configuração escolhida esta pré-visualização pode aparecer no painel “Viewer” no bloco inferior direito da interface do RStudio ou em uma janela que faz as vezes de um navegador Web.

Diferente de um arquivo R Markdown, no qual seu documento de saída precisa ser necessariamente renderizado (a partir do botão “Knit” ou do atalho de teclado ctrl+shift+k) para que seja visualizado, a saída .nb.html é apenas pré-visualizada, o que significa que o processo será muito mais rápido (praticamente instantâneo) e portanto muito mais dinâmico e interativo (o que é justamente a filosia de um notebook interface para literate programming) mas também significa que os chunks não serão executados na geração deste “preview”.

Ao se clicar em “Preview” será utilizada a última versão executada das saídas e valores de cada chunk que estiver armazenada na memória do RStudio. Se em algum chunk o valor de algum objeto ou variável tiver sido modificado mas o chunk não tiver sido executado ainda após a mudança, o “preview” exibirá a versão anterior armazenada na memória. Para gerar um notebook HTML atualizado basta executar os chunks e então salvar o arquivo.

Para gerar outros formatos de saída é necessário necessário utilizar a função render() através das opções de “Knit” específicas disponíveis no menu que se abre ao se clicar na seta ao lado do botão “Preview”, ou chamando a função manualmente no console, conforme já mencionamos anteriormente.

Vantagens do R notebook

Esta característica autônoma e “autocontida” do documento .nb.html é um grande diferencial não apenas do R notebook em relação do R Markdown “normal”, mas também em relação a outros “notebook interfaces” disponíveis por aí.

Uma primeira diferença do R notebook em relação a outros “notebooks” conhecidos é a separação entre o arquivo com código-fonte .Rmd e o arquivo de saída .nb.html. O arquivo .Rmd, sendo efetivamente um arquivo de texto simples, é muito amigável com versionamento de código (diferente do que acontece com os notebooks .ipynb, por exemplo, que funcionam sobre uma base .json, vamos tratar deles no futuro).

A “estrutura” do arquivo .nb.html, entretanto, imagino que seja o principal diferencial, e que trás as principais vantagens. É um arquivo único que carrega tudo o que se precisa para visualizar, interagir, contribuir, compartilhar, editar, etc., sem nenhum requisito específico e, simultaneamente, sem nenhuma limitação de funcionalidade.

O arquivo .nb.html é um arquivo HTML, o que significa que tanto pode ser publicado na internet quanto pode ser enviado para qualquer pessoa, por email por exemplo, e então ser aberto pelo próprio navegador padrão do computador, sem a necessidade de possuir nenhum software especial instalado, e com acesso a todo o conteúdo renderizado do documento, texto, código e outputs, com a possibilidade interativa de recolher ou expandir os blocos de código. Na parte superior direita de cada bloco de código há um botão “hide”, que, se clicado, recolhe o bloco e transforma-se em um botão “code”, que, se clicado, expande o bloco e permite a visualização do trecho de código. Conforme Figura 15 e Figura 16.

rstudio-15

Notebook HTML - blocos de código recolhidos

rstudio-16

Notebook HTML - blocos de código expandidos

Mais que isso, uma vez que o arquivo .nb.html contém o arquivo .Rmd que o gerou, é possível extraí-lo e trabalhar com ele. Além de ser possível abrir o arquivo .nb.html no RStudio (o que fará com que o RStudio “recrie” o arquivo .Rmd), conforme já mencionado, também é possível fazer download do .Rmd a partir do próprio .nb.html a partir de um botão “Code” no canto superior direito do documento e que, ao ser clicado, exibe um menu que permite exibir ou recolher todos os blocos de código e também fazer o download do .Rmd, conforme Figura 17.

rstudio-17

Notebook HTML - download do arquivo .Rmd

Estas propriedades fazem do arquivo HTML notebook algo extremamente versátil, visto que permite a visualização e interação com seu conteúdo por alguém que não tenha nenhum software específico instalado ao mesmo tempo que não limita nenhuma forma de acessar o conteúdo, permitindo mesmo a recriação completa de seu código fonte para qualquer tipo de edição ou modificação dentro ou mesmo fora do RStudio, graças à opção de download do .Rmd. E tudo isso em um único e simples arquivo.

A seguir disponibilizo para download o documento que foi utilizado como pequeno exemplo prático no artigo sobre R Markdown, transformado em R notebook (meramente substituindo o valor do output para html_notebook), a partir do qual se gerou este arquivo .nb.html.

Conclusão

Neste artigo apresentamos o R notebook, que é uma espécie de modo de execução especial de documentos R Markdown, com características e funcionalidades sutilmente diferentes que lhe conferem casos de uso próprios e se configura como uma implementação de literate programming em uma interface de computational notebook mais conceitualmente alinhada com o significado destes termos.

Além do blog, a plataforma Inteligência Urbana disponibiliza páginas com referências para livros, cursos e leis e normas relacionadas aos temas que tratamos aqui. Caso você tenha interesse pode conferir nossos serviços oferecidos e entrar em contato quando quiser. Se quiser ser alertado da publicação de material novo pode assinar a nossa newsletter, e muito obrigado pela atenção até aqui!

Principais referências