jupyter-notebooks

関連スキル

ノートブックの結果が推奨事項、共有する主張、または意思決定の根拠となる場合は、$validate-data を使用してください。

Jupyter Notebooks

読みやすく、再実行しやすく、引き継ぎやすい、整理された再現可能な Jupyter ノートブックを作成してください。ノートブックは、作業メモの寄せ集めではなく、読者に提示する分析成果物として扱ってください。ノートブックの作業は、ノートブックが最初から最後まで正常に実行されるか、実行できない場合に再現に必要な検証手順が正確に明記されるまでは完了ではありません。

ワークフロー

1. ノートブックのモードと範囲を決めます。

   ノートブックが分析レポート、実験ログ、診断用ノートブック、データ品質チェック、市場規模の算出、モデルの検討、 チュートリアル、またはレポートの補足資料のいずれに当たるかを判断します。読者、意思決定、想定する引き継ぎ内容、 必要な入力を特定し、新しいノートブックが必要か、既存のノートブックへの対象を絞った編集が必要かを確認します。

2. ノートブックに適したツールで確認またはひな形を作成します。

   生の JSON を手作業で編集するより、JupyterLab、nbformat、nbclient、または既存のひな形ユーティリティを優先します。既存のノートブックを編集する場合は、意図を保ち、JSON の変更を最小限に抑えます。全体の流れが明らかに改善される場合を除き、セルの並べ替えは避けます。生の JSON を編集せざるを得ない場合は、 完了前にノートブックの構造を検証します。

3. 選択したモードに合わせてノートブックを構成します。

   分析ノートブックでは、次の構成を標準とします。

   1. ## tl;dr
   2. ## Context & Methods
   3. ## Data
   4. ## Results
   5. ## Takeaways

   tl;dr と結論は、実行結果を確認してから記述します。仮定ではなく、実際に観測された具体的な値、パターン、行、またはグラフを含めます。仮定が正確性に影響する場合は、Context & Methods に ### Key Assumptions のサブセクションを設けます。

   チュートリアルや手順解説では、同じ方針を次の学習の流れに合わせて調整します。

   1. ## Goal
   2. ## Setup
   3. ## Steps
   4. ## Checks
   5. ## Next Steps

4. 明確なデータと計算の流れを構築します。

   セットアップ、インポート、パラメーター、データ読み込み、データ準備、計算、可視化、解釈を分けます。ノートブックで SQL と Python の両方を使う場合、明確な理由がない限り、複雑な SQL は大きな Python の埋め込み文字列にせず、SQL セルまたは個別のクエリファイルに置きます。説明的な変数名を使い、各コードセルで扱う手順は一つに絞ります。

5. データソースを意図的に使用します。

   ノートブックでテーブルデータが必要な場合は、まず ~~structured_data を使って、テーブルの選択、スキーマ、パーティションフィルター、サンプル行、クエリ送信ポリシーを確認します。利用可能であれば該当するソースコネクターを使い、必要に応じてエクスポートデータや貼り付けた SQL に切り替えます。鮮度やデータ系譜の確認が重要な場合は、~~operations_logs を使用します。分析を支える実行結果について、クエリーのパーマリンク、リクエスト ID、ソースパス、ダッシュボードのリンク、抽出データ名などのソース情報をノートブックのコンテキストに記録します。ノートブックが広範なライブソースのスキャンにならないよう、負荷の高いクエリにはフィルターと上限を設定します。

6. セルを読みやすく、適切な範囲に収めます。

   ほとんどのコードセルの前に、簡潔な Markdown の見出しを追加します。### 1. Load Data、### 2. Validate Inputs、### 3. Plot Results のように、短く、作業内容が分かる見出しにします。用途の混在した大きなセル一つより、短いセルを複数使います。文章は簡潔にし、コードのすべての行ではなく、目的、前提、期待される結果を説明します。複数のテーブルやグラフを出力する場合は、一つのセルからまとめて出力せず、セルを分けます。

7. 結論を書く前に結果を検証します。

   重要な数値、グラフ、結論が実行結果と一致しているかを確認します。生のデバッグ出力、過大なテーブル、ノイズの多いログには上限を設けます。予想外の結果が出た場合は、要約に取り上げる前に、その場で妥当性確認、小規模なサンプルの確認、または信頼できるソースとの照合を追加します。

8. 検証を実行し、その状況を記録します。

   環境が許す場合は、ノートブックを上から順に実行します。

   python -m jupyter nbconvert --execute --to notebook --inplace path/to/notebook.ipynb
   

   必要に応じて、次のローカルセットアップを行います。

   uv pip install jupyterlab nbformat nbclient ipykernel
   

   実行できない場合は、その旨を明記し、ローカルで検証するために必要な正確なコマンド、不足している依存関係、認証情報、データアクセス、カーネル、または環境の手順を示します。

基準

Notebook の構成

• 読者がセルを順不同で実行し始める前に、上から下へ読み進められる明確な流れを整えます。
• エグゼクティブサマリーにあたる内容を冒頭に置きますが、実行結果を確認した後に作成します。
• Notebook のセクションを、Notebook の用途（分析、実験、診断、チュートリアル、引き継ぎ用成果物）に合わせます。
• セクションのタイトル、グラフのタイトル、ラベル、ファイル名は、引き継ぎに十分な情報が伝わるものにします。
• リファクタリング時は、Notebook の既存の目的を維持します。デフォルトでは、すべてを書き換えるのではなく、構成を改善します。

再現性

• パラメーター、日付範囲、フィルター、コホート、前提、ソースの参照情報を Notebook の上部付近で確認できるようにします。
• 別の読者が分析をたどれるよう、クエリのパーマリンク、リクエスト ID、テーブル名、ソースパス、スプレッドシートのタブ、ダッシュボードのリンク、抽出データのバージョン、入力ファイルの場所など、十分なソースのコンテキストを記録します。
• 可能な限り計算の決定性を確保します。隠れた状態、手動で編集した中間値、順不同の依存関係、説明のないキャッシュ済み出力は避けます。
• 標準外のパッケージ、カーネル、認証情報、ローカルファイルに Notebook が依存する場合は、明示的な環境設定セルまたは注記を設けます。
• タスクで実行可能な成果物が求められる場合は、Notebook を実行します。クリーンに実行できた場合、最終回答に定型的な検証セクションを別途追加する必要はありません。実行上の問題、一部のみの実行、未実行の Notebook がある場合は、成果物を信頼できるかどうかに影響するため、その理由を明記します。

コードとデータの衛生管理

• データの準備と提示を分けます。
• 複雑な SQL は読みやすくし、目的を説明する1行のコメントを付けます。
• データ準備のステップが完了した後に、Python でプロットや簡単なデータ整形を行います。
• 読者向けの Notebook では、説明的な変数名を使い、一時変数名の省略は避けます。
• 出力の規模を抑えます。生データのダンプではなく、小さなプレビュー表、サンプリングした行、明示的な上限、焦点を絞ったグラフを優先します。
• ライブソース全体を対象とする広範なスキャンは避けます。必要なパーティション、コホート、または期間でクエリを絞り込みます。

分析の品質

• 解釈に影響する前提を明示します。
• 実行済みの出力に基づき、具体的な数値、行、グラフ、または目に見えるパターンを挙げて結論を示します。
• 未実行または未検証の計算を tl;dr に記載しないでください。
• 留意点、未完了の確認、ソースへのアクセス不足、既知の検証上の不足を明示します。
• 驚くような結果、影響の大きい主張、関係者に提示する結論には、妥当性を確認するチェックを追加します。

検証チェックリスト

• Notebook の用途に応じた必須セクションが所定の順序で配置されています。
• Notebook が実行時エラーなしで動作するか、実行に失敗した場合はその旨が明記されています。
• 必要な箇所に出力があり、生のデバッグ情報ばかりになっていません。
• tl;dr、結果、結論が実行済みのセルと一致しています。
• ソースの参照情報とクエリまたは成果物へのリンクが保持されています。
• 表とグラフにラベルが付き、規模が抑えられ、内容を解釈できます。
• 最終回答に Notebook のパスと検証状況が記載されています。