Jupyter e R Markdown: Notebooks com R
Ao trabalhar em problemas de ciência de dados, talvez você queira configurar um ambiente interativo para trabalhar e compartilhar seu código para um projeto com outras pessoas. Você pode configurar isso facilmente com um notebook.
Em outros casos, você só vai querer se comunicar sobre o fluxo de trabalho e os resultados que coletou para a análise do seu problema de ciência de dados. Para obter um relatório transparente e reproduzível, um caderno também pode ser útil.
É isso mesmo: os notebooks são perfeitos para situações em que você deseja combinar texto simples com elementos de rich text, como gráficos, cálculos etc.
Este tutorial abordará os seguintes tópicos:
R e o Jupyter Notebook
Ao contrário do que você pode pensar, o Jupyter não o limita a trabalhar apenas com Python: o aplicativo de notebook é independente de linguagem, o que significa que você também pode trabalhar com outras linguagens.
Há duas maneiras gerais de começar a usar o R com o Jupyter: usando um kernel ou configurando um ambiente R que tenha todas as ferramentas essenciais para começar a fazer ciência de dados.
Executando o R no Jupyter com o kernel do R
Conforme descrito acima, a primeira maneira de executar o R é usando um kernel. Se você quiser ter uma lista completa de todos os kernels disponíveis no Jupyter, acesse aqui.
Para trabalhar com o R, você precisará carregar o IRKernel e ativá-lo para começar a trabalhar com o R no ambiente do notebook.
Primeiro, você precisará instalar alguns pacotes. Certifique-se de não fazer isso no console do RStudio, mas em um terminal R normal, caso contrário, você receberá um erro como este:
Error in IRkernel::installspec() :
Jupyter or IPython 3.0 has to be installed but could neither run “jupyter” nor “ipython”, “ipython2” or “ipython3”.
(Note that “ipython2” is just IPython for Python 2, but still may be IPython 3.0)
$ R
> install.packages(c('repr', 'IRdisplay', 'evaluate', 'crayon', 'pbdZMQ', 'devtools', 'uuid', 'digest'))
Esse comando solicitará que você digite um número para selecionar um espelho do CRAN para instalar os pacotes necessários. Digite um número e a instalação continuará.
> devtools::install_github('IRkernel/IRkernel')
Em seguida, você ainda precisa tornar o kernel do R visível para o Jupyter:
# Install IRKernel for the current user
> IRkernel::installspec()
# Or install IRKernel system-wide
> IRkernel::installspec(user = FALSE)
Agora, abra o aplicativo do notebook com jupyter notebook
. Você verá o R aparecer na lista de kernels quando criar um novo notebook.
Uso de um ambiente R Essentials no Jupyter
A segunda opção para trabalhar rapidamente com o R é instalar os elementos essenciais do R em seu ambiente atual:
conda install -c r r-essentials
Esses "essenciais" incluem os pacotes dplyr, shiny, ggplot2, tidyr, caret e nnet. Se não quiser instalar o essencial em seu ambiente atual, você pode usar o seguinte comando para criar um novo ambiente apenas para o essencial do R:
conda create -n my-r-env -c r r-essentials
Agora, abra o aplicativo notebook para começar a trabalhar com o R.
Talvez você se pergunte o que precisa fazer se quiser instalar pacotes adicionais para elaborar seu projeto de ciência de dados. Afinal, esses pacotes podem ser suficientes para você começar, mas talvez você precise de outras ferramentas.
Bem, você pode criar um pacote Conda R executando, por exemplo:
conda skeleton cran ldavis conda build r-ldavis/
Ou você pode instalar o pacote de dentro do R via install.packages()
ou devtools::install_github
(para instalar pacotes do GitHub). Você só precisa se certificar de adicionar o novo pacote à biblioteca R correta usada pelo Jupyter:
install.packages("ldavis", "/home/user/anaconda3/lib/R/library")
Se quiser saber mais sobre kernels ou sobre como executar o R em um ambiente Docker, consulte esta página.
Adicionando um pouco de magia R ao Jupyter
Uma grande vantagem de trabalhar com notebooks é que eles proporcionam um ambiente interativo. Essa interatividade vem principalmente dos chamados "comandos mágicos".
Esses comandos permitem que você mude de Python para instruções de linha de comando ou escreva código em outra linguagem, como R, Julia, Scala, ...
Para mudar de Python para R, primeiro você precisa baixar o seguinte pacote:
%load_ext rpy2.ipython
Depois disso, você pode começar a usar o R ou mudar facilmente do Python para o R em sua análise de dados com o comando mágico %R
.
Vamos demonstrar como a mágica do R funciona com um pequeno exemplo:
# Hide warnings if there are any
import warnings
warnings.filterwarnings('ignore')
# Load in the r magic
%load_ext rpy2.ipython
# We need ggplot2
%R require(ggplot2)
# Load in the pandas library
import pandas as pd
# Make a pandas DataFrame
df = pd.DataFrame({'Alphabet': ['a', 'b', 'c', 'd','e', 'f', 'g', 'h','i'],
'A': [4, 3, 5, 2, 1, 7, 7, 5, 9],
'B': [0, 4, 3, 6, 7, 10,11, 9, 13],
'C': [1, 2, 3, 1, 2, 3, 1, 2, 3]})
# Take the name of input variable df and assign it to an R variable of the same name
%%R -i df
# Plot the DataFrame df
ggplot(data=df) + geom_point(aes(x=A, y=B, color=C))
Se quiser obter mais detalhes sobre o Jupyter, sobre como configurar um notebook, onde fazer download do aplicativo, como executar o aplicativo do notebook (via Docker, instalação do pip ou com a distribuição do Anaconda) ou outros detalhes, consulte nosso Guia definitivo.
O Caderno R
Até recentemente, o Jupyter parece ter sido uma solução popular para os usuários de R, ao lado de notebooks como o Apache Zeppelin ou o Beaker.
Além disso, outras alternativas para relatar resultados de análises de dados, como R Markdown, Knitr ou Sweave, têm sido muito populares na comunidade R.
No entanto, isso pode mudar com o recente lançamento do R ou R Markdown Notebook pelo RStudio.
Você vê: o contexto do R Markdown Notebook é complexo, e vale a pena examinar a história da pesquisa reproduzível em R para entender o que impulsionou a criação e o desenvolvimento desse notebook. Por fim, você também perceberá que esse notebook é diferente dos outros.
R e a história da pesquisa reproduzível
Em sua palestra, J.J. Allaire confirma que os esforços do próprio R para a pesquisa reproduzível, os esforços do Emacs para combinar código de texto e entrada, os projetos Pandoc, Markdown e knitr e os notebooks computacionais vêm evoluindo em paralelo e influenciando uns aos outros há muitos anos. Ele confirma que todos esses fatores acabaram levando à criação e ao desenvolvimento de notebooks para R.
Em primeiro lugar, os notebooks computacionais têm uma história e tanto: desde o final dos anos 80, quando o front-end do Mathematica foi lançado, houve muitos avanços. Em 2001, Fernando Pérez começou a desenvolver o IPython, mas somente em 2011 a equipe lançou a versão 0.12 do IPython. O projeto SageMath começou em 2004. Depois disso, houve muitos cadernos. Os mais notáveis para a comunidade de ciência de dados são o Beaker (2013), o Jupyter (2014) e o Apache Zeppelin (2015).
Além disso, há também as linguagens de marcação e os editores de texto que influenciaram a criação do aplicativo de notebook do RStudio, a saber, Emacs, Markdown e Pandoc. Org-mode foi lançado em 2003. É um modo de edição e organização para anotações, planejamento e criação no editor de texto de software livre Emacs. Seis anos depois, o Emacs org-R estava lá para oferecer suporte aos usuários do R. O Markdown, por outro lado, foi lançado em 2004 como uma linguagem de marcação que permite formatar o texto simples de modo que ele possa ser convertido em HTML ou em outros formatos. Mais alguns anos depois, o Pandoc foi lançado. É uma ferramenta de escrita e uma base para fluxos de trabalho de publicação.
Por fim, os esforços da comunidade do R para garantir que a pesquisa possa ser reproduzida e transparente também contribuíram para o surgimento de um notebook para o R. 2002, o Sweave foi introduzido em 2002 para permitir a incorporação de código R em documentos LaTeX para gerar arquivos PDF. Esses arquivos PDF combinavam a narrativa e a análise, os gráficos, o código e os resultados dos cálculos. Dez anos depois, o knitr foi desenvolvido para resolver problemas antigos no Sweave e para combinar recursos presentes em outros pacotes complementares em um único pacote. É um mecanismo transparente para a geração dinâmica de relatórios em R. O Knitr permite qualquer linguagem de entrada e qualquer linguagem de marcação de saída.
Também em 2012, o R Markdown foi criado como uma variante do Markdown que pode incorporar blocos de código R e que pode ser usado com o knitr para criar relatórios reproduzíveis baseados na Web. A grande vantagem era e ainda é o fato de não ser mais necessário usar o LaTex, que tem uma curva de aprendizado para ser aprendido e usado. A sintaxe do R Markdown é muito semelhante à sintaxe regular do Markdown, mas tem alguns ajustes, pois você pode incluir, por exemplo, equações LaTex.
R Markdown versus cadernos de anotações computacionais
O R Markdown é provavelmente uma das opções mais populares na comunidade R para relatar análises de dados. Não é nenhuma surpresa que ele ainda seja um componente essencial do R Markdown Notebook.
E há algumas coisas que o R Markdown e os notebooks compartilham, como o fornecimento de um fluxo de trabalho reproduzível, a combinação de código, saída e texto em um único documento, o suporte a widgets interativos e a saída para vários formatos. No entanto, eles diferem em suas ênfases: O R Markdown concentra-se na execução em lote reproduzível, na representação de texto simples, no controle de versão, na saída de produção e oferece o mesmo editor e as mesmas ferramentas que você usa para scripts R.
Por outro lado, os notebooks computacionais tradicionais se concentram na saída em linha com o código, no armazenamento em cache da saída em todas as sessões, no compartilhamento de código e na saída em um único arquivo. Os notebooks enfatizam um modelo de execução interativo. Eles não usam uma representação de texto simples, mas uma representação de dados estruturados, como JSON.
Isso tudo explica o propósito do aplicativo de notebook do RStudio: ele combina todas as vantagens do R Markdown com as coisas boas que os notebooks computacionais têm a oferecer.
É por isso que o R Markdown é um componente central do R Markdown Notebook: O RStudio define seu notebook como "um documento R Markdown com partes que podem ser executadas de forma independente e interativa, com a saída visível imediatamente abaixo da entrada".
Como trabalhar com notebooks do R
Se você já trabalhou com o Jupyter ou qualquer outro notebook de computação, verá que o fluxo de trabalho é muito semelhante. Uma coisa que pode parecer muito diferente é o fato de que agora você não está mais trabalhando com células de código por padrão: em vez disso, está trabalhando com um tipo de editor de texto no qual você indica seus blocos de código com o R Markdown.
Como instalar e usar o R Markdown Notebook
O primeiro requisito para usar o notebook é que você tenha a versão mais recente do RStudio disponível em seu PC. Como os notebooks são um novo recurso do RStudio, eles só estão disponíveis na versão 1.0 ou superior do RStudio. Portanto, é importante verificar se você tem a versão correta instalada.
Se você não tiver a versão 1.0 ou superior do RStudio, poderá fazer o download da versão mais recente aqui.
Em seguida, para criar um novo notebook, vá para a guia File (Arquivo), selecione "New File" (Novo arquivo) e você verá a opção de criar um novo R Markdown Notebook. Se o RStudio solicitar que você atualize alguns pacotes, basta aceitar a oferta e, eventualmente, um novo arquivo aparecerá.
Dica: verifique novamente se está trabalhando com um notebook olhando para a parte superior do documento. O resultado deve ser html_notebook.
Você verá que o texto padrão que aparece no documento está em R Markdown. O R Markdown deve ser bastante familiar para você, mas, se ainda não estiver muito familiarizado, poderá conferir nosso curso Reporting With R Markdown ou consultar o material fornecido pelo RStudio.
Observe que você sempre pode usar o ícone de engrenagem para ajustar o espaço de trabalho do notebook: você tem a opção de expandir, recolher e remover a saída do seu código, alterar as opções de visualização e modificar as opções de saída.
Essa última opção pode ser útil se você quiser alterar o realce da sintaxe, aplicar outro tema, ajustar a largura e a altura padrão das figuras que aparecem na saída, etc.
A partir daí, você pode começar a inserir trechos de código e texto!
Você pode adicionar blocos de código de duas maneiras: por meio do atalho de teclado Ctrl + Alt + I ou Cmd + Option + I, ou com o botão de inserção que se encontra na barra de ferramentas.
O melhor de trabalhar com esses notebooks R Markdown é o fato de que você pode acompanhar a execução dos blocos de código, graças à pequena barra verde que aparece à esquerda quando você está executando grandes blocos de código ou vários blocos de código ao mesmo tempo. Além disso, observe que há uma barra de progresso na parte inferior.
Você pode ver a barra de progresso verde aparecendo no gif abaixo:
Falando sobre a execução de código: há várias maneiras de executar seus blocos de código R.
Você pode executar um trecho de código ou executar o próximo trecho, executar todos os trechos de código abaixo e acima; mas também pode optar por reiniciar o R e executar todos os trechos ou reiniciar e limpar a saída.
Observe que, ao executar o código do notebook, você também verá a saída exibida no console! Essa pode ser uma diferença bastante grande para quem costuma trabalhar com outros notebooks de computação, como o Jupyter.
Se houver algum erro enquanto os blocos de código do notebook estiverem sendo executados, a execução será interrompida e aparecerá uma barra vermelha ao lado do bloco de código que produziu o erro.
Você pode suprimir a interrupção da execução adicionando errors = TRUE
nas opções de bloco, da seguinte forma:
```{r, error=TRUE}
iris <- read.csv(url("http://mlr.cs.umass.edu/ml/machine-leaning-databases"), header = FALSE)
names(iris) <- c("Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width", "Species")
```
Observe que o erro ainda aparecerá, mas a execução do código do notebook não será interrompida!
Como usar a magia do R Markdown Notebook
Assim como no Jupyter, você também pode trabalhar interativamente com seus notebooks R Markdown. Ele funciona de forma um pouco diferente do Jupyter, pois não há comandos mágicos reais; para trabalhar com outras linguagens, você precisa adicionar blocos separados de Bash, Stan, Python, SQL ou Rcpp ao notebook.
Essas opções podem parecer bastante limitadas para você, mas isso é compensado pela facilidade com que você pode adicionar facilmente esses tipos de blocos de código com o botão de inserção da barra de ferramentas.
Também é fácil trabalhar com esses blocos de código: você pode ver um exemplo de blocos de SQL neste documento, publicado por J.J Allaire. Para comandos do Bash, basta digitar o comando. Não há necessidade de caracteres extras, como '!
', para indicar que você está trabalhando no Bash, como faria ao trabalhar com o Jupyter.
Como gerar seus blocos de anotações Markdown do R
Antes de renderizar a versão final de um notebook, talvez você queira visualizar o que está fazendo. Há um recurso útil que permite fazer isso: você o encontrará em sua barra de ferramentas.
Clique no botão "preview" (visualizar) e a versão provisória do seu documento aparecerá no lado direito, na guia "Viewer" (visualizador).
Ao adicionar algumas linhas à primeira seção na parte superior do notebook, é possível ajustar as opções de saída, como a seguir:
---
title: "Notebook with KNN Example"
output:
pdf_document:
highlight: tango
toc: yes
html_notebook:
toc: yes
---
Para ver onde é possível obter essas distribuições, basta tentar fazer o knit, e a saída do console fornecerá os sites onde você pode baixar os pacotes necessários.
Observe que essa é apenas uma das muitas opções que você tem para exportar um notebook: há também a possibilidade de renderizar documentos do GitHub, documentos do Word, apresentações do Beamer etc. Essas são as opções de saída que você já tinha com os arquivos regulares do R Markdown. Você pode encontrar mais informações aqui.
Dicas e truques para trabalhar com o R Notebook
Além das práticas gerais de codificação que você deve ter em mente, como documentar seu código e aplicar um esquema de nomenclatura consistente, agrupamento de código e comprimento do nome, você também pode usar as dicas a seguir para tornar um notebook incrível para ser usado e lido por outras pessoas:
- Assim como nos notebooks computacionais, pode ser útil dividir grandes blocos de código ou blocos de código que geram mais de uma saída em vários blocos. Dessa forma, você melhorará a experiência geral do usuário e aumentará a transparência de um notebook.
- Use os atalhos de teclado para acelerar seu trabalho. Você encontrará a maioria delas na barra de ferramentas, ao lado dos comandos que deseja executar.
- Use o verificador ortográfico na barra de ferramentas para garantir que o vocabulário do seu relatório esteja correto.
- Aproveite a opção de ocultar seu código se o notebook tiver muito código. Você pode fazer isso por meio de opções de bloco de código ou no arquivo HTML do próprio notebook!
O R Notebook versus o Jupyter Notebook
Além das diferenças entre os notebooks Jupyter e R Markdown que você já leu acima, há mais algumas coisas.
Vamos comparar o Jupyter com o R Markdown Notebook!
Há quatro aspectos que você achará interessante considerar: compartilhamento de notebook, execução de código, controle de versão e gerenciamento de projetos.
Compartilhamento de notebooks
O código-fonte de um notebook R Markdown é um arquivo .Rmd
. Mas quando você salva um bloco de notas, um arquivo .nb.html
é criado junto com ele. Esse arquivo HTML é um arquivo associado que inclui uma cópia do código-fonte do R Markdown e a saída gerada.
Isso significa que você não precisa de um visualizador especial para ver o arquivo, embora possa precisar dele para visualizar notebooks criados com o aplicativo Jupyter, que são documentos JSON simples, ou outros notebooks de computação que têm saídas em formato estruturado. Você pode publicar seu notebook R Markdown em qualquer servidor da Web, no GitHub ou como anexo de e-mail.
Há também APIs para renderizar e analisar notebooks do R Markdown: isso permite que outras ferramentas de front-end criem modos de criação de notebooks para o R Markdown. Ou as APIs podem ser usadas para criar utilitários de conversão de e para diferentes formatos de notebook.
Para compartilhar os notebooks criados no aplicativo Jupyter, você pode exportá-los como apresentações de slides, blogs, painéis etc. Você pode encontrar mais informações neste tutorial. No entanto, há também as opções padrão para gerar scripts Python, arquivos HTML, arquivos Markdown, arquivos PDF ou arquivos de texto reestruturado.
Execução de código
Os R Markdown Notebooks têm opções para executar um trecho de código ou executar o próximo trecho, executar todos os trechos de código abaixo e acima; além dessas opções, você também pode optar por reiniciar o R e executar todos os trechos ou reiniciar e limpar a saída.
Essas opções são interessantes quando se trabalha com o R porque o R Markdown Notebook permite que todas as partes do código do R compartilhem o mesmo ambiente. No entanto, isso pode ser uma grande desvantagem se você estiver trabalhando com partes de código não-R, pois elas não compartilham ambientes.
Em suma, essas opções de execução de código adicionam uma flexibilidade considerável para os usuários que têm tido dificuldades com as opções de execução de código oferecidas pelo Jupyter, mesmo que elas não sejam muito diferentes: no aplicativo Jupyter, você tem a opção de executar uma única célula, executar células e executar todas as células. Você também pode optar por limpar a saída atual ou todas as saídas. O ambiente de código é compartilhado entre as células de código.
Controle de versão
Houve alegações de que o Jupyter atrapalha o controle de versão dos notebooks ou que é difícil usar o git com esses notebooks. As soluções para esse problema são exportar o notebook como um script ou configurar um filtro para corrigir partes dos metadados que não devem ser alteradas quando você faz o commit ou remover a contagem de execuções e a saída.
Os notebooks Markdown do R parecem tornar esse problema um pouco mais fácil de lidar, pois eles têm arquivos HTML associados que salvam a saída do seu código e, como os arquivos do notebook são essencialmente arquivos de texto simples, o controle de versão será muito mais fácil. Você pode optar por colocar o arquivo .Rmd
apenas no GitHub ou em outro sistema de controle de versão, ou também pode incluir o arquivo .nb.html
.
Gerenciamento de projetos
Como o R Markdown Notebook é nativo do kit de desenvolvimento do RStudio, os notebooks se integrarão perfeitamente aos seus projetos R. Além disso, esses notebooks oferecem suporte a outras linguagens, incluindo Python, C e SQL.
Por outro lado, o projeto Jupyter não é nativo de nenhum kit de desenvolvimento: nesse sentido, será necessário algum esforço para integrar esse notebook perfeitamente aos seus projetos. Mas esse notebook ainda oferece suporte a mais linguagens e será um companheiro mais adequado para você se estiver procurando usar Scala, Apache Toree, Julia ou outra linguagem.
Alternativas aos notebooks Jupyter ou R Markdown
Além dos notebooks que você pode usar como ambientes interativos de ciência de dados, que facilitam o compartilhamento do seu código com colegas, pares e amigos, há outras alternativas a serem consideradas.
Porque, às vezes, você não precisa de um notebook, mas de um painel, de uma plataforma de aprendizagem interativa ou de um livro, por exemplo.
Você já leu sobre opções como Sweave e Knitr na segunda seção. Algumas outras opções disponíveis são:
- Embora esta postagem do blog tenha abordado o R Markdown até certo ponto, você deve saber que pode fazer muito mais com ele. Por exemplo, você pode criar painéis com o flexdashboard.
- Ou você pode usar o Bookdown para publicar rapidamente livros em HTML, PDF, ePub e Kindle com o R Markdown.
- O Shiny é uma ferramenta que você também pode usar para criar painéis. Para começar a usar o Shiny, vá para esta página.
- Em um ambiente educacional, o DataCamp Light também pode ser útil para criar tutoriais interativos em seu blog ou site. Se você quiser ver a luz do DataCamp em ação, acesse este tutorial, por exemplo.
tutorial
RStudio Tutorial
tutorial
Tutorial de Markdown no Jupyter Notebook
Olivia Smith
9 min
tutorial
Como usar o Jupyter Notebooks: O guia definitivo

Adam Shafi
25 min
tutorial
Tutorial de introdução ao JupyterLab
tutorial
Tutorial de como executar consultas SQL em Python e R
tutorial