Jupyterノートブック

コード・結果・メモを1つの文書に

Jupyter ノートブックはセルでできた文書です。コードセルには実行できる Python を書き、出力（数値、表、グラフ）がすぐ下に表示されます。Markdown セルには説明、数式、見出しなどの書式付きテキストを書きます。カーネルというバックグラウンドのプロセスがコードを実行し、セル間で変数をすべて覚えています。データの探索や分析の説明に最適で、クオンツ研究のあらゆる場面で使われています。

# 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

カーネルは覚えている。それが落とし穴

セルは任意の順序で何度でも実行でき、カーネルは各変数の最新の値を保持します。そのため、画面上は正しく見えても、削除したセルや順序を無視した実行に依存していることがあり、他の人（や明日の自分）は再現できません。各コードセルの横の実行カウンター（[3]、[7]）が実際の順序を示します。ノートブックを信頼したり共有したりする前に、カーネルを再起動してすべてのセルを実行を使いましょう。失敗したり数値が変わったりするなら、そのノートブックは再現可能ではありません。

# 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

ノートブックはただの JSON

.ipynb ファイルは、cells リストを持つ JSON 文書です。各セルには cell_type（"code"、"markdown"、"raw"）と source（行のリストまたは1つの文字列）があり、コードセルは outputs と execution_count も保存します。ただの JSON なので json モジュールで読み書きでき、ツールがスクリプトへ変換したり出力を消したりするのもこの方法です。出力とカウンターが実行のたびに変わるため、Git の差分がノイズだらけになる理由もここにあります。

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

整った信頼できるノートブックのための習慣

ノートブックは短く、上から下へ一直線に保ちます。最初のセルにインポートと設定を置き、1つの考えにつき Markdown の見出し付きで1セクションにします。再利用できるロジックは普通の .py モジュール（パッケージを参照）の関数に移してインポートし、テストできるようにします。ノートブックは呼び出しと描画だけにします。コミットの前に必ず再起動してすべて実行します。Git に入れるときは先に出力を消し（nbstripout などのツールで自動化できます）、そうしないと数メガバイトのグラフと読めない差分をコミットすることになります。API キーをセルや出力に残してはいけません。

# 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

• セルは任意の順序で実行され、カーネルは覚えている。信頼・共有の前に再起動して全実行
• .ipynb は JSON。cells の各セルに cell_type、source、コードなら outputs と execution_count
• ロジックはモジュールに置き、コミット前に出力を消し、秘密情報は入れない

次は再現可能なリサーチワークフローです。シード、環境、バージョン、データ検査を組み合わせ、誰でも結果を再現できるようにします。

ラボ：採点される内容

• code_cells でノートブックからコードを取り出す25点
• count_cells でセルの種類ごとの数を数える25点
• clear_outputs でコミット前に出力を消す25点
• to_script でノートブックをスクリプトに変換する25点