Jupyter Notebook


O que é o Jupyter Notebook?

Jupyter Notebook é uma ferramenta poderosa para o desenvolvimento projetos de ciência de dados de forma interativa que é executada de dentro de seu browser. Além da execução interativa de código ele pode ser usado para a preparação de apresentações dinâmicas onde texto pode ser bem formatado contendo imagens, gráficos interativos e fórmulas matemáticas. O conteúdo das linhas de código e seus outputs (as respostas produzidas pelo código) ficam bem delimitadas.

Ele faz parte do Projeto Jupyter de código aberto e free software. É possível baixar e instalar gratuitamente o Jupyter Notebooks separadamente ou como parte do kit de ferramentas de ciência de dados Anaconda. Com ele se pode usar vários ambientes de execução (kernels ou núcleos) com linguagens de programação como o Python, R, Julia, C++, Scheme, Haskell e Ruby.

O Jupyter Notebook está se tornando uma interface muito popular para a computação na nuvem e muitos dos provedores desse tipo de serviço o adotaram como interface front-end para seus usuários. Entre eles estão o SageMaker Notebooks da Amazon, o Colaboratory do Google e o Azure Notebook da Microsoft. O Colaboratory (também chamado de Colab) é um ambiente gratuito que armazena e roda notebooks no Google Drive.

Os arquivos no Notebook são armazenados no formato JSON com a extensão *.ipynb. Eles podem ser lidos pelo aplicativo instalado (que usa o browser para sua exibição), e exportado para várias formatos, entre eles: html, markdown, pdf, latex e slides Reveal.js. O arquivo consiste de várias células que são exibidas como uma página usual de html. Algumas células são de código e seus resultados, outras de texto, imagens ou outras mídias. Alternativamente eles podem ser lidos e exibidos (de forma não interativa) pelo nbviewer (na web).

Instalação

A forma mais simples de instalação do Jupyter Notebooks consiste em instalar o Anaconda, a distribuição Python mais usada para ciência de dados. Esta instalação inclui as princiais bibliotecas e ferramentas mais populares, como NumPy, Pandas e Matplotlib.

Para obter o Anaconda:

  • Baixe a versão mais recente do Anaconda aqui. Existem instaladores gráficos para Linux, Windows e MacOS.
  • Instale seguindo as instruções na página de download ou contidas no arquivo instalador executável.
  • ou … usuários que conhecem Python e que preferem gerenciar seus pacotes manualmente, pode apenas usar:
    pip3 install jupyter.

Executando e Criando um Notebook

No Windows na MacOS ou Linux um atalho para Jupyter Notebook é criado no menu do sistema. Caso nenhum atalho tenha sido criado você pode criar um ou iniciar usando o console. No Linux se digita jupyter-notebook no console. Uma janela com a seguinte aparência é aberta no browser padrão:

A primeira página exibe o painel de controle do Jupyter (dashboard). Ele dá acesso aos arquivos e subpastas que estão na pasta de inicialização do Jupyter. Esta pasta, no entanto, pode ser alterada. O painel de controle tem uma interface amigável por onde você pode controlar suas pastas e notebooks. Toda a descrição que usamos aqui se refere à aparência default dos notebooks. Essa aparência pode ser alterada modificando-se o arquivo css em /home/nome-usuario/.jupyter/custom/custom.css (no Linux).

O Jupyter Notebook fica aberto no navegador usando uma URL especial, do tipo “http://localhost:8888/tree”. Isso indica que o servidor dessa página esta em sua máquina local.

Você pode criar uma pasta nova para seus projetos clicando em New Folder. Depois pode renomear sua pasta selecionado e clicando em Rename. Clique na pasta para abrí-la e depois em New: Python 3 (notebook). Um notebook vazio e sem nome é criado. Clique nele e em File | Rename e dê um nome apropriado para o seu notebook. Vários notebooks podem ser abertos ao mesmo tempo.

Um notebook aberto apresenta a seguinte interface:

Os menus superiores dão acesso as funcionalidades de gravar arquivo, importar e exportar para diferentes formatos, etc. O item File | Save and Checkpoint (Ctrl-S) permite guardar o estado as sessão no momento de forma a poder ser recuperada mais tarde por meio de File | Revert to Checkpoint. Para fechar uma sessão não basta fechar a aba do navegador pois isso deixaria ativa a tarefa na memória do computador. Para isso você pode usar File | Close and Halt ou Kernel | Shutdown. Também se pode clicar em LOGOUT no canto superior direito.

Ainda na barra de menus você pode clicar em Help | User interface tour para ver alguns pontos relevantes no notebook. Help | Keyboard Shortcuts exibe os atalhos de teclado predefinidos, observando que eles podem ser modificados pelo usuário. O menu de ajuda também contém links diretos para as documentações do Python, IPython, NumPy, SciPy, Matplotlib, SymPy, pandas e markdown. O ícone de teclado abre uma ajuda com os atalhos mais usados.

Notebooks são iniciados com uma célula vazia. Cada célula possui dois modos de uso: modo de edição e modo de comando. Clicando dentro da célula ela fica com borda verde e entra no modo de edição onde se pode inserir texto e códigos. Use a caixa de seleção na caixa de ferramentas do notebook para selecionar entre ‘code’, ‘markdown’ ou ‘Raw NBConvert’. (A opção ‘heading’ está em desuso e é desnecessária). Se ‘code’ está selecionado você pode digitar um comando como, por ex.,

print('Olá galera!')
Olá galera!

Comandos dentro de uma célula de código são executados todos de uma vez. Para isso pressione:
shift-enter: o código é executado e uma nova célula é aberta no mode de edição, ou
ctrl-enter: o código é executado e a mesma célula fica selecionada no modo de comando.

Em ambos os casos o output, se existir, é mostrado abaixo da célula. O botão ▶ Run na barra de ferramentas tem o mesmo efeito que shift-enter.

Os modos de edição e de comando são alternados com o uso de ESC (passa de comando para edição) e enter (de edição para comando).

Quando no modo de comando (a célula fica com a borda azul) os seguintes atalhos ficam habilitados:

Comando Ação
ESC/enter Alterna entre modos de edição / comando
Barra de espaço Rolar tela para baixo
Shift-Barra de espaço Rolar tela para cima
A Inserir célula acima
B Inserir célula abaixo
D, D Apagar células selecionadas
Z Desfazer apagamento
Shift-L Exibir/ocultar numeração das linhas de código
Shift-Tab Exibir docstring de objeto
Y Alterar célula para código
M Alterar célula para markdown
R Alterar célula para raw
H Exibir Help | keyboard shortcuts
Teclas 🔼 ou 🔽 Rolar para cima e para baixo nas células
Shift 🔼 ou 🔽 Selecionar várias células de uma vez.
Shift M Mesclar várias células selecionadas em uma única.
Ctrl Shift – Dividir célula ativa na posição do cursor (no modo de edição).
Shift clique na margem esquerda da célula Selecionar várias células de uma vez.

Um lista completa desses atalhos pode ser vista no menu Help | keyboard shortcuts.

Células no formato de texto

Células podem ser marcadas como texto puro, sem qualquer formatação, no modo Raw NBConvert. Esse texto é exibido como está e não passará por renderização de nenhuma forma nem na exibição dentro do notebook nem na exportação para outros formatos, como o pdf.

Markdown

Markdown é uma linguagem de marcação limitada mas bastante simples de se aprender e usar. Ela tem sintaxe diferente de html mas guarda uma correspondência com suas tags. Você pode encontrar uma descrição mais completa de Markdown na página Marcação de Texto com Markdown.

Além da marcação markdown se pode usar um conjunto restrito de tags html nas caixas de texto. Por exemplo, o código seguinte:

 <div style = "border:1px solid black; padding:10px; color:white; background-color:red;" >
parei aqui ↷ 
</div>

produzirá a barra vermelha abaixo, útil para marcar um ponto específico dentro de um notebook.

parei aqui ↷

O Jupyter Notebook pode renderizar Latex (para isso usa a biblioteca javascript Mathjax) em suas células de Markdown.


A identidade de Euler é \(e^{i \pi} + 1 = 0\).
A definição da derivada de primeira ordem é:
$$
f'(x) = \lim\limits_{h \rightarrow 0} \frac{f(x+h) – f(x)}{h}
$$

Células de código

Células de código contém as instruções a serem executadas pelo kernel. À esquerda de uma célula de código aparece o sinal In[n] que significa Input [n], onde n é a ordem de execução das linhas. Uma célula em exibição é marcada pelo sinal In[*], o que é importante observar quando se tem uma execução mais demorada de código. Em geral o notebook continua responsivo mas novas instruções devem aguardar o término das primeiras para serem executados. O resultado da computação da célula, quando existir, aparece abaixo com o sinal Out[n].

O código em um célula ativa (com bordas azuis) é executado com ctrl-enter ou shift-enter (alternativamente com botão ▶ Run na barra de ferramentas). A barra de menu contém as opções Cell | Run All, Cell | Run All Above Cell | Run All Below.

É importante notar que as células são executadas no kernel e seu estado persiste ao longo da execução. O estado do kernel se refere ao notebook como um todo e não às células individuais. Se você importar bibliotecas ou declarar variáveis ​​em uma célula elas estarão disponíveis em toda a seção e não apenas nas células abaixo da declaração. A ordem em que inputs e outputs aparecem pode ser enganosa: se você declarar uma variável em uma célula, digamos g = 5 e voltar para uma célula anterior a variável g ainda terá o mesmo valor. O que importa é a ordem de execução, marcada por In[n]. Por isso é preciso ter cuidado ao fazer alterações nas células. Idealmente se deve manter a ordem sequencial e, ao fazer alterações importantes, executar todo o notebook novamente.

Existem várias opções relativas à execução no menu Kernel:

Kernel | Interrupt Interromper o kernel,
Kernel | Restart Reinicializar o kernel,
Kernel | Restart & clear outputs Reinicializar kernel e limpar outputs,
Kernel | Restart & Run All Reinicializar kernel e executar todas as células.

A opção de reinicializar o kernel limpando as saídas e executar novamente todas as células pode ser útil quando muitas células foram alteradas. No entanto, dependendo das operações a serem executadas, ela pode ser uma operação demorada.

É possível escolher e rodar e Jupyter Notebook com diferentes opções de kernel, com diferentes versões de Python e muitas outras linguagens, incluindo Java, C, R e Julia.

O Notebook é salvo ao se pressionar Ctrl S. Isso renova o arquivo de ponto de verificação que é criado junto com o Notebook. Esse arquivo, que também tem extensão .ipynb fica localizado em pasta oculta e pode ser usado na recuperação da sessão caso algum erro inesperado cause a perda do notebook atual. Por padrão o Jupyter salva automaticamente o bloco de notas a cada 120 segundos sem alterar o arquivo de bloco de notas principal.Para reverter para um ponto de verificação use o menu via File | Revert to Checkpoint.

Tendo escolhido um notebook com kernel python 3, podemos experimentar um resultado com a execução de código que fornece um output de texto e gráfico:

# importe as bibliotecas necessárias
import numpy as np
import matplotlib.pyplot as plt

x = np.arange(1, 15, 0.1);
y = np.sin(x)/np.cos(x)
z = np.cos(x)/np.sin(x)
print("x em [1, 15] \ny=seno/cosseno; z=cosseno/seno")
plt.plot(x, y)
plt.plot(x, z)
x em [1, 15]
y=seno/cosseno; z=cosseno/seno

É importante observar que a última variável listada em uma célula é exibida no output sem necessidade de um comando print. Por ex., no código abaixo importamos uma tabela disponível na web no formato *.csv para a construção de um dataframe do pandas. O dataframe é exibido com uma formatação amigável no final da célula.

1  import pandas as pd
2  bfi ='https://vincentarelbundock.github.io/Rdatasets/csv/psych/bfi.csv'
3  df = pd.read_csv(bfi)
4  # head exibirá apenas as 5 primeiras linhas do dataframe
5  df.head()
Unnamed: 0 A1 A2 A3 A4 A5 C1 C2 C3 C4 N4 N5 O1 O2 O3 O4 O5 gender education age
0 61617 2.0 4.0 3.0 4.0 4.0 2.0 3.0 3.0 4.0 2.0 3.0 3.0 6 3.0 4.0 3.0 1 NaN 16
1 61618 2.0 4.0 5.0 2.0 5.0 5.0 4.0 4.0 3.0 5.0 5.0 4.0 2 4.0 3.0 3.0 2 NaN 18
2 61620 5.0 4.0 5.0 4.0 4.0 4.0 5.0 4.0 2.0 2.0 3.0 4.0 2 5.0 5.0 2.0 2 NaN 17
3 61621 4.0 4.0 6.0 5.0 5.0 4.0 4.0 3.0 5.0 4.0 1.0 3.0 3 4.0 3.0 5.0 2 NaN 17
4 61622 2.0 3.0 3.0 4.0 5.0 4.0 4.0 5.0 3.0 4.0 3.0 3.0 3 4.0 3.0 3.0 1 NaN 17

2800 rows × 29 columns

Ajuda

É sempre útil lembrar os mecanismos de se conseguir ajuda no python e no Jupyter. A função help do python é útil para se ver documentação sobre um tipo de variável ou uma bliblioteca importada. (Em ambos os casos a saída exibida está truncada.)

# ajuda sobre dictionaries
help(dict)
Help on class dict in module builtins:
class dict(object)
| dict() -> new empty dictionary
| dict(mapping) -> new dictionary initialized from a mapping object’s
| (key, value) pairs
| dict(iterable) -> new dictionary initialized as if via:
| d = {}
| for k, v in iterable:
| d[k] = v
import math
help(math)
Help on module math:
FUNCTIONS
acos(x, /)
Return the arc cosine (measured in radians) of x.
acosh(x, /)
Return the inverse hyperbolic cosine of x.
asin(x, /)
Return the arc sine (measured in radians) of x.

O comando help() usado sem argumento abre uma janela de busca interativa do tópico de ajuda.

Além disso escrever o nome de uma biblioteca, método ou variável precedido de ? provocará a exibição da docstring relativa ao item, o que é uma boa forma de conferir uso e sintaxe.

import pandas as pd
?pd
Type: module
String form: <module ‘pandas’ from ‘/home/guilherme/.anaconda3/lib/python3.7/site-packages/pandas/__init__.py’>
File: ~/.anaconda3/lib/python3.7/site-packages/pandas/__init__.py
Docstring:
pandas – a powerful data analysis and manipulation library for Python
=====================================================================
**pandas** is a Python package providing fast, flexible, and expressive data
structures [… texto truncado …]

Além disso é possível exibir a docstring de um objeto no Notebook apertando Shift-Tab após o nome do objeto dentro da célula.

Células e Linhas Mágicas em Jupyter

Uma sintaxe especial dos notebooks consiste em inserir comandos iniciados por %% para “mágica” na célula inteira e % para “mágica” na linha. Por exemplo %matplotlib inline faz com que gráficos do matplotlib sejam renderizados dentro do próprio notebook. Os sinais % e %%indicam respectivamente “mágica” na linha ou na célula. Digitar %lsmagic na célula e executá-la exibirá uma lista de todos os comandos mágicos de célula e de linha, informando ainda se automagic está ativado. Se automagic = ON os prefixos %% e % são desnecessários.

Alguns exemplos de “mágicas”:

Mágica Efeito
%run Roda um script externo como parte da célula.
Ex.: %run meu_codigo.py
executa meu_codigo.py como parte da célula.
%timeit Conta os loops, mede e exibe o tempo de execução da célula.
%prun Mostra o tempo de execução de uma função.
%%writefile Salva o conteúdo da célula para um arquivo.
Ex.: %%writefile meu_output.py
salva o código da célula no arquivo meu_output.py.
%%pycat Lê e exibe o conteúdo de um arquivo.
Ex.: %%pycat meu_output.py
lê o conteúdo gravada antes em meu_output.py.
%macro Define uma macro para execução posterior.
%store Salva a variável para uso em outro notebook.
%pwd Exibe a pasta default de trabalho.
%who Exibe varáveis ativas.
%matplotlib inline Exibe gráficos matplotlib inline.
%lsmagic Exibe lista de comandos “mágicos”.
%automagic Liga/desliga automagica (necessidade de %).
%%javascript Roda a célula como código JavaScript.
%%html Exibe código html renderizado.
%pdb Aciona o Python Debugger.
%<comando>? Mostra ajuda sobre a %<comando>
%%script python2
import sys
print 'Esse comando foi executado no Python %s' % sys.version
# output---> Esse comando foi executado no Python 2.7.18 (default, data / hora) 
%%script python3
import sys
print('Comando executado no Python: %s' % sys.version)
# output---> Esse comando foi executado no Python 3.8.5 (default, data / hora) 
%%bash
echo "O conteúdo de minha variável BASH: $BASH"
# output---> O conteúdo de minha variável BASH: /usr/bin/bash
# Definição de fatorial usando recursão	
def fatorial(n):
    if n == 1:
        return 1
    else:
        return n * factorial(n-1)
fatorial(40)      # resulta em 87178291200
# Claro que a mesma coisa seria obtida com a função
import math
print(math.factorial(14))    # 87178291200

Para medir o tempo de execução da célula ao rodar a função fatorial usamos %timeit

%timeit fatorial(14)

1.78 µs ± 16.9 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)

Executando comandos da SHELL

Usando o prefixo ! você pode enviar comandos diretamente para a shell de seu sistema operacional. Os comandos dependerão, claro, de seu sistema. No exemplo seguinte uso o bash do linux.

! ls *.ipynb     # vai listar todos os arquivos ipynb
! ls *.py        # lista meu_output.py gravado no exemplo anterior 

# mv é o comando bash para renomear arquivos
! mv meu_output.py novo_nome.py 
! ls *.py        # lista novo_nome.py

# Se você tem pip instalado pode gerenciar pacotes python de dentro do notebook:
!pip install --upgrade nome_do_pacote

Extensões do Jupyter Notebook


Extensões são recursos adicionais que estendem a funcionalidade dos Notebooks. Elas podem melhorar sua funcionalidade como uma IDE (um ambiente integrado de desenvolvimento), permitindo o acompanhamento de variáveis para fins de debugging, formatando o código automaticamente ou alterando sua aparência. Elas também permitem a inserção de widgets, que geralmente são objetos com representação gráfica no navegador, tais como caixas de texto, sliders e outras ferramentas interativas. Elas adicionam funcionalidades GUIs nos notebooks.

Uma extensão muito usada é a Nbextensions que pode ser instalada à partir do código seguinte, inserido no próprio notebook.

conda install -c conda-forge jupyter_contrib_nbextensions
conda install -c conda-forge jupyter_nbextensions_configurator 

A instalação de extensões pode variar de acordo com o seu ambiente de trabalho.

Jupyter Widgets

Widgets são objetos do python que possuem uma representação visual no navegador e permitem interação do usuário. Eles podem ser simples como uma caixa de texto ou um controle de arrastar, ou objetos sofisticados como os controles sobre uma tabela de dados ou sobre um mapa.

Slider é um widget útil para receber um valor do usuário por meio do mouse ou toque de tela. O objeto possui propriedades que podem ser alteradas e lidas, e métodos.
No exemplo abaixo um slider é criado, algumas de suas propriedades são ajustadas e depois é exibido.

import ipywidgets as ipw
# Inicializar um slider
slid = ipw.IntSlider()
slid.min = 0
slid.max = 50
slid.description = "Avalie:"
display(slid) # Exibe o slider ( figura a)

# O objeto pode ser inicializado com as propriedades desejadas
slid2 = ipw.IntSlider(
    value=0,
    min=0,
    max=10,
    step=2,
    description='Só pares:',
    disabled=False,
    continuous_update=True,
    orientation='horizontal',
    readout=True,
    readout_format='d'
)
display(slid2) # Exibe o slider ( figura b)

Button é um widget que pode armazenar interação do usuário em resposta binária (sim/não, por ex.).

ipw.Button (
    description='Clica aí',
    disabled=False,
    tooltip='clica...',
    button_style='success', # pode ser 'success', 'info', 'warning', 'danger' ou ''
    icon='check'
)
# Exibe o botão (figura c)

Text apresenta uma caixa de texto a ser preenchida pelo usuário:

ipw.Text (
    placeholder='Digite seu nome',
    description='Nome:',
)
# Exibe a caixa de texto ( figura d)

Progress Bar mostra uma barra de progresso:

ipw.IntProgress (
    min=0,
    max=10,
    value=7,
    description='Realizado %',
    bar_style='success', # pode ser 'success', 'info', 'warning', 'danger' ou ''
    orientation='horizontal'
)
# Exibe a barra de progresso ( figura e)

Para serem úteis as widgets devem interagir com o código. Como ex. vamos criar uma barra de progresso atribuindo o objeto a uma variável.

pb = ipw.IntProgress (
    min=0,
    max=10,
    value=7,
    description='Realizado%',
    bar_style='success', # pode ser 'success', 'info', 'warning', 'danger' ou ''
    orientation='horizontal'
)

print('valor inicial = ', pb.value) # value é uma propriedade de pb. Neste caso seu valor é 7

pb.value = 10                       # que pode ser alterada no código
display(pb)	                        # exibe uma barra de progesso cheia

No exemplo seguinte fazemos uma interação entre os valores da barra de progresso com o clique de dois botões. O código usa o evento on_click dos botões para acionar as funções que aumentam e diminuem o valor da barra.

def aumentaBarra(s):
    pb.value +=1

def diminuiBarra(s):
    pb.value -=1

botaoMais = ipw.Button(description='Aumenta barra')
botaoMais.on_click(aumentaBarra)

botaoMenos = ipw.Button(description='Diminue barra')
botaoMenos.on_click(diminuiBarra)
# display(botaoMenos, botaoMais, pb)
# -- isso exibiria os controles um sobre o outro

# Para exibir os controles em uma linha única com título
# usamos HBox, Label

from ipywidgets import HBox, Label
HBox([Label('Em uma linha única:'), botaoMenos, botaoMais, pb])         # exibe figura (f)


Existem widgets mais sofisticados para formatação dos controles, inclusive com o uso de html e formatação css. Apenas para mostrar um exemplo segue o código abaixo, que usa HBox para construir uma linha e VBox para construir uma coluna de controles.

from ipywidgets import HBox, VBox, Label	
linha1 = HTML('<h2 style="color: red;">Use controles para modificar <i>progress box</i> </h2>')
linha2 = HBox([Label('Botões de controle:'), botaoMenos, botaoMais])
linha3 = pb
VBox([linha1, linha2, linha3]) # exibe figura (g)


Um clique no primeiro botão faz a barra de progressa avançar, no segundo faz a barra regredir.

Observe importamos os controles HBox,VBox e Label de ipywidget e, portanto eles podem ser usados diretamente sem menção à biblioteca de origem. Poderíamos usar a notação ipw.HBox para usar a caixa horizontal, sem precisar da importação explícita.

Outras informações sobre formatação dos widgets em
Layout and Styling of Jupyter widgets
.

Outros Widgets Úteis

HTMLMath serve para exibir equações matemáticas:

equacao = ipw.HTMLMath(
    value = r"Widgets podem ser usados para exibir equações inline \(x^2\) e destacadas $$\frac{x^2-1}{x-1}= x+1$$",
    placeholder='HTML',
    description='MathML:',
)
display(equacao)
MathML: Widgets podem ser usados para exibir equações inline \(x^2\) e destacadas $$\frac{x^2-1}{x-1}= x+1$$

ipyleaflet é uma biblioteca para a criação de mapas interativos que permitem marcação, arraste e ampliação. Em muitos casos, para executar um biblioteca recém instalada, pode ser necessário reinicializar o kernel.

# A biblioteca pode ser instalada com condas:
conda install -c conda-forge ipyleaflet

from ipyleaflet import Map
# inserindo as coordenadas da Praça da Liberdade em Belo Horizonte, MG
Map(center=[-19.932252,-43.9381638], zoom=15)

BeakerX é um pacote com widgets destinados a representar tabelas, gráficos, formulários de modo interativo. O widget de tabela reconhece e exibe dataframes do pandas. Ele facilita a pesquisa, e permite classificar, arrastar, filtrar, formatar ou selecionar células na tabela. Ele também permite a exportação para CSV ou área de transferência e a representação gráfica dos dados. O widget de tabela é mostrado abaixo, em imagem estática. Mais informações em Beakerx.

# Instalação do pacote
conda install -c conda-forge beakerx ipywidgets

import pandas as pd
from beakerx import *
pd.read_csv("UScity.csv")
# Instalando o pacote
conda install -c conda-forge k3d	

import k3d
plot = k3d.plot()
plot += k3d.points([0, 0, 0, 1, 1, 1])
plot.display()

A figura dentro do Notebook é dinâmica, podendo ser girada, ampliada, exportada, etc.

Modificando o estilo do Notebook

Jupyter Notebooks são enviados para o navegador como páginas html e são formatadas e estilizadas por meio de arquivos css (cascade style sheets) padrões. Para quem conhece html e css pode ser interessante editar diretamente esse arquivo. (Não se esqueça de fazer cópias de segurança dos arquivos que vai modificar).

Se sua instalação não contém a pasta “.jupyter” execute o comando jupyter notebook --generate-config no terminal. No Linux o arquivo de estilos está em /home/usuario/.jupyter/custom/custom.css, no Windows em pasta.do.python\Lib\site-packages\notebook\static\custom\custom.css, embora isso possa ser alterado ou ser diferente para outras instalações. Para ver a pasta onde está o arquivo de configurações você pode usar:

import jupyter_core
jupyter_core.paths.jupyter_config_dir()

Existem muitas folhas de estilo prontas para baixar, por exemplo no GitHub. Elas podem ser baixadas e copiadas para a pasta citada.

Para modificar apenas o estilo do Notebook aberto, sem alterar a aparência dos demais você pode usar:

# Importe biblioteca 
from IPython.core.display import HTML
HTML("<style> instruções de estilo </style>")
# Alternativamente se pode usar "mágica" em uma célula
%%html "<style> estilos - CSS </style>"

# Por exemplo, para atribuir margens laterais de 10% do tamanho da página use
display(HTML("<style>.container { margin: 0 10% 0 10% !important; }<style>"))

# Para exibir outputs em negrito
display(HTML("<style>.output_wrapper { font-weight: bold !important; }</style>"))

De dentro de um Notebook você pode carregar uma folha de estilo particular que passa a valer para aquele documento. Esse método é útil para formatar documentos de um tipo específico, por exemplo para uma apresentação ou páginas com estilos incomuns.

from IPython.core.display import HTML
def css_styling():
    styles = open("../styles/custom.css", "r").read()
    return HTML(styles)
css_styling()

Finalmente você pode instalar extensões tais como Jupyter themes.

Exportando e Compartilhando Notebooks


Notebooks podem ser exportados para diversos formatos tais como HTML e PDF e vários outros formatos. Isso pode ser encontrado no menu File | Download as. Se estiver trabalhando na nuvem a importação no formato nativo .ipynb serve para baixar para seu computador uma cópia do notebook. Ao subir uma cópia para o GitHub ou para o Colab você pode disponibilizar a sessão para outros colaboradores. Slides são úteis para aulas e apresentações.

NBViewer: NBViewer é um renderizador de notebooks, útil para quem quer ver uma sessão sem ter que necessariamente instalar o Jupyter. Esse é um serviço gratuito oferecido pelo Projeto Jupyter, disponível em nbviewer.jupyter.org. Ele recebe uma URL do notebook e o renderiza como página da web.

Bibliografia

  • Wintjen, Marc: Practical Data Analysis Using Jupyter Notebook: Learn how to speak the language of data by extracting useful and actionable insights using Python, Packt Publishing, Birmingham, UK, 2020.
  • Taieb, David: Thoughtful Data Science, , Packt Publishing, Birmingham, UK, 2018.
  • Dataquest: Advanced Jupyter Notebooks Tutorial, acessado em novembro de 2020.
  • Real Python: Jupyter Notebook Introduction, acessado em novembro de 2020.
  • Jupyter.org: Jupyter Main Site, acessado em novembro de 2020.
  • jupyter.org: Jupyter Widgets, acessado em novembro de 2020.

Marcação de Texto com Markdown

“O poeta é um fingidor. Finge tão completamente que chega a fingir que é dor a dor que deveras sente.”
Fernando Pessoa, Autopsicografia.

O que é Markdown

Markdown é uma linguagem de marcação de texto. Ele permite a insercão de marcas ou códigos em texto simples que são representados na exibição final em formatos sofisticados. Além disso ela permite a conversão para textos em HTML, que podem ser distribuídos pela web (ou localmente) e lidos por browsers. A marcação foi concebida para deixar o texto simples e legível. Markdown é software livre, disponível sob uma licença BSD de código aberto.

Títulos (Headings)

Para criar títulos use sinais # em frente ao texto (um para cada nível).

Markdown html Output obtido
# Título de nível 1 <h1>Título de nível 1</h1> (título de nível 1)
## Título de nível 2 <h2>Título de nível 2</h2> (título de nível 2)
### Título de nível 3 <h3>Título de nível 3</h3> (título de nível 3)
#### Título de nível 4 <h4>Título de nível 4</h4> (título de nível 4)
##### Título de nível 5 <h5>Título de nível 5</h5> (título de nível 5)
###### Título de nível 6 <h6>Título de nível 6</h6> (título de nível 6)

Alternativamente, é possível sublinhar com sinais de igual (===) para gerar um título de nível 1 e com traços (---) para gerar um título de nível 2:

Markdown Output
Título de nível 1
=================
(Título de nível 1)
Título de nível 2
—————–
(Título de nível 2)

Bastam dois sinais == ou -- para a representação de título.

Parágrafos

Parágrafos são linhas de texto separadas por linhas vazias.

Markdown html Output obtido
Markdown é simples.
Vou usá-lo sempre!
<p>Markdown é simples.</p>
<p>Vou usá-lo sempre!</p>
Markdown é simples.
Vou usá-lo sempre!

Quebra de linhas

Para quebrar uma linha termine a linha com 2 ou mais espaços (⎵ ⎵) seguidos de return ().

Markdown html Output obtido
Essa é a primeira linha. ⎵⎵↲
Essa é a segunda linha.
<p>Essa é a primeira linha.<br>
Essa é a segunda linha.</p>
Essa é a primeira linha.
Essa é a segunda linha.

Negrito e itálico

Texto em negrito é obtido com asteriscos ou traços baixos (underscores) envolvendo o texto a negritar. Letras dentro da palavra também podem ser negritadas com duplos asteriscos.

Markdown html Output obtido
Precisamos de **negrito**. Precisamos de <strong>negrito</strong>. Precisamos de negrito.
Precisamos de __negrito__. Precisamos de <b>negrito</b>. Precisamos de negrito.
abcdef**GH**ij abcdef<strong>GH</strong>ij abdcefGHij

Textos em itálico são obtidos com um asterisco ou uma traço baixo (underscores) envolvendo o texto. Letras dentro da palavra também podem ser tornadas itálicos com um asterisco.

Markdown html Output obtido
Texto *em itálico*. Texto <em>em itálico</em>. Texto em itálico.
Texto _em itálico_. Texto <i>em itálico</i>. Texto em itálico.
a*bcd*ef a<em>bcd</em>ef abcdef

Texto em negrito e itálico simultâneos são obtidos com três asteriscos ou traços baixos (underscores) envolvendo o texto. Letras dentro da palavra também podem ser negritadas com três asteriscos.

Markdown html Output obtido
Um texto ***muito importante***. Um texto <strong><em>muito importante</em></strong>. Um texto muito importante.
Um texto ___muito importante___. Um texto <b><i>muito importante</i></b>. Um texto muito importante.
Um texto __*muito importante*__. Um texto <i><b>muito importante</b></i>. Um texto muito importante.
Um texto **_muito importante_**. …idem… Um texto muito importante.
Texto***muito***importante. Texto<strong><em>muito</em></strong>importante. Textomuitoimportante.

Textos riscados são obtidos com dois “tils” ˜˜ anterior e posterior ao texto.

Markdown html Output obtido
Texto ˜˜riscado˜˜. Texto <del>riscado</del>. Texto riscado.

Linha horizontal

Linhas horizontais são inseridas com três ou mais asteriscos (***), ‘dashes’ (---), ou ‘underscores’ (___) em uma linha.

Markdown html Output obtido
*** <hr>

Blocos

Para criar blocos destacados (citações) coloque > na frente do parágrafo.

> “O poeta é um fingidor. Finge tão completamente que chega a fingir que é dor a dor que deveras sente.”
> ― Fernando Pessoa, Autopsicografia.

“O poeta é um fingidor. Finge tão completamente que chega a fingir que é dor a dor que deveras sente.”
― Fernando Pessoa, Autopsicografia.

Blocos destacados podem conter muitos parágrafos. Para isso basta inserir > em cada linha branca entre as parágrafos.

> “Nós, os mortais, alcançamos a imortalidade nas coisas que criamos em comum e que estão atrás de nós.”
>
> “A coisa mais bela que podemos experimentar é o mistério. Essa é a fonte de toda a arte e ciências verdadeiras.”
> ― Albert Einstein.

“Nós, os mortais, alcançamos a imortalidade nas coisas que criamos em comum e que estão atrás de nós.”
“A coisa mais bela que podemos experimentar é o mistério. Essa é a fonte de toda a arte e ciências verdadeiras”.
― Albert Einstein.

Blocos ou citações podem ser aninhadas. Para isso coloque >> na frente do parágrafo com segunda indentação.

> “Eu jamais iria para a fogueira por uma opinião minha pois não tenho certeza alguma. Porém, eu iria pelo
direito de ter e mudar de opinião, quantas vezes quisesse.”
>
>> ”Sem música a vida seria um erro.”
> ― Friedrich Nietzsche

“Eu jamais iria para a fogueira por uma opinião minha pois não tenho certeza alguma. Porém, eu iria pelo direito de ter e mudar de opinião, quantas vezes quisesse.”

“Sem música a vida seria um erro.”

― Friedrich Nietzsche

Listas

Listas ordenadas (numeradas) são criadas numerando-se as linhas, cada número seguido de ponto. Qualquer número serve para isso, embora o número da primeira linha marque o número usado na lista:

Markdown html Output obtido
1. Primeiro item
2. Segundo item
3. Terceiro item
4. Quarto item
<ol>
<li>Primeiro item</li>
<li>Segundo item</li>
<li>Terceiro item</li>
<li>Quarto item</li>
</ol>
  1. Primeiro item
  2. Segundo item
  3. Terceiro item
  4. Quarto item
1. Primeiro item
1. Segundo item
1. Terceiro item
  1. Indentado item 1
  1. Indentado item 2
1. Quarto item
<ol>
<li>Primeiro item</li>
<li>Segundo item</li>
<li>Terceiro item
<ol>
<li>Indentado item 1</li>
<li>Indentado item 2</li>
</ol>
</li>
<li>Quarto item</li>
</ol>
  1. Primeiro item
  2. Segundo item
  3. Terceiro item
    1. Indentado item 1
    2. Indentado item 2
  4. Quarto item

Observe que não é necessário usar a numeração correta nas listas. Alguns editores completam automaticamente esses números. A segunda indentação (ou lista dentro de outra lista) é gerada por espaços ou tab antes do item.

Listas não numeradas são criadas com os sinais *, + ou - antes dos itens.

Markdown html Output obtido
– Primeiro item
– Segundo item
– Terceiro item
– Quarto item
<ul>
<li>Primeiro item</li>
<li>Segundo item</li>
<li>Terceiro item</li>
<li>Quarto item</li>
</ul>
  • Primeiro item
  • Segundo item
  • Terceiro item
  • Quarto item
– Primeiro item
– Segundo item
– Terceiro item
  - Indentado item 1
  - Indentado item 2
– Quarto item
<ul>
<li>Primeiro item</li>
<li>Segundo item</li>
<li>Terceiro item
<ul>
<li>Indentado item 1</li>
<li>Indentado item 2</li>
</ul>
</li>
<li>Quarto item</li>
</ul>
  • Primeiro item
  • Segundo item
  • Terceiro item
    • Indentado item 1
    • Indentado item 2
  • Quarto item

Blocos de código

Uma anotação apropriada para código, principalmente de programação, é uma característica muito útil no markdown. A indentação correta para blocos de código pode ser conseguida com linhas precedidas por 4 espaços ( ) ou 1 tab. Dentro de uma lista essas linhas são precedidas por 8 espaços ou 2 tabs. Nesse contexto usamos o sinal para representar um espaço:

Markdown html Output obtido
⎵⎵⎵⎵def soma(a,b):
⎵⎵⎵⎵⎵⎵⎵⎵return a + b
⎵⎵⎵⎵print (soma(5, 7))
<pre>
  def soma(a,b):
    return a + b
  print (soma(5, 7))
</pre>
  def soma(a,b):
    return a + b
  print(soma(5, 7))

Alternativamente, blocos de código também podem ser colocados entre três acentos graves, backticks, ```:

Markdown Output obtido
```
function factorial(n) {
  if (n === 0) return 1; // 0! = 1
  return n * factorial(n – 1);
}
factorial(3); // returns 6}
```
function factorial(n) {
  if (n === 0) return 1; // 0! = 1
  return n * factorial(n – 1);
}
factorial(3); // returns 6}

Nesse formato de bloco de código é possível marcar o código com cores, de acordo com a linguagem selecionada (syntax highlighting). Essa característica depende do processador usado. No exemplo seguinte o código é marcado como JSON, o que é informado após o primeiro grupo de acentos graves.

Markdown Output obtido
``` json
{
  ”nome”: “José”,
  ”sobrenome”: “Garcia”,
  ”idade”: 45
}
```
{
  “nome”: “José”,
  “sobrenome”: “Garcia”,
  “idade”: 45
}

Para denotar texto em código, uma ou mais palavras, coloque-as entre acentos graves (backticks, `).

Markdown html Output obtido
Digite no prompt de comando: `nano`. Digite no prompt de comando: <code>nano</code>. Digite no prompt de comando: nano.

Imagens

Para acrescentar uma imagem use a seguinte sintaxe:


![Imagem 1](caminho/images/tux.png “Título a ser exibido”)

Tabelas

Tabelas são criadas usando-se a barra vertical | e hífens. Por exemplo, as três tabelas abaixo mostram o uso do código markdown a seguir

Tabela (1)

| Título 1 | Título 2 | T3 |
| ‐‐‐‐‐‐‐‐‐‐‐‐| ‐‐‐‐‐‐‐‐‐‐‐‐|‐‐-‐|
| célula 1, 1 | célula 1, 2 | 1 |
| célula 2, 1 | célula 2, 2 | 2 |

Tabela (2)

| Alinhamento | Alinhamento | Alinhamento |
| :‐‐‐‐‐‐‐‐‐‐ | :‐‐‐‐‐‐‐‐‐: | ‐‐‐‐‐‐‐‐‐‐: |
| Esquerda | Centro | Direita |
| 1 | 2 | 3 |

Tabela (3)

Título | N
-|-
a|b

são representadas como as tabelas (1), (2) e (3) abaixo:

A tabela (2) ilustra o uso dos sinais de alinhamento: à esquerda (:‐‐), centralizado (:‐‐:) (centralizado) e à direita (‐‐:). Os itens da tabela não precisam estar bem alinhados no markdown e as barras laterais são dispensáveis, como é mostrado na tabela (3). Dentro das tabelas o texto pode conter links, negrito e itálico e código.

Links

Links para outras páginas, locais ou na web, podem ser inseridos dentro de colchetes (ex.: [Duck Duck Go]) seguidos da URL entre parênteses. Por ex. (https://duckduckgo.com)).

Markdown html Output obtido
Recomendo o mecanismo de busca_ _
[Duck Duck Go](https://duckduckgo.com).
Recomendo o mecanismo de busca <br>
<a href=”https://duckduckgo.com”>Duck Duck Go</a>.
Recomendo o mecanismo de busca
Duck Duck Go.

Notas de Pés de Página

Segue um exemplo de texto com notas de pé de página.

Use a seguinte notação para criar pés de página[^1], que também pode conter textos mais longos e várias parágrafos[^2].
Os marcadores não precisam ser números[^t].[^1]: O pé de página fica no final do texto.
[^2]: Um pé de página pode ter vários parágrafos.
Todos os parágrafos dentro da mesma nota devem ser indentados.
`{ function teste(a, b): # pode conter código e outras formatações. }`
[^t]: Outro pé de página.

Esse código é apresentado em forma final da seguinte forma (com os links ativos):


Use a seguinte notação para criar pés de página[1], que também pode conter textos mais longos e várias parágrafos[2].
Os marcadores não precisam ser números[3].


1. O pé de página fica no final do texto.
2. Um pé de página pode ter vários parágrafos.
Todo o texto dentro do mesma anotação deve ser indentado.
{ function teste(a, b): # pode conter código e outras formatações. }
3. Outro pé de página.

Lista de tarefas

O código abaixo gera a lista mostrada à direita.

## Lista de Tarefas
- [x] Tarefa primeira (completa)
- [ ] Tarefa segunda
- [ ] Arranjar outras **tarefas**

Lista de Tarefas
☑ Tarefa primeira (completa)
Tarefa segunda
Arranjar outras tarefas

HTML

Vários aplicativos que usam Markdown, entre eles o Jupyter Notebook, também podem representar corretamente diversas tags de marcação html. Isso é útil para usuários familiarizados com html, principalmente quando se pretende inserir texto com formatos mais sofisticados, tais como como texto colorido, com variação de tamanho, caixas coloridas, etc.

Como exemplo, o código abaixo produzirá uma barra vermelha, útil para marcar o ponto de parada dentro de um notebook (Jupyter). Outro exemplo consiste na produção de texto sublinhado. Como não há código markdown específico para isso você pode conseguir texto sublinhado com as tags html.

<u>Texto 1 sublinhado</u> ou <ins>Texto 2 sublinhado</ins><div style=”border:1px solid black; padding:10px; color:white; background-color:red;”>parei aqui &curarr;</div>


Texto 1 sublinhado ou Texto 2 sublinhado

parei aqui ↷

Latex

LaTeX é uma linguagem de composição de texto para a produção de documentos científicos. Vários editores de Markdown podem renderizar equações matemáticas e símbolos Latex para reproduzir notação matemática. Em particular o Jupyter Notebook reconhece código LaTeX escrito nas células de Markdown e os representa corretamente no navegador usando a biblioteca JavaScript MathJax. Para inserir uma fórmula matemática em uma linha use o símbolo $expressão$. Para equações isoladas em uma linha e centralizadas use $$expressão$$.

A identidade de Euler é $e^{i \pi} + 1 = 0$.
As equações de Einstein são:
$$
R_{\mu\nu}-\frac{1}{2} Rg_{\mu\nu} +\Lambda g_{\mu\nu} = \frac{8 \pi G}{c^4} T_{\mu\nu}.
$$
A definição da derivada de primeira ordem é:
$$
f'(x) = \lim\limits_{h \rightarrow 0} \frac{f(x+h) – f(x)}{h}
$$

A identidade de Euler é \(e^{i \pi} + 1 = 0\).
As equações de Einstein são:
$$
R_{\mu\nu}-\frac{1}{2} Rg_{\mu\nu} +\Lambda g_{\mu\nu} = \frac{8 \pi G}{c^4} T_{\mu\nu}.
$$
A definição da derivada de primeira ordem é:
$$
f'(x) = \lim\limits_{h \rightarrow 0} \frac{f(x+h) – f(x)}{h}
$$

Editores de Markdown

Existem muitos bons editores de markdown. Algumas sugestões:

Remarkable
Haroopad
UberWriter
Macdown
Ghostwriter
Marcor

Editores online:

São excelentes aplicativos de anotações, permitindo o uso de plugins para calendários, ToDos, customização de aparência por css. Permitem a sincronização entre diversos aparelhos Mac, Windows, Linux e Androide:

SimpleNote, Joplin, Obsidian

Bibliografia