data-analysis-patterns

数据分析模式

在数据分析工作流中做出关键决策的专家指导，尤其涉及聚合、重新计算和维护分析完整性。

何时使用此技能

• 决定从原始数据重新计算，还是复用聚合数据
• 更改现有分析中的类别定义
• 确保分析结果达到发表级准确度
• 处理需要拆分的混合特征
• 在不牺牲正确性的前提下优化分析流水线
• 使用复合键合并多源数据集
• 处理数据丰富过程中 DataFrame 类型转换问题

核心模式

1. 重新计算还是复用聚合数据

如果已有预聚合数据，但需要使用不同的类别或分组：

• 当类别定义发生根本变化、先前混合的特征需要拆分、聚合标准改变，或发表级准确度至关重要时，请从原始数据重新计算
• 在探索性分析中、类别高度一致，或原始数据不可用时，可以接受近似结果
• 规则：如果无法在不丢失信息的情况下有把握地将旧类别映射到新类别，就重新计算

详细模式和代码示例请参阅 data-manipulation-recipes.md

2. 使用复合键合并多源数据

合并来自多个来源的数据集时，单个标识符通常不足以确保唯一性：

• 通过使用分隔符（| 或 ::）连接多个字段来创建复合键
• 创建复合键后，务必验证其唯一性
• 合并前明确处理重复项（优先选择日期最新、记录最完整的项）
• 最终保存前移除复合键（临时工作列）

实现详情请参阅 data-manipulation-recipes.md

3. 拆分混合特征

当一个指标包含多个相互独立的特征时，请拆分为独立分析：

• 确定每个类别中混合了哪些特征
• 为每个独立特征创建单独的类别体系
• 这有助于清晰解读，并支持未来开展独立分析

示例请参阅 data-manipulation-recipes.md

4. 数据丰富过程中的 DataFrame 类型转换

使用外部来源丰富 DataFrame 时，类型不匹配很常见：

• 赋值前检查目标列的 dtype
• 转换值以匹配目标 dtype（这比转换整列更简单）
• 使用辅助函数封装类型检查逻辑
• 使用 pd.notna() 检查显式处理 NaN

类型安全的赋值模式和示例请参阅 data-manipulation-recipes.md

5. AWS 数据丰富模式

使用 AWS S3 或外部存储库丰富表格数据时：

• 使用多来源路径解析（直接查找 + 路径推断）
• 自动检测内容最完整的输入文件，以支持幂等的重新运行
• 以幂等方式添加列（添加前先检查）
• 完整丰富前，先使用 TEST_MODE 进行初步验证

实现模式请参阅 enrichment-patterns.md

6. 关键数据验证

列名并不总是与列内容一致。使用分类列前，务必对照源代码进行验证：

• 找到源脚本并验证赋值逻辑
• 添加断言以确保符合生物学合理性
• 使用已知对照样本进行测试
• 记录并修复发现的所有不匹配

完整的验证工作流和预防检查清单请参阅 validation-patterns.md

7. 数据溯源验证

派生列可能使用较差的数据源，导致数据悄然丢失：

• 将派生列的覆盖率与可能的源列进行比较
• 通过交叉制表验证映射的一致性
• 与合并稀疏的外部文件相比，优先从信息丰富的源列重新分类

有关诊断模式，请参阅 validation-patterns.md

8. 组织分析文本以提高令牌效率

将计算（笔记本）与解读（Markdown 文件）分开：

• 创建 analysis_files/ 目录，为每个图表分别创建 Markdown 文件
• 笔记本用于代码，分析文件用于解读
• 令牌用量减少 98%（笔记本为 1.1M 个令牌，分析文件为 22K 个令牌）

有关目录结构和写作指南，请参阅 analysis-organization.md

9. 多因素实验设计分析

当实验设计包含多个因素时：

• 使用三类别设计，分离各个因素的独立效应
• 每次控制一个因素，对各组进行成对比较
• 识别协同、主导或拮抗交互作用

有关解读框架和示例，请参阅 analysis-interpretation.md

10. 解读悖论性结果

当某个类别在指标 X 上表现更好，却在相关指标 Y 和 Z 上表现更差时：

• 运用权衡假设框架
• 透明地记录违反直觉的结果
• 探索机制性解释，而不是忽略研究发现

有关文档记录模式，请参阅 analysis-interpretation.md

11. 物种名称协调

当外部服务使用的物种名称与元数据不同时：

• 将不匹配分为系统性替换和名称变体
• 使用模糊匹配检测名称变体
• 将更正同步应用到所有相关文件
• 对文件进行版本标记，以追踪更正阶段

有关协调工作流和代码，请参阅 species-reconciliation.md

12. 系统发育树覆盖率分析

追踪系统发育树中有数据的部分所占比例：

• 计算覆盖率指标并识别缺失物种
• 将缺失项归类为可恢复、系统发育背景或未知
• 从已弃用的数据集中恢复 Time Tree 代理替代项
• 记录预期内和意料之外的数据缺失

有关覆盖率分析工作流，请参阅 species-reconciliation.md

13. 区分真实变异与检验效能限制

分析多个组时，判断无效应究竟是真实的，还是由检验效能不足造成：

• 检验效能受限的指标：样本量小、趋势方向符合预期、类别不平衡、置信区间较宽
• 真实零效应的指标：样本量大且置信区间较窄、方向与其他组相反、部分指标显著而其他指标不显著
• 恰当报告：“检验效能不足”或“检验效能充分但未发现效应”

有关报告建议和示例，请参阅 analysis-interpretation.md

14. 技术混杂分析

时间趋势可能反映的是技术采用，而非方法改进：

• 采用三阶段方法：混合技术基线、技术控制子集、比较
• 检验正交性、持续性和时间模式
• 使用决策矩阵判断是否跨技术合并数据

有关系统化检验方法，请参阅 analysis-interpretation.md

15. 数据整合与丰富工作流

处理多个中间数据集版本时：

• 遵循「整合 -> 丰富 -> 验证」模式
• 始终从丰富后的主数据集重新构建筛选后的子集（不要手动合并）
• 当发布日期不可靠时，从仓库文件名中提取准确日期

有关工作流详情，请参阅 enrichment-patterns.md

16. 数据文件压缩策略

对于大型数据文件，压缩而非删除：

• 决策树：活跃（保留）/可重新生成（删除）/归档（压缩）
• BED/VCF/FASTA 使用 gzip 可压缩 70%–90%
• 更新脚本以直接读取压缩文件
• 在 README 中记录压缩情况

有关压缩基准和工作流，请参阅 compression-strategies.md

核心原则

1. 当类别定义发生变化、特征被混淆，或需要保证发表准确性时，默认重新计算
2. 使用近似值时，应做好记录，并使用重新计算的数据子集进行验证
3. 将混淆的特征拆分为独立分析，以提高清晰度
4. 分析前，始终根据源代码核对列名
5. 丰富 DataFrame 时，赋值前检查 dtype
6. 从主数据集重新构建筛选后的子集，而不是手动合并新列
7. 跨技术世代汇总数据前，先检查是否存在技术混杂
8. 对于之后可能需要的数据文件，压缩而非删除

最佳实践

评估信息损失

在决定复用汇总数据前，先检查：能否从汇总数据中完美还原原始数据？如果不能，就重新计算。

记录决策

"""
Data source: scaffold_telomere_data.csv (n=6,356 scaffolds)
Recalculated: 2026-01-29
Reason: Previous aggregation conflated terminal and interstitial presence
Method: [describe categorization logic]
"""

尽可能与原始数据进行验证

original_total = df['cat1'] + df['cat2'] + df['cat3'] + df['cat4']
new_total = df['new_cat1'] + df['new_cat2'] + df['new_cat3']
assert (original_total == new_total).all(), "Category totals don't match!"

时间与准确性的权衡

• 探索阶段：可以使用近似值，但要清楚记录
• 发表阶段：始终重新计算以确保准确性
• 中间阶段：重新计算一次，保存结果并复用

性能注意事项

重新计算通常比你想象的更快：

# Modern pandas on 10,000+ rows
df['new_cat'] = df.apply(categorize_func, axis=1)
result = df.groupby('species').agg({'new_cat': 'value_counts'})
# Often < 1 second

优化：使用向量化操作，仅筛选相关列，并缓存中间结果。

支持文件

文件	内容
data-manipulation-recipes.md	重新计算模式、复合键、混淆特征、类型转换
enrichment-patterns.md	AWS 数据丰富、数据整合、日期提取、筛选数据集重建
validation-patterns.md	列名验证、数据质量检查、数据溯源
analysis-interpretation.md	多因素设计、悖论性结果、统计功效限制、技术混杂
species-reconciliation.md	物种名称协调、系统发育树覆盖范围
analysis-organization.md	节省 Token 的分析文本组织、统计结果填充
compression-strategies.md	文件压缩决策树、基准、脚本更新