Notebooks de Jupyter

Código, resultados y notas en un solo documento

Un cuaderno Jupyter es un documento formado por celdas. Una celda de código contiene Python que puedes ejecutar; su salida (números, tablas, gráficos) aparece justo debajo. Una celda markdown contiene texto con formato para explicaciones, ecuaciones y títulos. Un proceso en segundo plano llamado kernel ejecuta el código y recuerda cada variable entre celdas. Los cuadernos son ideales para explorar datos y explicar un análisis, por eso están por todas partes en la investigación cuantitativa.

# 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

El kernel recuerda, y ese es el peligro

Las celdas pueden ejecutarse en cualquier orden y cualquier número de veces, y el kernel conserva el último valor de cada variable. Por eso un cuaderno puede verse correcto en pantalla y depender de una celda que borraste o de ejecutar celdas desordenadas, y nadie más (ni tú mañana) puede reproducirlo. El contador de ejecución junto a cada celda de código ([3], [7]) muestra el orden real. Antes de fiarte de un cuaderno o compartirlo, usa Reiniciar kernel y ejecutar todo: si falla o cambian los números, el cuaderno no era reproducible.

# 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

Un cuaderno es solo JSON

Un archivo .ipynb es un documento JSON con una lista cells. Cada celda tiene un cell_type ("code", "markdown" o "raw") y una source (una lista de líneas o una cadena); las celdas de código también guardan sus outputs y execution_count. Al ser JSON simple, puedes leer y editar cuadernos con el módulo json, así es como las herramientas los convierten en scripts o les quitan las salidas. Esto explica también por qué los cuadernos generan diferencias de Git ruidosas: las salidas y los contadores cambian en cada ejecución.

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 cuadernos ordenados y fiables

Mantén los cuadernos cortos y lineales: de arriba abajo, importaciones y ajustes en la primera celda, una idea por sección con un título markdown. Lleva la lógica reutilizable a funciones de un módulo .py normal (ver paquetes) e impórtala, para poder probarla; el cuaderno solo llama y grafica. Reinicia y ejecuta todo antes de cada commit. Con Git, borra primero las salidas (una herramienta como nbstripout puede hacerlo automáticamente) o confirmarás megabytes de gráficos y diferencias ilegibles. Nunca dejes claves de API en una celda o una salida.

# 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

• Las celdas se ejecutan en cualquier orden y el kernel recuerda: reinicia y ejecuta todo antes de fiarte o compartir.
• Un .ipynb es JSON: cells, cada una con cell_type, source y, para código, outputs y execution_count.
• Mantén la lógica en módulos, borra las salidas antes de confirmar y deja fuera los secretos.

A continuación: flujos de investigación reproducibles, que reúnen semillas, entornos, versiones y comprobaciones de datos para que cualquiera pueda reconstruir un resultado.

Lab: qué se califica

• Extraer el código de un cuaderno con code_cells25 pts
• Contar los tipos de celdas con count_cells25 pts
• Borrar las salidas antes de confirmar con clear_outputs25 pts
• Convertir un cuaderno en un script con to_script25 pts