Notebooks Jupyter

Código, resultados e anotações em um só documento

Um notebook Jupyter é um documento feito de células. Uma célula de código contém Python que você pode executar; a saída (números, tabelas, gráficos) aparece logo abaixo. Uma célula markdown contém texto formatado para explicações, equações e títulos. Um processo em segundo plano chamado kernel executa o código e lembra cada variável entre as células. Notebooks são ideais para explorar dados e explicar uma análise, por isso estão em toda parte na pesquisa quantitativa.

# Inside your project's virtual environment
python -m pip install jupyterlab

# Start it; a browser tab opens
jupyter lab

# Keyboard shortcuts you will use all day
#   Shift+Enter   run the cell and move on
#   Esc then A/B  insert a cell above/below
#   Esc then M/Y  turn a cell into markdown/code

O kernel lembra, e esse é o perigo

As células podem ser executadas em qualquer ordem e quantas vezes quiser, e o kernel guarda o último valor de cada variável. Por isso um notebook pode parecer correto na tela e depender de uma célula que você apagou ou de executar células fora de ordem, e ninguém mais (nem você amanhã) consegue reproduzi-lo. O contador de execução ao lado de cada célula de código ([3], [7]) mostra a ordem real. Antes de confiar num notebook ou compartilhá-lo, use Reiniciar kernel e executar tudo: se falhar ou os números mudarem, o notebook não era reproduzível.

# Cell [1]
fee = 0.001

# Cell [2]
cost = 10000 * fee
print(cost)          # 10.0

# Cell [3]: you edit this to fee = 0.002 but never re-run cell [2]
fee = 0.002
print(cost)          # still 10.0: the notebook now says fee=0.002 but shows the old cost

Um notebook é só JSON

Um arquivo .ipynb é um documento JSON com uma lista cells. Cada célula tem um cell_type ("code", "markdown" ou "raw") e um source (uma lista de linhas ou uma string); as células de código também guardam seus outputs e execution_count. Por ser JSON simples, você pode ler e editar notebooks com o módulo json, e é assim que ferramentas os convertem em scripts ou limpam suas saídas. Isso também explica por que notebooks geram diferenças ruidosas no Git: saídas e contadores mudam a cada execução.

import json

notebook = {
    "nbformat": 4, "nbformat_minor": 5, "metadata": {},
    "cells": [
        {"cell_type": "markdown", "metadata": {}, "source": ["# Fee study\n", "Does the fee matter?"]},
        {"cell_type": "code", "metadata": {}, "execution_count": 2,
         "source": ["fee = 0.001\n", "print(10000 * fee)"],
         "outputs": [{"output_type": "stream", "name": "stdout", "text": ["10.0\n"]}]},
    ],
}

# What the file looks like, and how to walk it
print(len(json.dumps(notebook, indent=1).splitlines()) > 10)     # True
for cell in notebook["cells"]:
    print(cell["cell_type"], "".join(cell["source"]).splitlines()[0])
# markdown # Fee study
# code fee = 0.001

Hábitos para notebooks organizados e confiáveis

Mantenha os notebooks curtos e lineares: de cima para baixo, imports e configurações na primeira célula, uma ideia por seção com um título markdown. Leve a lógica reutilizável para funções num módulo .py normal (veja pacotes) e importe-a, para poder testá-la; o notebook só chama e plota. Reinicie e execute tudo antes de cada commit. Com o Git, limpe as saídas primeiro (uma ferramenta como nbstripout faz isso automaticamente) ou você commitará megabytes de gráficos e diferenças ilegíveis. Nunca deixe chaves de API numa célula ou saída.

# Keep notebooks tidy under Git
python -m pip install nbstripout
nbstripout --install           # strips outputs automatically on every commit

# Run a notebook top to bottom from the terminal (a reproducibility check)
jupyter nbconvert --to notebook --execute study.ipynb --output checked.ipynb

# Turn a notebook into a plain script
jupyter nbconvert --to script study.ipynb

• As células rodam em qualquer ordem e o kernel lembra: reinicie e execute tudo antes de confiar ou compartilhar.
• Um .ipynb é JSON: cells, cada uma com cell_type, source e, no código, outputs e execution_count.
• Mantenha a lógica em módulos, limpe as saídas antes de commitar e deixe os segredos de fora.

A seguir: fluxos de pesquisa reproduzíveis, reunindo sementes, ambientes, versões e verificações de dados para que qualquer pessoa possa refazer um resultado.

Lab: o que é avaliado

• Extrair o código de um notebook com code_cells25 pts
• Contar os tipos de células com count_cells25 pts
• Limpar as saídas antes de commitar com clear_outputs25 pts
• Transformar um notebook em script com to_script25 pts