analysis-artifacts

分析产物

适用场景

• 用户要求对答案并不显而易见的问题进行“深入分析”或“分析”
• 分析需要在 BigQuery 中进行探索性查询
• 输出应可复现且可分享，而不只是一次性答案

工作流

1. 搭建分析目录

每次分析开始时：

• 在 analyses 文件夹中创建一个新目录，命名方式遵循其中现有的模式
• 创建子目录：/assets/queries 和 /assets/visualizations
• 在新目录的根目录下创建一个 README.md，作为分析的主要可读文档

2. 规划分析

无论用户是否要求，都必须在开始前制定计划。计划中的步骤应对应你认为值得探索的逻辑子问题或子领域。展示计划并等待用户批准后再继续。

3. 设置 README

计划获批后：

• 在 README 顶部添加标题、作者和日期

• 添加 问题陈述 部分，概述分析问题及要探索的子问题

• 添加 群组定义 部分，明确说明要比较的群组。如果比较两个群组（例如免费与付费、新用户与老用户、里程碑之前与之后），定义群组时应控制混杂因素。请考虑：

  • 注册／激活时间（按产品定义，例如首次登录、首次有意义的操作）；这与用户使用时长有关
  • 套餐类型或订阅层级（例如免费与付费）
  • 控制不同群组观察时间窗口的长度
  • 与分析问题相关的产品专属使用倾向指标

  定义群组后，必须在整个分析的所有查询中遵循这些定义。

4. 随分析进展创建产物

在分析的每个重要步骤中：

• SQL 查询产物：对于任何用于生成可视化、摘要或关键洞察的 BigQuery 查询，在 /assets/queries/ 中保存一个 .sql 文件，文件名应具有描述性，并附上说明查询用途的注释块。只有在对结果满意后才创建文件。略过简单或一次性的查找查询。
• 可视化或表格产物：针对每项关键洞察，判断用图表还是表格呈现效果最佳。优先考虑可视化。如果使用可视化，则编写 Python 脚本生成图表，并将脚本和输出图像以具有描述性的名称保存到 /assets/visualizations/。如果使用表格，则将其保存为 /assets/visualizations/ 中的 .csv 文件。

5. 覆盖产物

如果需要重做部分分析（由于方法修正或用户反馈），请覆盖所有相关产物：

• 替换 .sql 查询文件
• 替换可视化脚本并重新生成图像
• 替换 .csv 表格文件

进行此操作时，请告知用户变更内容。

6. 总结分析

分析完成后（计划结束时或用户提出要求时），编写完整的 README：

• 在文档中按逻辑章节总结每个步骤和子问题
• 简洁明了，避免不必要的冗长
• 在适当位置嵌入 /assets/visualizations/ 中保存的可视化图片
• 根据 /assets/visualizations/ 中的 .csv 文件生成 Markdown 表格
• 在每个章节中添加指向关联查询文件的简短参考链接
• 在靠近顶部的位置添加 TL;DR 部分（放在问题陈述之后、群组定义之前）
• 在末尾添加 关键要点 部分

示例

analyses/
└── 2024-01-user-retention/
    ├── README.md
    └── assets/
        ├── queries/
        │   ├── cohort_retention_by_week.sql
        │   └── retention_by_plan_type.sql
        └── visualizations/
            ├── retention_curve.py
            ├── retention_curve.png
            └── plan_type_summary.csv