explore-ml-data

探索机器学习数据

针对项目开展一次探索性数据分析：提供一个用户可以打开的笔记本、HTML 报告、一份嵌入这些报告的简短 data_analysis.md，以及 JOURNAL 索引行。

面向人的文案

详情：setup-workspace references/human_facing_prose.md。 笔记本 Markdown、data_analysis.md、JOURNAL 文本和 # 注释描述的是此数据集，而非技能框架、CLI 或生成输出的命令。 问题、回复和收尾叙述使用相同的数据科学语言，而非技能 ID、 G-* 名称或封装 CLI。 `` 是站点标记。编写提示保留在此技能中。 style 仅用于 ruff。

产物

路径	受众
原始数据（任意位置）	用户所有，只读
data_analysis/data_analysis.py	面向人的笔记本——TableReport + ML 差距单元格
data_analysis/data_analysis_<slug>.html	面向人——TableReport 页面，每个系列一个
data_analysis/*.png	面向人——用于阐述影响的图表，绝不用于快速浏览
data_analysis/<slug>.html	面向人——Plotly（或其他）HTML，在影响分析中使用 iframe
data_analysis/data_analysis.md	面向人 + 后续建模——TableReport iframe、影响分析
scratch/data_analysis/materialize.py	Agent——唯一运行入口；被 gitignore 忽略
scratch/data_analysis/<slug>.json	Agent——每个系列对应一个 TableReport.json()；被 gitignore 忽略
scratch/data_analysis/extras.json	Agent——tables[]、targets、泄漏信息、png 和 html 路径
JOURNAL § 数据理解	索引：状态、2–4 行摘要、链接

TableReport 负责数据类型、缺失情况、单变量分布、基数和排名靠前的成对关联。 额外单元格涵盖重复项、每个目标的分布、特征与目标的关系，以及 潜在泄漏。其他目标不是特征。不要在额外单元格中重复 TableReport 的内容。

详情：references/cell_anatomy.md。额外分析配方： references/extra_analyses.md。

后续步骤指引

你来这里是为了……	→ 下一步
首次 EDA（分流或自由文本）	→ 编写 md；然后展示五选项续接面板
选择续接方式	→ 预定义选项、查询、自动探索或描述图表；此时不要结束回合
结束此阶段	→ 填写 / site / git end-turn / 若已安装则使用 triage-ml-task
EDA 已完成，但对方法有疑问	→ 跳过 G-DATA-ANALYSIS；继续探索 § 自动探索（明确提出的问题会跳过预设调查）
数据源已变更或“也绘制 X”	→ 覆盖 data_analysis/data_analysis.*，更新 JOURNAL

停止条件

• 先完成设置。 运行 python -m skore_skills status。如果 status.setup.pending 不为空，且 status.skills.setup-ml-project 为 true，则加载 setup-ml-project 并停止。不要启动此技能。它返回后再继续。本轮不要再次加载它。如果未安装该技能，用一行列出待处理项 并停止。不要臆造 git init、脚手架或 env init。 如果 status.setup.env 或 status.setup.workspace 为 declined，用一行说明后停止。若 git 或 editable 被拒绝，则不要再次询问；继续。不要手动定义 PROJECT_ROOT，也不要在工作区设置待处理时写入根目录下的 JOURNAL.md。
• 原始数据只读。 绝不清理、改写或重新保存用户的文件。绝不要让用户删除某列或文件（“删除它”）。数据泄漏应留在开放问题 / measure 看板中。清理工作属于 build-ml-pipeline。
• 交付内容放在 data_analysis/ 下。 原始数据的加载位置可以是任何地方。
• 每个询问都要带上上下文。 在此技能中使用任何 AskUserQuestion 之前，用 2–4 行说明答案授权的操作、依据的事实（在行内明确写出，例如文件名、候选列、建议的系列 slug），以及每个选项的作用。文件链接只能作为补充，不能替代上下文。
• G-DATA-ANALYSIS 运行 | 跳过。 AskUserQuestion。“快速进行”不等于跳过。若跳过 → python -m skore_skills eda stamp --status skipped 并停止。不要填写日期。 只有当 data_analysis/data_analysis.md 不存在时，跳过才有效（status.data_analysis 为 missing 或 skipped）。若状态为 present，不要写入 skipped。说明已写入的分析会保留，并提供重新运行探索（覆盖 data_analysis/data_analysis.*）或保留现有内容的选项。用户接受重新运行之前，不要覆盖。即使 EDA 已完成，只要用户提出了具体的方法论疑虑，此门槛仍应跳过。跳过时不要运行 site build。在 build-ml-pipeline 中，Evaluate 之前仍要运行未拟合快照构建。
• 在 data_analysis/data_analysis.py 之前处理 G-TABULAR。 status.policy.tabular；否则先运行 choose-python-library（推荐 pandas），再为该库以及 skrub、 matplotlib 和 seaborn 运行 add-python-package。不要静默采用默认值。安装该 skrub 时出现的 Graphviz 修复诊断不会导致放弃此分析。用一行引用该诊断并继续。build-ml-pipeline 中的未拟合快照需要可渲染的图。若 G-TABULAR、 目标或系列尚未得到答复，在询问后停止 — 不要创建默认路径笔记本，哪怕称作“假设使用 pandas 的交付物 A”。除非用户选择的额外项需要，否则不要安装 sklearn / skore / pytest。
• 目标。 当列含义明确时，根据 JOURNAL Status / 用户提示推断目标，包括所有命名的输出。否则使用 AskUserQuestion allow_multiple（列名加上“暂时没有目标”），然后停止 — 暂时不要编写笔记本。“暂时没有目标”不可与其他选项同时选择。不要将特征与目标的区别 / 数据泄漏列为始终需要执行的后续步骤。不同取值很多的数值列属于回归。标签较少或标签为非数值的列属于分类。一列 → 只添加对应的目标代码片段。两列或更多回归列属于一个多输出回归：追加一次 templates/target_multioutput_regression.py。多个分类列，或分类与回归混合，不属于 skore 可报告的联合模型：记录每列及其任务，不要追加该代码片段。在选择“暂时没有目标”或拒绝后 → TARGETS=[]。只使用 TableReport + 重复项。不要持久化策略键。
• 不进行训练 / 测试集拆分。 之后由建模决策锁定来决定此选择。EDA 期间不要拆分。如果文件已经分别是训练表和测试表，在摘要中写出两者，不要将它们合并。探索不负责选择评估方式。 数据泄漏单元格是对包含所有目标的原始系列进行的定性标记。其他系列只使用 templates/family.py（TableReport + 重复项）——不要在不包含目标的系列上添加数据泄漏 / 目标 / 双变量单元格。不要持久化合并后的建模表。
• 先确定系列，再编写笔记本。 数据文件多于一个 → 使用 AskUserQuestion 询问分组（不推荐任何选项）：使用建议的分组 / 分别分析每个文件 / 我会描述分组方式。根据扩展名、名称模式或表头 / 模式预览提出聚类建议；使用通用 slug（family_a）。询问时提出这些 slug 不等于臆造系列；只有在得到答复后编写系列才算臆造。一个文件 → 跳过此询问。
• 本轮对使用到的符号执行 api get（缓存命中也算）。 TableReport.json() 的键可能变化 — 使用 .get(...)。
• 只创建一个 data_analysis/data_analysis.py。 对每个已确认的系列（若用户选择按文件处理，则对每个文件）重复 TableReport 单元格。重新运行时原地覆盖。默认笔记本只包含这些模板（以及匹配的目标代码片段）。不要添加额外的直方图、sns.heatmap / 关联矩阵、唯一值比例（nunique()/n）、列字典或 report.json() 单元格。重复项单元格只打印重复项数量，不打印唯一值百分比，也不打印 nunique()/n。数据泄漏内容应使用模板表格，而不是注释。一个目标：在 templates/target_regression.py / target_classification.py 中使用 seaborn displot（描述统计 + 一张目标图），并使用一个分面 relplot → bivariate_grid.png。多个回归目标：只使用一次 templates/target_multioutput_regression.py （target_distributions.png、bivariate_targets.png）。不要在其旁边复制单目标代码片段，也不要在 TableReport 旁边臆造另一张目标直方图。最后一个表达式为 g。默认路径中不要 import matplotlib.pyplot。
• 不要设计模型。 只在 data_analysis.md 中说明影响。
• 不要将 data_analysis/ 加入 gitignore。若用户提出要求，通过 setup-git 忽略特定的原始数据模式（默认：不忽略）。

预检

- [ ] Setup: pending empty | load setup-ml-project and stop
- [ ] Detect: status.data_analysis present|skipped|missing
- [ ] G-DATA-ANALYSIS: run | skip when the analysis file is absent (skip → JOURNAL only, STOP). present → keep or re-run; never write skipped
- [ ] G-TABULAR + add frame lib + skrub + matplotlib + seaborn
- [ ] Targets: inferred | AskUserQuestion | none
- [ ] Families: one file | AskUserQuestion grouping
- [ ] Load plot-ml-figure if installed; place
      data_analysis/data_analysis.py from the template (edit to
      the live path); do not execute it
- [ ] scratch/data_analysis/materialize.py once → HTML, figures,
      <slug>.json per family, extras.json
- [ ] notebook fill when policy.notebooks is true
- [ ] Author data_analysis.md + JOURNAL
- [ ] Preview `site build` if `policy.site` (skip on G-DATA-ANALYSIS skip)
- [ ] AskUserQuestion five options, including Close (skip if user
      already closed the turn)

勾选，然后运行对应步骤。附上证据重新输出检查清单。 只有完成 Close 后才能结束本轮。

执行前

解决 G-DATA-ANALYSIS、G-TABULAR、目标和族之后，在首次写入前立即输出 1–3 句自然语言。说明这是本地计算：它会分析已确认的完整表族，运行适用的重复项／目标／双变量／泄漏分析，并写入 data_analysis/ HTML／图表以及 scratch/data_analysis/ JSON 事实。指出数据范围和报告路径；不要用预检内容来解释。

根据事实描述成本，不要猜测。TableReport 和所请求的图表会随表大小和族的数量而扩展；除非已有测量得到的耗时，否则说明耗时取决于这些输入，不要虚构分钟数。此预览只输出一次，不要在每次编辑前重复；仅当新选择的额外项实质性改变工作内容时才更新。

自动探索／方法论讨论属于 LLM 研究，不是模型拟合或测试：说明它将基于记录的 EDA 进行推理，可能会写入一份临时研究笔记，并会在本地分析前停在测量选择板。

如果有强制关卡尚未完成，可以预览可能进行的工作，但不要写入或执行笔记本。

流程（运行路径）

1. 首先解析 TARGETS，并为每一列确定一个任务（classification | regression）。空列表表示没有目标。两个或更多回归列表示多输出回归。解析 各数据族（见上面的停止条件）。如果适用，复制 templates/data_analysis.py，然后编辑 ——不要粘贴未使用的分支。若存在目标，第一个数据族必须包含所有目标；替换 <pkg>、<LOAD_RAW_DATA>（将该数据族的分片载入内存并拼接；可选 _source_file）和 <slug>（Python 标识符）。每个后续数据族对应 → templates/family.py（<OTHER_SLUG>、 <LOAD_OTHER>）。一个目标 → 追加 templates/target_regression.py 或 templates/target_classification.py，并在第一个数据族的加载单元格中设置 TARGET。两个或更多回归目标 → 追加一次 templates/target_multioutput_regression.py，并将 TARGETS 设置为该列表。没有目标、多个分类列或混合任务 → 不追加这些代码片段，也不进行 TARGET / TARGETS 赋值。某个数据族有日期时间列 → 为该数据族添加 templates/datetime.py（除非恰好有一个数值型目标，否则删除 relplot 单元格）。两个数据族共享列名 → 使用 templates/drift.py 和 <OTHER_FRAME>。默认流程中，模式互不相交时不做漂移分析。此处不要追加连接覆盖率单元格。生成的 Notebook 不得包含 if TARGET、if TASK、 OTHER = None、空的日期时间循环或“skip this cell”。 如果已安装 plot-ml-figure，在编写图表单元格之前加载它（包括首次编写）。Markdown 内容应围绕本次 分析。写入后运行 python -m skore_skills style。不要执行此文件。

2. 将 templates/materialize.py 复制到 scratch/data_analysis/materialize.py。替换 <pkg>、 <TARGETS>、<TASKS> 和 <ANALYSIS> 块：加载内容、TableReport.write_html 调用以及图表或 HTML 保存内容，均应与人工编写的文件一致。<TARGETS> 是列名列表（没有目标时为 []）。<TASKS> 是对应的 classification | regression 并行列表，也包括没有联合代码片段的列。每个数据族只加载一次。 将 FAMILIES 绑定为 (slug, raw)，并将 FRAME 绑定为包含所有目标的 pandas 数据框。保留文件末尾部分。运行该文件一次。 它会写入 TableReport HTML、图表、<slug>.json 和 extras.json。不要执行 data_analysis/data_analysis.py。不要对它运行 notebook convert，也不要运行 cells run。读取 <slug>.json 和 extras.json。

3. 读取 status.policy.notebooks 和 status.policy.site。 当 notebooks 为 true 时，运行 python -m skore_skills notebook fill data_analysis/data_analysis.py，仅当 site 也为 true 时才添加 --html。fill 不会执行该文件。它需要 jupytext 和 nbformat，而不需要 nbclient、ipywidgets 或 IPython。当 notebooks 为 null 或 false 时，不要更改策略，也不要 fill。materialize.py 仍然是唯一要运行的文件。

4. 根据 templates/data_analysis.md 编写 data_analysis/data_analysis.md：概览（每个数据族一个 iframe，除此之外不包含其他内容）、建模影响（包括特征工程候选项）、未决问题。报告和图表应嵌入，而不是链接；![](<name>.png) 或 HTML iframe（<iframe src="<slug>.html" …>）应放在其支持的建模影响旁边，不能放在概览中。概览只能包含 TableReport。每个 extras["pngs"] 和 extras["htmls"] 中的路径都要嵌入，并为每个路径附上一句引用这些 JSON 文件（或 Notebook 摘要表格）中数字的说明。不要保存没有对应说明的图表。 论断须以两个 JSON 文件和 HTML 为依据。不要编造列名。

5. JOURNAL § Data understanding 表格：运行 python -m skore_skills eda stamp --status done 填写 Status 单元格。不要手动输入日期。撰写简短摘要（数据形状、每个目标的类别分布或偏斜程度，以及一到两个会影响建模的发现） 并报告 [data_analysis/data_analysis.md](../data_analysis/data_analysis.md)。 跳过路径：仅运行 eda stamp --status skipped。跳过时不要 fill，也不要运行 git end-turn。

6. 继续工作看板——除非用户已经结束本轮（“EDA is done”、“close the turn”）：如果 policy.site 为 true 且已安装 export-ml-site，首先运行 python -m skore_skills site build --if-stale。否则用一行说明跳过。如果 site build 报错并提示 mkdocs-material is required，则为 mkdocs-material 加载 add-python-package （agent），然后再构建一次。不要运行 pixi add / uv add。 如果缺少该技能，或重试仍失败，用一行说明错误。说明构建错误；不要因此导致关卡失败。 如果构建已运行或报告网站为最新状态，请说明网站已更新，并提示在浏览器中打开 report.html。不要提及 data_analysis.md 或 html/data_analysis.html。此预览期间不要运行 notebook fill 或 git end-turn。然后通过 AskUserQuestion 询问一个选项。不推荐或预先选定任何选项。首次 md 之后始终要询问（包括分流将你引导到此处时）。不要在此看板中说“extra-analyses”或“standard extra analysis”。

   Label	副标题
   选择其他预定义选项	仅列出适用的项目：交互 / pairplot、PCA、假设检验、子群、时间序列、文本或地理数据、连接键 / 覆盖范围（2 个以上类别）
   提供查询以扩展探索	描述要添加到笔记本的分析（表格、检验或图表）
   自动探索与数据和问题相关的内容	针对我们正在探索的问题和数据进行深入研究
   描述图表	指定图表类型，我会为其添加单元格
   关闭	结束此阶段。不要添加其他分析。

   关闭 → 结束本轮对话（面向用户的关闭）。关闭时不要重写 data_analysis.md。其他四个选项会进入 继续探索，且不会针对相同选项再次询问此面板。重复项 / 目标 / 泄漏应保留在建模 影响中，而不应只放在开放问题里。

如果原始提示词已指定其他项目（例如 PCA），请在步骤 1 中加入 这些单元格，不要再次询问该项目。

导入失败 → 使用 add-python-package，不要绕过问题。

刷新（已为 done，用户要求更多图表）：编辑 人工维护的文件和 <ANALYSIS> 块，运行一次 materialize.py， 笔记本启用后再填写，然后执行步骤 4–6。不要再次询问 G-DATA-ANALYSIS。

当 status.data_analysis 存在时提出方法论疑虑 （泄漏 /“研究此问题”）：跳过 G-DATA-ANALYSIS；不要 覆盖笔记本；转到继续探索 § 自动探索，并针对该明确提出的疑虑进行探索（跳过预设的 额外分析问卷）。

如果已安装 plot-ml-figure，务必在编写或重写图表单元格前加载它。模板并不意味着可以跳过绘图工作器。缺少技能 → 用一行说明跳过，并仍然遵循该流程（统计图表用 seaborn，简单图表用 pandas，最后才用 matplotlib）。笔记本单元格中绝不要使用 plt.close：保存 PNG 后，让图表 / 网格保留为单元格输出。

继续探索

无需单独导出，也不要执行 git end-turn。编辑人工文件时也会编辑 <ANALYSIS>，然后运行一次 materialize.py，启用 notebooks 时再运行 fill。md 重写之前，不要再次构建站点。本轮任何地方（聊天、检查清单或看板）都不要说“extra-analyses”或“standard extra analysis”。只能将文件 references/extra_analyses.md 作为路径提及。 已询问过继续看板。处理已选标签。不要询问保留还是关闭，也不要针对本次选择重复看板。

1. 预定义选项 — 配方文件 references/extra_analyses.md（仅路径；聊天中不要说“extra-analyses”）。它自己的 allow_multiple 看板。问题的最后一行必须严格为：Select each one you want. 该行之后不要写任何内容。在绘图单元格之前，如果已安装，则加载 plot-ml-figure。

2. 查询 — 等待用户提出分析请求。追加单元格（如果要绘图，则加载 plot-ml-figure）。不要使用预设的研究调查。之后执行刷新步骤。

3. 自动探索 — 如果已安装，则加载 research-ml-practice，阶段设为 data_analysis，并使用下方的预设调查关注点。缺少技能时 → 用一行说明跳过，并重新询问五选项看板，不要再次执行 site build。不要询问初始信息。将 JOURNAL、data_analysis.md（含影响和未决问题）以及 scratch/data_analysis/extras.json 作为上下文传入。工作进程在搜索前会抽象出问题类别（不包含数据集专有名称）。预设问题：

   鉴于 JOURNAL 中的问题类型（领域、任务、约束）以及 EDA 中已观察到的结构类型（而非数据集的专有名称），对于这样的原始表，还有哪些额外测量值得进行？

   阅读 scratch/research/survey-<slug>.md。在聊天中总结，不要直接贴出笔记。如果工具未运行，就用两句话说明具名关注点（针对泄漏：来源 / 评分时是否可用），并提供 measure 看板；不要声称已读取临时文件。不要建议删除原始列。通过 AskUserQuestion，仅针对有来源且尚未出现在笔记本中的 measure 类额外分析启用 allow_multiple。没有选项默认选中。问题的最后一行必须严格为：Select each one you want. 该行结束消息：之后不要添加检查清单。 如果存在配方，则映射到 extra_analyses；否则使用自定义单元格。declare / evaluate / confirm 不要放到此看板上 → 将未决问题作为建议，而非发现。除非调查笔记列出了带来源的未决问题，否则不要将其复制到看板上。

   用户点名的方法论关注点（leakage / “research this”）会跳过预设调查：将该关注点作为深入研究内容传入，然后提供相同的 measure 看板。如果工具未运行，则按上述方式总结；不要建议删除原始列。

4. 描述绘图 — 如果已安装，则加载 plot-ml-figure；追加单元格。

5. 会更改 .py 的选择：设置 style，编辑 <ANALYSIS> 块使其保持一致，运行一次 materialize.py，然后在 notebooks 为 true 时运行 notebook fill（仅当 site 也为 true 时才使用 --html）。根据 JSON/PNG/HTML 重写 data_analysis.md（影响应基于结果）。然后，如果 policy.site 为真，则预览 site build 并重新询问五选项看板（执行运行路径第 6 步）。不要编造领域检查清单。

分派

由 triage-ml-task 调用（explore-the-data 意图，或建模请求中的 explore-first，而 data_analysis 缺失时），也由用户自由文本调用。

调用：add-python-package、api get、choose-python-library / G-TABULAR 的技术栈；如果已安装，且用户希望进行额外分析研究或关注某个具名方法论， 则调用 research-ml-practice；如果已安装，则在任何图表单元格之前调用 plot-ml-figure（默认笔记本、额外内容、自由文本、research-measure）； 在 data_analysis.py 之后调用 style。

需要软件包？如果已安装，加载 add-python-package；否则指出软件包名称并停止。 此处不要执行 env add。

回合结束

仅在 Close 之后（或用户已结束回合时）运行此区块。继续探索时绝不会到达此处。 不要在此区块中重写 data_analysis.md。

面向用户的结束内容

面向用户的消息应简短叙述并附上链接。它不是 Pre-flight，不是 Markdown 内容倾倒， 也不能只有 JOURNAL 表格单元格。不要在该消息中提及 site build、--if-stale 或其他包装命令。

1. 先叙述 — 用 2–6 句话概述此阶段的发现，并以建模启示 / JSON 事实为依据 （形状、目标、会影响建模的泄漏或重复项）。不要编造列名。不要粘贴 data_analysis.md。
2. 打开以下内容 — 如果运行了 site build 或报告称网站已是最新，请说明网站已更新， 并链接 [report.html](<workspace>/report.html)，供用户在浏览器中打开。不要提及 Markdown 文件或 html/data_analysis.html。此阶段不提供 Skore 定位符。 如果未构建网站，不要声称网站已更新，也不要提及 Markdown 文件。
3. 其次是规范化标记 — EDA 不适用（没有 G-REPORT-LOCATOR / G-AUDIT-FINDING）。

此技能负责结束流程。继续探索时只需用 1–2 句话概述（如果运行了构建：说明网站已更新， 并提示在浏览器中打开 report.html）；绝不会进入 fill / git end-turn。

如果 policy.notebooks 为 true，export-ml-notebook 已安装，且本次运行尚未写入最新笔记本， 则运行 python -m skore_skills notebook fill data_analysis/data_analysis.py，如果 policy.site 也为 true，则添加 --html。 由运行路径步骤 3 生成的笔记本已是最新：不要仅仅因为用户选择了 Close 就再次填充。 如果产物已由此人工文件生成，则不要重新运行 materialize.py。否则用一行说明跳过。 缺少 jupytext / nbformat / nbconvert → 用一行说明跳过并提及 add-python-package； 不要导致回合失败，也不要运行 pixi add。

然后，如果 policy.site 为 true 且 export-ml-site 已安装，则在持久化文件写入磁盘后运行 python -m skore_skills site build --if-stale。否则用一行说明跳过。如果 site build 因 mkdocs-material is required 出错，则为 mkdocs-material（agent）加载 add-python-package，然后再构建一次。不要运行 pixi add / uv add。如果缺少该技能， 或重试仍失败，则用一行说明错误。指出构建错误；不要导致数据分析回合失败。运行构建后， 说明网站已更新，并提及 report.html（在浏览器中打开）。不要提及 Markdown 文件或 html/data_analysis.html。

python -m skore_skills git end-turn --stage data_analysis。如果 JSON action 为 invoke，仅当 status.skills.persist-ml-git 为 true 时加载 persist-ml-git，然后停止； 该技能会返回 triage。如果缺少 persist，则指出待处理的 staged 路径并停止。否则仅当 status.skills.triage-ml-task 为 true 时加载 triage-ml-task；否则停止。不要执行 git commit。