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. 两阶段文件工作流——输入文件 -> 不同的输出文件（绝不原地修改）

有关数据更新、丰富和 AWS GenomeArk 工作流的详细模式，请参阅 notebook-patterns.md。

Notebook 编辑

修改 .ipynb 文件时，始终使用 NotebookEdit 工具——切勿使用 Edit 工具（会破坏 JSON 结构）。

三种模式：replace（更新单元格内容）、insert（在目标单元格后添加新单元格）、delete（删除单元格）。

主要规则：

• 插入时始终指定 cell_type
• 使用 jq 或 Python JSON 解析查找单元格 ID
• 通过编程方式编辑后，提示用户执行“Restart & Run All”
• 更改单元格间的指标时，按依赖顺序更新

有关 NotebookEdit 的用法、通过编程方式操作 JSON、批量操作和单元格换行处理，请参阅 notebook-editing.md。

统计方法

所有相关性分析的必备要求

1. 使用 scipy.stats.pearsonr 计算皮尔逊相关系数及 p 值
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）。两组比较使用蓝色 #0173B2 + 橙色 #DE8F05
• 数据不平衡：当样本量比率 > 5x 时，添加醒目的警告

图像显示

• 在 Markdown 单元格中使用 HTML <img> 标签，实现 SVG/PNG 的响应式缩放
• 直接修改 viewBox 属性来裁剪 SVG（无需 ImageMagick）
• 管理 DPI，避免出现“Output too large”错误（默认使用 150 DPI）

有关详细的字体大小表、调色板代码、不平衡处理、SVG 操作和 DPI 管理，请参阅 visualization-guide.md。

Notebook 组织

大型 Notebook（60 个以上单元格）

• 使用 Markdown 分节标题，并采用单元格配对模式
• 统一图表、变量和函数的命名
• 从基础分析逐步扩展到复杂分析

双 Notebook 系统

对于包含 5 张以上图表、准备发表的分析：

• 代码 Notebook：可执行分析、图表生成、统计检验
• 展示 Notebook：图表展示、说明文字、解读、方法

拆分与弃用

拆分 Notebook 时，在每个拆分后的 Notebook 中重新创建所有计算列和变量定义。弃用时，创建带日期的目录并附上文档。

有关图表使用情况分析、拆分策略、双 Notebook 工作流、发表用 Notebook 结构、目录生成、弃用工作流和迁移指南，请参阅 notebook-organization.md。

分享与导出

关键规则

• 准备分享包时，保留输出（输出就是文档）
• 使用相对路径（绝不使用绝对路径），以确保可移植性
• HTML 导出最适合分享（自包含，无需软件）
• 将 Notebook 移至子目录时，以编程方式更新路径

有关路径管理、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”
• Notebook 大小：对于大于 256 KB 的 Notebook，使用 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	拆分、双 Notebook、弃用、图表分析
sharing-and-export.md	路径、HTML/PDF 导出、分享包
troubleshooting.md	常见问题、调试、验证、环境