【人工智能驱动的电催化研究-07】CSV文件、路径与可追溯记录

前六节中,我们已经能使用变量、列表、字典、循环和函数处理记录。但输入仍主要写在代码里。

实际科研中,电化学工作站会导出文件,文献数据也常整理成表格。因此,本节要把前面的知识连接起来:

从文件读取数据,按照明确规则处理,再把结果保存为新的文件。

一、本节学习目标

学完后,你应能够:

  1. ++理解CSV的表头、记录、分隔符和引号。++
  2. ++正确处理中文编码和文件换行。++
  3. ++区分工作目录与脚本所在位置。++
  4. ++将CSV中的数字文字明确转换成数值。++
  5. ++保留未知和问题原因,不用零掩盖缺失。++
  6. ++导出计算结果与完整审计表。++
  7. ++记录输入文件、脚本、环境和处理结果之间的关系。++

本节使用Python标准库,不需要安装额外软件包。NumPy数组和科研绘图分别安排在第八、九节。

二、为什么把数据从代码中移到文件?

上一节可以这样提供输入:

复制代码
j_a = current_density_mA_cm2(-12.5, 0.50)

样品较少时,这样写很直观。但样品增加后,反复修改代码里的数字容易带来几个问题:

  • 不清楚数字来自哪份原始记录。
  • 修改输入时误改计算步骤。
  • 无法区分原始数据和修订数据。
  • 其他人难以重新执行相同分析。

因此,我们把职责分开:

复制代码
输入文件:保存记录
Python代码:执行检查和计算
输出文件:保存派生结果
运行记录:说明这些文件怎样关联

这种组织方式适用于四条科研主线:催化剂性能表、界面条件记录、动力学时间序列,以及反应器工况和结果。

三、CSV是什么?

CSV通常指逗号分隔值文件,是一种组织表格信息的文本格式。

例如:

复制代码
record_id,current_mA,area_cm2
A_run01,-12.5,0.50
B_run01,-20.0,0.50

第一行是表头,给出字段名称。

后续每条记录按照相同顺序保存数据:

record_id current_mA area_cm2
A_run01 −12.5 0.50
B_run01 −20.0 0.50

CSV可以用文本编辑器查看,也可以用表格软件打开。

但它没有Excel工作簿中的完整格式、公式计算和多工作表结构。字段名中的`mA`、`cm2`也是人为约定,CSV不会自动理解物理单位。

四、引号为什么重要?

假设电解液说明写成:

复制代码
HClO4, 0.10 mol/L

这段文字内部已经包含一个逗号。如果直接按逗号拆分,就可能错误地变成两个字段。

CSV可以用双引号明确它是一个单元格:

复制代码
record_id,electrolyte
A_run01,"HClO4, 0.10 mol/L"

因此,不应随意用:

复制代码
line.split(",")

代替正规的CSV读取。

引号内还可能包含换行,所以文件的物理行数也不一定等于数据记录数。Python的`csv`模块可以处理这些规则。官方CSV文档

本课的`source_record`表示表头后第几条被读取的数据记录,不把它称为文件的绝对行号。

五、编码与换行:怎样避免中文读取错误?

文件保存的是字节,编码规定这些字节怎样解释成文字。

本节采用UTF-8,并使用:

复制代码
encoding="utf-8-sig"

它可以读取带有或不带UTF-8文件头标记BOM的UTF-8文件。

这里需要区分:

  • 文件编码决定CSV内容怎样读取。
  • 终端编码决定输出文字怎样显示或被其他程序接收。

两者不是同一件事。

utf-8-sig也不是自动识别所有编码的工具。如果来源文件实际采用其他编码,应先核查,不能靠反复替换中文"修复"数据。

打开CSV时还会使用:

复制代码
newline=""

它让CSV模块处理换行细节。

文件通常放在`with`语句中打开,离开缩进块后会自动关闭:

复制代码
with input_path.open(
    "r",
    encoding="utf-8-sig",
    newline="",
) as file:
    ...

这里:

  • "r"表示读取。
  • "w"表示写入,并覆盖已有目标文件。
  • as file给打开的文件对象一个名字。

因此,写入之前必须确认目标是派生输出,而不是原始文件。

六、路径:让程序稳定找到输入

第二节已经区分过:

工作目录:程序此刻解析相对路径时使用的位置。

脚本位置:`.py`文件实际保存的位置。

它们可以不同。

本课结构为:

复制代码
Day07
├─ data
│  └─ Day07_raw_records.csv
├─ code
│  └─ Day07_csv_workflow.py
├─ outputs
└─ figures

代码通过脚本位置构建输入路径:

复制代码
from pathlib import Path

course_dir = Path(__file__).resolve().parents[1]
input_path = course_dir / "data" / "Day07_raw_records.csv"

逐项理解:

  • __file__:当前脚本的位置。
  • resolve():得到完整路径。
  • parents[1]:取上两级,在本结构中得到`Day07`。
  • Path对象之间的`/`:拼接路径,不是数值除法。

因此,即使从另一个工作目录启动脚本,仍能找到同一份随课数据。官方路径文档

七、读到的数字为什么仍然是文字?

使用`DictReader`可以把每条记录读成字典:

复制代码
with input_path.open(
    "r",
    encoding="utf-8-sig",
    newline="",
) as file:
    reader = csv.DictReader(file)

    for row in reader:
        print(row["current_mA"])

表头提供键名,因此可以按字段读取。

但是,默认读取时:

复制代码
-12.5

对应的仍然是字符串:

复制代码
"-12.5"

不能因为屏幕看起来像数字,就假定它已经是数值。

需要明确转换:

复制代码
current_mA = float(row["current_mA"])

转换前还要检查空白,转换后还要检查有限性和物理范围。

空单元格通常读成`"";一条记录缺少尾部单元格时,某些字段可能成为None`。多出的单元格也需要检查,不能忽略结构异常继续计算。

八、本课输入:六条带条件的教学记录

本课提供了六条带条件的教学记录。

记录编号 样品编号 反应 电位/mV 参考电极 电解液 温度/K 电流/mA 面积/cm² 面积基准 iR补偿 数据来源
A_run01 demo_A HER −180.0 RHE 0.10 mol/L HClO₄ 298.15 −12.5 0.50 几何面积 未应用 教学设定,非实测
B_run01 demo_B HER −180.0 RHE 0.10 mol/L HClO₄ 298.15 −20.0 0.50 几何面积 未应用 教学设定,非实测
C_run01 demo_C HER −180.0 RHE 0.10 mol/L HClO₄ 298.15 −10.0 0.25 几何面积 未应用 教学设定,非实测
D_run01 demo_D HER −180.0 RHE 0.10 mol/L HClO₄ 298.15 −12.5 0.00 几何面积 未应用 教学故障测试,非实测
E_run01 demo_E HER −180.0 RHE 0.10 mol/L HClO₄ 298.15 未填写 0.50 几何面积 未应用 教学故障测试,非实测
F_run01 demo_F HER −180.0 未填写 0.10 mol/L HClO₄ 298.15 −12.5 0.50 几何面积 未应用 教学故障测试,非实测

六条记录全部是教学设定或故障样例,不是实验测量。

前三条沿用前课:

记录 电流/mA 几何面积/cm² 特殊情况 预期处理
A −12.5 0.50 无 计算
B −20.0 0.50 无 计算
C −10.0 0.25 无 计算
D −12.5 0 面积为零 暂缓
E 空白 0.50 电流缺失 暂缓
F −12.5 0.50 参考电极空白 暂缓

教学条件沿用HER、−180 mV vs RHE、0.10 mol/L HClO₄、298.15 K、几何面积、未应用iR补偿;F故意不提供参考电极。

文件还保存记录编号、样品编号、反应和来源。保存为CSV并不会改变这些数值的教学身份。

九、计算与验证要求

几何平均电流密度为:

\ j_{\\mathrm{geo}}=\\frac{I}{A_{\\mathrm{geo}}} \\

其中:

  • \(I\):电流,单位mA。
  • \(A_{\mathrm{geo}}\):几何面积,单位cm²,且必须为正。
  • \(j_{\mathrm{geo}}\):平均电流密度,单位mA/cm²。

手算得到:

\ j_A=-12.5/0.50=-25\\ \\mathrm{mA/cm\^2} \\\ j_B=-20.0/0.50=-40\\ \\mathrm{mA/cm\^2} \\\ j_C=-10.0/0.25=-40\\ \\mathrm{mA/cm\^2} \\

还应检查:

\ j_{\\mathrm{geo}}A_{\\mathrm{geo}}=I \\

例如:

\ -25\\times0.50=-12.5\\ \\mathrm{mA} \\

记录数量应满足:

\ 6=3\\text{条通过}+3\\text{条暂缓} \\

这个比例不是模型准确率,只表示当前教学规则下的处理结果。

十、完整、可运行的代码

下面代码使用随课CSV,包含读取、检查、计算、导出和基本运行记录。

复制代码
import csv
import hashlib
import math
import platform
from pathlib import Path


def read_number(text):
    """Convert a nonblank CSV number without filling unknowns with zero."""
    if text is None or text.strip() == "":
        raise ValueError("missing number")

    value = float(text)

    if not math.isfinite(value):
        raise ValueError("number must be finite")

    return value


def current_density_mA_cm2(current_mA, area_cm2):
    """Inputs have already been converted to finite numbers."""
    if area_cm2 <= 0:
        raise ValueError("area_cm2 must be positive")

    result = current_mA / area_cm2

    if not math.isfinite(result):
        raise ValueError("computed current density must be finite")

    return result


course_dir = Path(__file__).resolve().parents[1]
input_path = course_dir / "data" / "Day07_raw_records.csv"
output_dir = course_dir / "outputs"
output_dir.mkdir(exist_ok=True)

fields = [
    "record_id", "sample_id", "reaction", "potential_mV",
    "reference", "electrolyte", "temperature_K",
    "current_mA", "area_cm2", "area_basis",
    "ir_compensation", "source",
]

numeric_fields = [
    "potential_mV", "temperature_K", "current_mA", "area_cm2",
]

text_fields = [
    "record_id", "sample_id", "reaction", "reference",
    "electrolyte", "area_basis", "ir_compensation", "source",
]

audit = []
accepted = []
seen_ids = []
record_number = 0

with input_path.open(
    "r", encoding="utf-8-sig", newline=""
) as file:
    reader = csv.DictReader(file, strict=True)

    if reader.fieldnames != fields:
        raise ValueError(
            "Header does not match the Day07 field names and order"
        )

    for raw in reader:
        record_number += 1
        reasons = []
        numbers = {}

        if None in raw:
            raise ValueError(
                "A CSV record contains more cells than the header"
            )

        for key in numeric_fields:
            try:
                numbers[key] = read_number(raw[key])
            except ValueError as error:
                reasons.append(key + ": " + str(error))

        for key in text_fields:
            if raw[key] is None or raw[key].strip() == "":
                reasons.append(key + ": missing text")

        record_id = raw["record_id"]

        if record_id in seen_ids:
            reasons.append("record_id: duplicate")
        seen_ids.append(record_id)

        if raw["reaction"] != "HER" or raw["reference"] != "RHE":
            reasons.append("reaction/reference outside this exercise")

        if raw["area_basis"] != "geometric":
            reasons.append("area_basis outside this exercise")

        if (
            "temperature_K" in numbers
            and numbers["temperature_K"] <= 0
        ):
            reasons.append(
                "temperature_K must be positive for this exercise"
            )

        j_value = ""

        if len(reasons) == 0:
            try:
                j_value = current_density_mA_cm2(
                    numbers["current_mA"],
                    numbers["area_cm2"],
                )
            except ValueError as error:
                reasons.append(str(error))

        result_row = raw.copy()
        result_row["source_file"] = input_path.name
        result_row["source_record"] = record_number
        result_row["j_mA_cm2"] = j_value
        result_row["reasons"] = " | ".join(reasons)

        if len(reasons) == 0:
            result_row["status"] = "PASS"
            accepted.append(result_row)
        else:
            result_row["status"] = "HOLD"

        audit.append(result_row)

        print(
            record_id,
            result_row["status"],
            "j =", j_value,
            result_row["reasons"],
        )

output_fields = fields + [
    "source_file", "source_record", "status",
    "reasons", "j_mA_cm2",
]

for name, rows in [
    ("Day07_results.csv", accepted),
    ("Day07_audit.csv", audit),
]:
    with (output_dir / name).open(
        "w", encoding="utf-8-sig", newline=""
    ) as file:
        writer = csv.DictWriter(file, fieldnames=output_fields)
        writer.writeheader()
        writer.writerows(rows)

input_sha256 = hashlib.sha256(
    input_path.read_bytes()
).hexdigest()

script_path = Path(__file__).resolve()
script_sha256 = hashlib.sha256(
    script_path.read_bytes()
).hexdigest()

with (output_dir / "Day07_run_record.txt").open(
    "w", encoding="utf-8"
) as file:
    file.write("Input: " + str(input_path) + "\n")
    file.write("Input SHA256: " + input_sha256 + "\n")
    file.write("Script: " + str(script_path) + "\n")
    file.write("Script SHA256: " + script_sha256 + "\n")
    file.write("Python: " + platform.python_version() + "\n")
    file.write(
        "Counts input/pass/hold: "
        + str(len(audit)) + "/"
        + str(len(accepted)) + "/"
        + str(len(audit) - len(accepted)) + "\n"
    )

print(
    "Counts input/pass/hold:",
    len(audit),
    len(accepted),
    len(audit) - len(accepted),
)
print("Output directory:", output_dir)

十一、逐段理解代码

第一部分定义两个函数。

read_number负责"文字到有限数值"的转换。空白不能变成零;例如`"0"可以转为0.0,而""`应报告缺失。

第二个函数接收前面已经转换并检查的数值,再检查面积和派生结果。两个函数分工配套,不能脱离前提宣称第二个函数已经完成全部输入检查。

第二部分确定路径和字段。

本课要求表头名称及顺序与约定一致。这是简化教学接口,不是CSV格式强制所有文件采用的规则。

第三部分逐条处理。

  • raw保留原始文字。
  • numbers保存供计算使用的数值。
  • reasons保存本条问题。
  • record_number += 1表示记录序号加一。

第四部分构造输出副本。

例如原CSV中的`0.50`仍保留为原文字,同时新增计算结果。保留原文字有助追溯,但不代表其小数位必然具有测量精度依据。

第五部分导出文件。

writeheader()写表头,`writerows()`写多条记录。`fieldnames`明确输出列顺序。

最后部分记录输入和脚本的身份。路径、版本与计数是必学内容,SHA256是本节选学的补充方法。

十二、结果表、审计表和运行记录各做什么?

程序生成三个派生文件:

文件 内容
Day07_results.csv 三条通过记录及计算结果
Day07_audit.csv 全部六条记录、状态和原因
Day07_run_record.txt 输入与脚本路径、内容指纹、Python版本和计数

HOLD记录的电流密度留空,同时由`status`和`reasons`说明为什么没有计算。

留空不能自动解释成零。重读输出时,仍要先看状态。

还要注意,CSV本身不能无损保存所有Python对象。例如,默认写出`None`时可能成为空单元格,读回来也不会自动恢复原对象类型。因此,输出契约与状态字段很重要。

重新运行会覆盖这三个固定派生文件,不覆盖`data`中的原始CSV。需要保留多次科研运行时,应把对应输入、代码、输出和运行记录一起归档。

如果运行失败,目录中可能仍有上一次的输出,不能只凭"文件存在"判断本轮成功。

十三、什么叫"可追溯"?

面对一个计算结果,至少应能回答:

  • 使用哪份输入?
  • 使用哪个脚本版本?
  • 在什么环境中运行?
  • 执行了什么命令?
  • 采用什么单位和检查规则?
  • 哪些记录被暂缓,原因是什么?

仅保留一个叫`final.csv`的文件,通常不足以回答这些问题。

本课额外使用SHA256生成文件内容指纹:

复制代码
hashlib.sha256(input_path.read_bytes()).hexdigest()

可以把它理解为根据文件字节计算出的标识。它有助区分同名但内容不同的文件。

但它不能证明实验真实,也不能证明科学结论正确。编码或换行改变,即使显示内容相似,也可能改变字节和指纹。

因此,指纹应与文件、来源说明和处理记录一起保存。

十四、真实文献案例:不能为了适配表格而补造条件

前课已核验的Nørskov等2005年论文 Trends in the Exchange Current for Hydrogen Evolution 中,Pt条目包含:

\ \\log_{10} \\left\[ \\frac{j_0}{1\\ \\mathrm{A/cm\^2}} \\right =-3.1 \]

文献发表于 Journal of The Electrochemical Society 。论文DOI

可以把这个数值、指标名称、DOI和表格位置保存到单独文献表。

但不能为了让它符合本课工作点CSV,就补上教学设定的面积、电位和电解液。

原因是:

  1. −3.1是交换电流密度的对数,不是总电流。
  2. 原始条件需要回查来源。
  3. 保存格式不能改变物理定义。

对应转换是:

\ j_0=10\^{-3.1}\\ \\mathrm{A/cm\^2} \\approx0.794328\\ \\mathrm{mA/cm\^2} \\

它已经是电流密度,不需要再随意除以本课面积。

十五、实际运行结果与检查

在项目根目录的PowerShell中运行:

复制代码
& 'C:\Users\Admin\AppData\Roaming\uv\python\cpython-3.11-windows-x86_64-none\python.exe' '.\01_课程\Day07\code\Day07_csv_workflow.py'

本机使用已有Python 3.11.15。其他电脑应替换为实际解释器路径。

实际运行结果为:

复制代码
A_run01 PASS j = -25.0
B_run01 PASS j = -40.0
C_run01 PASS j = -40.0
D_run01 HOLD j =  area_cm2 must be positive
E_run01 HOLD j =  current_mA: missing number
F_run01 HOLD j =  reference: missing text | reaction/reference outside this exercise
Counts input/pass/hold: 6 3 3

维护者已完成以下核对:

  • 从另一个工作目录启动,仍读取同一输入。
  • 原CSV字节保持不变。
  • 中文来源和引号内逗号正确保留。
  • 原字段导出后重读一致。
  • 六条审计记录都有来源序号。
  • 暂缓记录的空结果没有变成零。
  • 三条结果与手算、反向计算一致。
  • 输入与脚本内容指纹匹配。

这证明本次文件处理符合已说明的规则,不代表任意工作站导出、编码或实验条件都已被覆盖。

十六、练习与验收

基础练习:

  1. 解释表头、记录、分隔符与引号的作用。
  2. 读取`current_mA`,确认转换前后的类型。
  3. 说明工作目录与脚本位置为何可以不同。
  4. 核对三条电流密度及\(6=3+3\)。

进阶练习:

  1. 在完整课程副本中增加一条新编号、零电流记录,先预测结果再运行。
  2. 把电流改成带单位文字或空白,观察审计原因。
  3. 从另一个目录使用脚本绝对路径运行。
  4. 重读审计表,确认`HOLD`没有被解释为零。
  5. 修改副本内容,观察内容指纹变化。

科研思考:

  1. CSV能正常打开,为什么仍不能证明单位正确?
  2. 为什么不能给文献未知条件补上教学值?
  3. 如果只保留结果表、删除问题记录,会损失哪些证据?
  4. 导出数值的小数位为什么不等于测量精度?

本节按概念25分、数学20分、代码25分、科学解释20分、复现记录10分评分。

达到80分,且能读对文件、不覆盖原始值、明确完成类型转换、未知不补零,并把结果追溯到来源记录,才算通过本节验收。

下一节严格按目录学习 "NumPy数组、维度与向量运算"。

相关推荐
装不满的克莱因瓶40 分钟前
【从零搭建】AI大模型之ReactAgent智能体对接MCP实战
java·人工智能·ai·springai·mcp·springaialibaba
百度Geek说1 小时前
研发Loop的上下文优化与多Agent协作实践
人工智能
七夜zippoe1 小时前
Nexent 模型配置:4 字段与 9 个槽位
数据库·人工智能·模型·nexent
硅农程序猿1 小时前
SOC 物理实现: RTL2GDS 系列(二)—Innovus 初始化
人工智能·嵌入式硬件·硬件架构
梦想很大很大1 小时前
一句“你好”用了 5671 Token:我在 Workrun 中追查 Agent 隐性成本的过程
前端·人工智能·后端
诗句藏于尽头1 小时前
游戏《完美神话》-使用Ai-agent进行修复已停服游戏到本地成功部署以及GM端网页完整教程
人工智能·学习·游戏
依晨照旧1 小时前
从 MQ 积压查出 4000 个线程:不是泄漏,是事件总线的设计代价
人工智能
英辰朗迪AI获客2 小时前
英辰朗迪GEO知识库第188期:动态渲染站点在AI搜索里成了隐形人
人工智能
硅谷秋水2 小时前
MorphMimic 方法分析
人工智能·机器学习·计算机视觉·机器人