前六节中,我们已经能使用变量、列表、字典、循环和函数处理记录。但输入仍主要写在代码里。
实际科研中,电化学工作站会导出文件,文献数据也常整理成表格。因此,本节要把前面的知识连接起来:
从文件读取数据,按照明确规则处理,再把结果保存为新的文件。
一、本节学习目标
学完后,你应能够:
- ++理解CSV的表头、记录、分隔符和引号。++
- ++正确处理中文编码和文件换行。++
- ++区分工作目录与脚本所在位置。++
- ++将CSV中的数字文字明确转换成数值。++
- ++保留未知和问题原因,不用零掩盖缺失。++
- ++导出计算结果与完整审计表。++
- ++记录输入文件、脚本、环境和处理结果之间的关系。++
本节使用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,就补上教学设定的面积、电位和电解液。
原因是:
- −3.1是交换电流密度的对数,不是总电流。
- 原始条件需要回查来源。
- 保存格式不能改变物理定义。
对应转换是:
\ 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字节保持不变。
- 中文来源和引号内逗号正确保留。
- 原字段导出后重读一致。
- 六条审计记录都有来源序号。
- 暂缓记录的空结果没有变成零。
- 三条结果与手算、反向计算一致。
- 输入与脚本内容指纹匹配。
这证明本次文件处理符合已说明的规则,不代表任意工作站导出、编码或实验条件都已被覆盖。
十六、练习与验收
基础练习:
- 解释表头、记录、分隔符与引号的作用。
- 读取`current_mA`,确认转换前后的类型。
- 说明工作目录与脚本位置为何可以不同。
- 核对三条电流密度及\(6=3+3\)。
进阶练习:
- 在完整课程副本中增加一条新编号、零电流记录,先预测结果再运行。
- 把电流改成带单位文字或空白,观察审计原因。
- 从另一个目录使用脚本绝对路径运行。
- 重读审计表,确认`HOLD`没有被解释为零。
- 修改副本内容,观察内容指纹变化。
科研思考:
- CSV能正常打开,为什么仍不能证明单位正确?
- 为什么不能给文献未知条件补上教学值?
- 如果只保留结果表、删除问题记录,会损失哪些证据?
- 导出数值的小数位为什么不等于测量精度?
本节按概念25分、数学20分、代码25分、科学解释20分、复现记录10分评分。
达到80分,且能读对文件、不覆盖原始值、明确完成类型转换、未知不补零,并把结果追溯到来源记录,才算通过本节验收。
下一节严格按目录学习 "NumPy数组、维度与向量运算"。