scientific-eda

科学探索性数据分析

此技能用于对科学数据开展防御性、以人为主导的探索性数据分析。Agent 不会打开文件并倾倒代码；它会先了解问题背景，帮助将范围缩小到一个首要步骤，按照用户的指示行事，并在用户要求绘制特定图表或生成表格时先询问“为什么”。

用法

当用户提供一个或多个数据文件（CSV、FASTA 或其他科学格式），并希望探索或分析这些文件时，请使用此技能。先了解背景——只有在明确问题（生物学、化学或数据科学问题）且 Agent 已明确自身角色是引导式助手后，才能加载或绘制数据。

要求

• 运行 Python 脚本需要 uv：每个脚本都使用 PEP723 内联脚本元数据，并通过 uv run script.py 运行。不要运行临时 Python 代码或原始解释器；每个脚本都应声明并管理自己的依赖项。
• 通过脚本块中声明的依赖项读取相关数据格式的能力（pandas、BioPython 等）。

功能

1. 先了解背景 – 在处理数据前，了解并记录问题背景（问题是什么、属于哪个领域）。
2. 确定一个首要步骤 – 帮助用户将范围缩小到一个首要图表或一项首要汇总，而不是一次性给出大量代码或图表。
3. 由人引导执行 – 按照用户的指示决定下一步；用户说“绘制这张图”或“给我那张表”时，先询问原因，再执行。
4. 会话布局 – 每次分析都是一个会话：在 analysis/ 下创建一个带有描述性名称和开始日期/时间的文件夹，其中包含 journal.md、plots/ 和 scripts/。
5. 日志 – 每个会话都使用仅追加的 journal.md：记录数据形状（列、行、结构）、已完成的操作和发现。
6. 脚本和图表 – 在 scripts/ 中存放临时脚本（PEP723、uv run）；图表保存为 WebP（而非 PNG），以减小文件体积；所有内容都放在会话文件夹下。
7. 建议下一步 – 每次操作后，建议最合乎逻辑的下一步，并让用户决定。

工作方式

阶段 1：了解背景（处理数据前）

• 不要打开数据文件后就开始编写代码或绘图。
• 询问或确认：问题背景——生物学、化学或数据科学问题；用户希望了解或决定什么；以及任何限制条件（例如特定变量、子集）。
• 将这些信息记录到会话的 journal.md 中（参见阶段 3）。只有在背景已记录并达成一致后，才能继续检查数据形状并规划首要步骤。

阶段 2：开始数据分析会话

• 在 analysis/（或项目约定的基目录）下创建一个会话文件夹。会话开始时，将其命名为描述性名称 + ISO 日期时间，例如 analysis/2025-02-05T14-30-00-protein-binding/。
• 每个会话文件夹的标准布局：
  • journal.md – 本次会话仅追加的持续日志
  • plots/ – 所有图表（matplotlib 仅限 WebP）
  • scripts/ – 用于加载数据、汇总数据或绘图的临时脚本
• 会话文件夹名称必须包含日期/时间和简短的描述性标识，以便排序和识别会话。标准目录结构请参见 references/session-structure.md。

阶段 3：日志（每个会话仅追加）

• 每次实质性操作前，先阅读会话的 journal.md。
• 在日志中记录：
  • 数据形状：加载或检查数据后，记下各列（以及相关类型）、行数和任何结构信息（例如多重索引、FASTA 条目数、关键字段）。一旦了解数据形状，就立即记录；每次重大数据处理后也要记录。
  • 已完成的操作（使用了哪个脚本、生成了哪张图表、进行了哪项汇总）
  • 发现、意外情况和后续想法
• 每条日志都使用时间戳（例如 ISO 格式或简写格式 YYYY-MM-DD HH:MM）。
• 使用 [SHAPE]、[PLOT]、[FINDING]、[NEXT] 等标签，让日志易于浏览。日志是会话的记忆；请据此建议下一步。

第 4 阶段：了解数据形态，然后迈出第一步

• 数据形态：在提出或绘制图表之前，确保 Agent（和用户）了解有哪些列/字段、多少行/记录，以及任何关键结构。将这些信息记录在 journal.md 的 [SHAPE] 条目下。
• 第一个图表（或表格）：帮助用户选择一个初步可视化或摘要（例如，一个分布图、一张概览表）。不要一次生成多个图表；先就这一步达成共识，然后再执行。

第 5 阶段：由人引导执行并“询问原因”

• 遵循指示：用户可能会要求绘制特定图表、生成表格或筛选数据。只有在明确需求后才执行。
• 执行前询问原因：当用户说“绘制这个图表”或“给我那个表格”时，先简短询问原因（例如，它支持什么决策或问题）。然后运行脚本，并将结果记录在日志中。
• 每次操作之后：提出最合乎逻辑的下一步（一步），并让用户确认或调整方向。不要自动执行冗长的流水线。

第 6 阶段：脚本（一次性、PEP723、uv run）

• 本次 EDA 中使用的所有 Python 代码都放在会话 scripts/ 文件夹下的脚本中。
• 每个脚本顶部都要有 PEP723 内联脚本元数据（# /// script、requires-python、dependencies、# ///）。使用 uv run script.py 运行（或在 CWD = 会话文件夹时使用 uv run scripts/script_name.py）。不要运行原始的 python 命令，也不要在 REPL 中粘贴代码；脚本是执行单位，并负责管理自己的环境。
• 脚本是一次性的：它们用于本次会话的图表和摘要，不用于生产环境。脚本中的路径相对于会话文件夹（例如 ../data/file.csv，或按约定使用其他路径）。

第 7 阶段：图表（matplotlib 仅使用 WebP）

• 将所有 matplotlib（及类似工具）绘制的图表保存为 WebP，而不是 PNG，以缩小图像文件。示例：fig.savefig("plots/overview.webp", format="webp")。
• 将图表文件写入会话的 plots/ 目录。使用描述性文件名（例如 distribution_response.webp、first_ten_records.webp）。
• 在记录所做操作时，在日志中引用这些图表。

在 Marimo notebook 中进行 EDA 时

当用户在 Marimo notebook 中（而非 scripts/ 中的脚本）执行此 EDA 工作流时，仍须遵循上述阶段（先了解上下文、一次一步、记录日志、询问原因）。此外：

• 代码前后添加 Markdown：为 notebook 中的每个代码单元格添加前后 Markdown 单元格，说明代码的作用以及结果的含义。前置 Markdown 说明目的；后置 Markdown 总结或解读输出。

请参阅 references/marimo-notebook-eda.md，了解规范约定。

防护原则

1. 先了解上下文，再看数据——在问题背景已明确并记录到会话日志之前，不要打开或分析数据。
2. 第一步只做一件事——提出并确认一个初步图表或摘要；不要一次生成大段代码或多个图表。
3. 询问原因——用户请求特定图表或表格时，执行前先询问原因（它要解决什么问题或支持什么决策）。
4. 用日志保存记忆——阅读并追加会话的 journal.md；记录数据形态和发现，让后续步骤有据可依。
5. 仅通过 uv run 运行脚本——不使用临时 Python 代码；每个脚本都须包含 PEP723 元数据，并通过 uv run script.py 运行。
6. 图表使用 WebP——matplotlib（及类似工具）的输出使用 WebP；默认不要保存为 PNG。
7. 提出建议，不要擅自假定——每次操作后提出一个合乎逻辑的下一步，并等待用户确认或调整方向。
8. Marimo notebook——在 Marimo notebook 中进行 EDA 时，为每个代码单元格添加前后 Markdown 单元格，以说明目的和结果（参阅 references/marimo-notebook-eda.md）。