jupyter-notebook-analysis

Jupyter Notebook分析パターン

包括的で統計的に厳密なJupyter Notebook分析を作成するための専門知識です。

このスキルを使用する場面

• データ分析用の複数セルからなるJupyter Notebookを作成するとき
• 統計的検定を伴う相関分析を追加するとき
• 外れ値を除去する戦略を実装するとき
• 関連する一連の可視化（10個以上の図）を作成するとき
• 複数の特性を持つ大規模データセットを分析するとき
• 複数のソースを統合するデータ更新・拡充用Notebookを作成するとき
• Claudeやその他のAIツールと共有する図を生成するとき

重要：画像サイズの制約

Claudeと共有する画像を生成する場合、画像のいずれの辺も8000ピクセルを超えてはなりません。Notebookのインポート部分に、次のヘルパーを追加してください。

# Standard imports with Claude size checking
import matplotlib.pyplot as plt
import seaborn as sns
from PIL import Image

MAX_CLAUDE_DIM = 7999  # Claude API limit with safety margin

def save_figure(filename, dpi=300, **kwargs):
    """Save figure with automatic Claude size constraint check."""
    plt.savefig(filename, dpi=dpi, bbox_inches='tight', **kwargs)

    # Verify and auto-resize if needed
    img = Image.open(filename)
    if img.width > MAX_CLAUDE_DIM or img.height > MAX_CLAUDE_DIM:
        print(f"Auto-resizing {filename} for Claude compatibility")
        print(f"   Original: {img.width}x{img.height}")
        img.thumbnail((MAX_CLAUDE_DIM, MAX_CLAUDE_DIM), Image.Resampling.LANCZOS)
        img.save(filename)
        print(f"   Resized: {img.width}x{img.height}")
    else:
        print(f"OK {filename}: {img.width}x{img.height}")

# Safe figure sizes for Claude (300 DPI)
FIG_SIZES = {
    'small': (7, 5),       # 2100x1500 px
    'medium': (12, 9),     # 3600x2700 px
    'large': (20, 15),     # 6000x4500 px
    'max': (26, 26),       # 7800x7800 px - maximum safe
}

# Use in notebook
fig, ax = plt.subplots(figsize=FIG_SIZES['medium'])
# ... plotting code ...
save_figure('figure.png')

画像サイズに関する詳しいガイダンスについては、data-visualizationスキルを参照してください。

Notebookの基本パターン

データ更新・拡充用Notebook

複数ソースのデータ統合と拡充には、構造化されたNotebookパターンを使用してください。主な原則は次のとおりです。

1. 先頭に設定セクションを設ける。安全のためのデフォルト値（ENABLE_AWS_FETCH = False、TEST_MODE = True）を設定します。
2. 複合キーを使って、複雑な統合要件に対応します。
3. 設定可能な戦略（NEW優先またはOLD優先）で競合を解決します。
4. 冪等な列の追加を行います。列を追加する前に、その列が存在するか確認します。
5. 拡充の状況を追跡します。取得した数だけでなく、実際に保存された数を数えます。
6. 2段階のファイルワークフローを使用します。入力ファイルから別の出力ファイルへ書き込み、同じファイルを上書きしないでください。

データ更新、拡充、AWS GenomeArkワークフローを含む詳しいパターンについては、notebook-patterns.mdを参照してください。

Notebookの編集

.ipynbファイルを変更する場合は、必ずNotebookEditツールを使用してください。JSON構造が壊れるため、Editツールは使用しないでください。

モードは3種類あります。セルの内容を更新するreplace、対象セルの後に新しいセルを追加するinsert、セルを削除するdeleteです。

主なルール：

• 挿入時は必ずcell_typeを指定します。
• jqまたはPythonのJSON解析でセルIDを確認します。
• プログラムから編集した後は、ユーザーに「Restart & Run All」を実行するよう伝えます。
• 複数のセルにまたがるメトリクスを変更する場合は、依存関係の順に更新します。

NotebookEditの使用方法、プログラムからのJSON操作、一括処理、セル内の改行処理については、notebook-editing.mdを参照してください。

統計手法

すべての相関分析で必須

1. scipy.stats.pearsonrを使用した、p値付きのPearson相関
2. すべての相関プロットにr、p値、nを表示
3. グループ比較にはMann-Whitney U検定を使用

外れ値の処理

• 第1段階：件数ベースの外れ値（IQR法）。分析前に除去します。
• 第2段階：値ベースの外れ値（パーセンタイル）。統計分析ではなく、可視化にのみ適用します。
• 特性ごとに、分析単位で個別に外れ値を除去します。
• 除去した外れ値の数を必ず報告します。

統計的主張の検証（重要）

分析用Notebookを最終化する前に必ず、統計的主張をすべて実際に計算した値と照合してください。データやコードを更新すると、テキストに記載した主張が古くなることがあります。主張を抽出し、検定を再実行して、検証表を作成してください。

詳しい統計手法、外れ値の除去コード、主張を検証するワークフロー、交絡分析については、statistical-methods.mdを参照してください。

出版品質の図

主な基準

• DPI：出版用は300、デジタル表示用は150
• フォントサイズ：タイトルは18pt太字、軸ラベルは16pt太字、目盛りは14pt、凡例は12pt
• 色：色覚多様性に配慮したパレット（IBM／Okabe-Ito）を使用します。2グループ比較には青#0173B2とオレンジ#DE8F05を使用します。
• データの不均衡：サンプルサイズ比が5倍を超える場合は、目立つ警告を追加します。

画像の表示

• レスポンシブに SVG/PNG を拡大縮小するには、Markdown のセルで HTML の <img> タグを使用します
• viewBox 属性を直接変更して SVG をトリミングします（ImageMagick は不要です）
• 「Output too large」エラーを防ぐために DPI を調整します（デフォルトは 150 DPI です）

フォントサイズの詳細な表、カラーパレットのコード、不均衡への対処、SVG の操作、DPI の管理については、visualization-guide.md を参照してください。

ノートブックの構成

大規模なノートブック（60 セル以上）

• セルをペアにするパターンを用い、Markdown のセクション見出しを使用します
• 図、変数、関数には一貫した命名規則を使用します
• 基本的な分析から複雑な分析へと段階的に拡張します

2 ノートブック方式

論文投稿に向けて 5 個以上の図を準備する分析では、次のようにします。

• コードノートブック：実行可能な分析、図の生成、統計検定
• プレゼンテーションノートブック：図の表示、キャプション、解釈、手法

分割と非推奨化

ノートブックを分割するときは、各分割先で計算済みの列と変数定義をすべて再作成します。非推奨化するときは、日付入りのディレクトリを作成し、ドキュメントを用意します。

図の使用状況の分析、分割戦略、2 ノートブックのワークフロー、論文投稿用ノートブックの構成、目次の生成、非推奨化のワークフロー、移行ガイドについては、notebook-organization.md を参照してください。

共有とエクスポート

主なルール

• 共有用パッケージを準備するときは、出力を保持します（出力はドキュメントそのものです）
• 移植性を確保するため、相対パス（絶対パスは不可）を使用します
• 共有には HTML エクスポートが最適です（自己完結型で、ソフトウェアは不要です）
• ノートブックをサブディレクトリに移動するときは、プログラムでパスを更新します

パス管理、HTML/PDF/LaTeX のエクスポート、共有用パッケージの構成、出力保持のガイドラインについては、sharing-and-export.md を参照してください。

テンプレートとヘルパーのパターン

テンプレートの生成

類似した分析セルを複数作成する場合：

template = '''
if len(data_with_species) > 0:
    print('Analyzing {display} vs {metric}...\\n')
    species_data = {{}}
    for inv in data_with_species:
        {name} = safe_float_convert(inv.get('{name}'))
        if {name} is None:
            continue
        # ... analysis code
'''

characteristics = [
    {'name': 'genome_size', 'display': 'Genome Size', 'unit': 'Gb'},
    {'name': 'heterozygosity', 'display': 'Heterozygosity', 'unit': '%'},
]

for char in characteristics:
    code = template.format(**char)

ヘルパー関数のパターン

一度定義し、全体で再利用します。

def safe_float_convert(value):
    """Convert string to float, handling comma separators"""
    if not value or not str(value).strip():
        return None
    try:
        return float(str(value).replace(',', ''))
    except (ValueError, TypeError):
        return None

トラブルシューティング

注意すべき主な落とし穴：

• 変数のシャドーイング：グローバル変数をシャドーイングするため、ループ変数に data は絶対に使用しないでください
• 列名の不一致：処理の前に必ず df.columns.tolist() を出力します
• セルの実行順序：NotebookEdit で挿入した後は、「Restart & Run All」を実行します
• ノートブックのサイズ：256 KB を超えるノートブックには jq を使用します

詳細なトラブルシューティング、変数の検証、デバッグ手法、環境のセットアップについては、troubleshooting.md を参照してください。

ベストプラクティスのまとめ

1. 分析を作成する前に、必ずデータが利用可能か確認します
2. 外れ値の除去について、タイトルとコメントに明確に記載します
3. 変数と図には一貫した命名規則を使用します
4. すべての相関に統計検定を含めます
5. 外れ値をフィルタリングする場合は、可視化と統計を分離します
6. 繰り返し行う分析にはテンプレートを作成します
7. セル全体でヘルパー関数を一貫して使用します
8. ナビゲーションしやすいよう、Markdown の見出しで整理します
9. 全件の分析を実行する前に、小規模なデータセットでテストします
10. 計算コストの高い処理では、中間結果を保存します
11. すべての .ipynb ファイルの変更には NotebookEdit ツールを使用します

関連ファイル一覧

ファイル	内容
notebook-patterns.md	データの更新、エンリッチメント、AWS GenomeArk のパターン
notebook-editing.md	NotebookEdit ツール、プログラムによる操作、メトリクスの更新
visualization-guide.md	論文投稿用の図、色、画像の表示、SVG、DPI
statistical-methods.md	外れ値への対処、統計的厳密性、主張の検証
notebook-organization.md	分割、2 ノートブック方式、非推奨化、図の分析
sharing-and-export.md	パス、HTML/PDF エクスポート、共有用パッケージ
troubleshooting.md	よくある落とし穴、デバッグ、検証、環境