---
title: "从数据集到分析报告"
description: "说明如何让 Codex 把数据分析产出成可复查、可重跑、可交付的报告 artifact。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

数据分析的目标不是“分析本身”，而是交付能被别人使用的 artifact：管理层图表、产品实验读数、模型评估、运营 dashboard 或研究备忘录。

> [!IMPORTANT]
> 数据任务最危险的不是画错图，而是没盘点数据、没验证 join、没记录 caveat，却把结果包装成结论。

<Cards>
  <Card title="Datasets and reports" href="https://developers.openai.com/codex/use-cases/datasets-and-reports">
    查看官方数据分析与报告场景。
  </Card>
  <Card title="Skills" href="/docs/codex/official/03-extensions/09-skills-reuse">
    把重复的清洗、导出和报告步骤沉淀成 skill。
  </Card>
  <Card title="Worktrees" href="/docs/codex/official/01-products/43-worktrees">
    用 worktree 隔离假设、merge 策略和可视化分支。
  </Card>
</Cards>

## 适合什么任务

```mermaid
flowchart LR
    Raw["raw files"] --> Inventory["inventory"]
    Inventory --> Tidy["tidy / clean"]
    Tidy --> Join["join QA"]
    Join --> Explore["visualize / model"]
    Explore --> Report["report artifact"]
    Report --> Review["review / rerun"]
```

Codex 适合把数据工作做成可复查流程：

- 清点 CSV、TSV、Excel、JSON、Parquet 等输入。
- 解释每份数据的含义、主键候选、缺失值和异常。
- 编写可重跑的清洗脚本。
- 比较多种 join 策略并报告 match rate。
- 做 exploratory analysis、baseline model 和图表。
- 生成 Markdown、notebook、`.docx`、PDF 或静态报告站点。

不适合让 Codex 直接“给结论”。没有 inventory 和 join QA 的结论不能发表。

## 起始提示词

```text
我正在这个 workspace 里做 data analysis project。

目标：
- 判断靠近 highway 的 houses 是否有更低的 property valuations。

请先做，不要直接下结论：
- 阅读 AGENTS.md，解释推荐的 Python environment
- 加载 [dataset path] 下的 dataset(s)
- 描述每个文件包含什么、可能的 join keys、明显 data quality issues
- 提出可复现 workflow，覆盖 import、tidy、visualization、modeling、report output

约束：
- 优先使用 scripts 和 saved artifacts，不依赖一次性 notebook state
- 不要编造 missing values 或 merge keys
- 如果需要 skills 或 worktree splits，请说明原因

输出：
- setup plan
- data inventory
- analysis plan
- first commands or files to create
```

这个 prompt 先要求 Codex 解释环境、盘点数据和设计 workflow，而不是直接画图。数据分析里，跳过 inventory 和 join strategy 往往是后面结果不可信的根源。

## 环境先定好

开始新数据项目时，先让 Codex 读项目规则并确认环境：

- canonical Python environment。
- package manager。
- raw、processed、analysis、output 目录。
- notebook 和 script 的关系。
- artifact 命名和复跑方式。

小型 `AGENTS.md` 就够：

```md
## 数据分析默认规则

- 使用 `uv run` 或项目现有 Python environment。
- source data 放在 `data/raw/`，cleaned data 写入 `data/processed/`。
- exploratory notebooks 放在 `analysis/`，final artifacts 放在 `output/`。
- 永远不要覆盖 raw files。
- 优先使用 scripts 或已提交 notebooks，不依赖未命名 scratch cells。
- 合并 datasets 前，先报告 candidate keys、null rates 和 join coverage。
```

如果 repo 还没有定义 Python 环境，先创建可复现 setup 并说明运行方式。对数据分析来说，这一步比直接画图更重要。

## 先做数据盘点

第一轮只问 inventory，不问结论。让 Codex 回答：

- 这里有哪些 file formats。
- 每份 dataset 似乎代表什么。
- 哪些 columns 可能是 target、identifier、date、location 或 measure。
- 明显数据质量问题在哪里。
- 哪些字段不能直接用于 join。
- 哪些列需要抽样或隐私处理。

盘点输出应该保存到项目里，例如 `analysis/inventory.md` 或 `output/data-inventory.md`。不要只把结论留在线程里。

## Tidy 和 Merge

真实数据最容易在 merge 出错。primary key 不清楚时，naive merge 可能丢数据，也可能制造重复。

在真正 merge 前，让 Codex 先 profile：

- 检查 candidate keys 的 uniqueness。
- 测量 null rates 和 formatting differences。
- 归一化 casing、whitespace、address formatting 等明确问题。
- 跑 trial joins 并报告 match rates。
- 写出 safest merge strategy，再生成 final merged file。

如果需要派生 key，例如 normalized address、parcel identifier 或 location join，让 Codex 先解释 tradeoffs 和 edge cases。

## 探索和建模

Exploratory data analysis 适合隔离。一个 worktree 试 address cleanup 或 feature engineering，另一个 worktree 做 charts 或 alternate model direction。这样每个 diff 更容易 review，也避免一个长线程混合互斥想法。

```bash
git worktree add ../analysis-highway-eda -b analysis/highway-eda
git worktree add ../analysis-model-comparison -b analysis/highway-modeling
```

建模时先用可解释 baseline。要求 Codex 明确说明：

- target variable 和 feature definitions。
- controls 选择及原因。
- leakage risks 和 exclusions。
- split、evaluation 或 uncertainty estimate 的选择。
- 结果的自然语言解释。

第一版模型弱也有价值。它能告诉你问题出在 model、features、join quality，还是问题本身定义不清。

## 交付结果

按 audience 选择 artifact：

- 技术协作者：Markdown memo。
- 运营团队：spreadsheet 或 CSV。
- 格式和批注重要：`.docx` brief。
- 最终分享：PDF appendix 或 deliverable。
- 需要 URL：lightweight dashboard 或 static report site。

交付物必须包含 caveats。比如 join quality 不完美、sampling bias、model assumptions fragile，都应该写进报告，而不是藏在工作过程里。

## 可沉淀的 Skills

稳定后，把重复步骤做成 repo-local skills：

- `refresh-data`
- `merge-and-qa`
- `publish-weekly-report`

长期看，这比每次把同一段 procedural prompt 贴进线程更可靠。

## 验收清单

- raw data 没有被覆盖。
- inventory、清洗脚本、merged output 和报告都能重新生成。
- join strategy 有 match rate 和异常说明。
- 模型结论包含 controls、leakage risks 和不确定性。
- artifact 面向目标受众，而不是只给模型自己看。
- 报告明确写出 caveats 和不能下结论的地方。
