kulun 2.2.10

Coulomb titration .dat data processing and scientific plotting CLI tool

kulun — 库仑滴定数据处理与科研绘图工具

v2.2.10 已发布 — 修复了一些已知 bug。v2.2.9 中-e 仅接受2列/5列 DAT 文件；3列 DAT 为软件插值拟合数据，继续处理会失去物理意义，程序将拦截并引导用户传入2列原始数据。v2.2.8 中 -c / -ec / -cp / -ecp 均支持传入文件夹，交互式排列文件顺序。详情见 GitHub Releases。

⚠️ 尽量不要在文件名中使用空格或 ^ _ { } 等特殊字符

脚本 以空格区分不同文件，含空格的文件名必须加英文引号（如 "my data.dat"，也可以用单引号）才能被正确识别；^ _ {} 在标题/图例中会被解析为上下标。为保证图表标题与图例的正常显示，文件命名中请尽量不要出现 ^ _ {} 等特殊字符。

kulun 是一个用 Python 编写的命令行工具，专门用于提取、合并并绘制由 北京大学化学与分子工程学院定量分析化学实验教学组 开发的库仑滴定软件所生成的 .dat 数据文件。支持滴定曲线及一阶导数分析、多曲线对比叠加、突跃点自动标注，启动时自动检测 PyPI 新版本并提醒更新。

---

目录

• 安装
• 快速开始
• 命令详解
  • 1. 提取数据 -e
  • 2. 合并数据 -c
  • 3. 提取 + 合并 -ec
  • 4. 绘制科研图 -p
  • 5. 提取 + 绘图 -ep
  • 6. 合并 + 绘图 -cp
  • 7. 一步到位 -ecp
  • 8. 多曲线对比图 -t
  • 9. 提取 + 对比 -et
• 常见问题
• 从源码安装（开发者）
• 许可证

---

安装

确保电脑上已安装 Python 3.7 或更高版本，然后在终端中运行：

pip install kulun

安装完成后，在终端输入以下命令验证是否成功：

kulun --version

如果输出了版本号（如 kulun 2.2.10），说明安装成功。

如果你是第一次接触终端——

• Windows: 按 Win(⊞) + R，输入 "cmd" 回车。
• macOS: 按 Command(⌘) + 空格，搜索 "终端" 或 "Terminal" 并打开。

---

快速开始

⚠️ 命名提醒： 脚本以空格区分不同文件，含空格的文件名必须加英文引号（如 "my data.dat"，也可以用单引号）才能被正确识别（否则会被识别为文件夹 my/ 与错误的文件 data.dat）；^ _ {} 在标题/图例中会被解析为上下标。为保证图表标题与图例的正常显示，文件命名中请尽量不要出现 ^ _ {} 等特殊字符。

下面用一个典型的数据处理流程演示 kulun 的用法：

# 第 1 步：将 .dat 文件提取为表格
kulun -e my_data.dat
# → 生成 my_data.csv

# 第 2 步：绘制滴定曲线和一阶导数图
kulun -p my_data.csv
# → 生成 my_data.png（300 dpi 科研插图）

如果你有多个 .dat 文件需要顺序拼接后再出图，可以用以下代码一行搞定：

kulun -ecp file1.dat file2.dat file3.dat
# → 提取 → 合并 → 绘图，一步完成

如果你需要将多次独立实验的滴定曲线叠加在同一张图中对比：

# 直接对比已提取的 CSV
kulun -t run1.csv run2.csv run3.csv

# 或一步到位：提取 .dat 并叠加对比
kulun -et run1.dat run2.dat run3.dat

# 显示数据散点（不同曲线使用不同形状）
kulun -td run1.csv run2.csv

---

命令详解

1. 提取数据 -e

从库仑滴定仪导出的 .dat 文件中提取时间和电位数据，保存为 .csv 表格。仅支持2列（原始数据）和5列格式的 DAT 文件。3列 DAT 文件为软件插值拟合数据，继续处理会失去物理意义，程序将自动拦截并引导用户传入2列原始数据。

# 处理单个文件
kulun -e sample.dat

# 处理整个文件夹里的所有 .dat 文件
kulun -e ./data_folder/

输入	输出
sample.dat	sample.csv

---

2. 合并数据 -c

将多次实验的 CSV 文件按顺序拼接成一个，时间轴自动连续平移。支持传入文件夹，交互式排列文件顺序。

# 按顺序传入多个 CSV 文件
kulun -c part1.csv part2.csv part3.csv

# 传入文件夹（支持多个文件夹+多个文件混传）
kulun -c ./data_folder/
kulun -c ./folder1/ ./folder2/ extra.csv

程序会交互式询问合并后的文件名（比如输入 combined.csv）。

注意： 文件的传入顺序很重要，请按照实验进行的先后顺序排列。

---

3. 提取 + 合并 -ec

-e + -c 的组合方法：先提取每个 .dat，再合并成一个 CSV。支持传入文件夹，交互式排列文件顺序。

# 按顺序传入多个 .dat 文件
kulun -ec run1.dat run2.dat run3.dat

# 传入文件夹
kulun -ec ./data_folder/

---

4. 绘制科研图 -p

对 CSV 数据绘图，自动识别平行滴定曲线、计算一阶导数、标注突跃点。支持传入文件夹或多个文件，批量处理时弹出确认提示。

# 处理单个 CSV 文件
kulun -p data.csv

# 批量处理文件夹内所有 CSV 文件
kulun -p ./csv_folder/

# 一次传入多个 CSV 文件，分别绘图
kulun -p run1.csv run2.csv run3.csv

程序会依次询问图片标题、图例，识别到多条平行曲线时可选择多色模式（见下方色卡），自定义各曲线颜色。

输出图片包含： 平滑曲线与原始散点、一阶导数曲线、突跃点标记（含电位值、一阶导数值和时间间隔）。平行曲线间以灰线连接。排版自动适配曲线条数。

智能判定： 自动排除因测量时间间隔切换引起的假突跃。对真突跃做双重可靠性检查，满足任一条件则标为"存疑"（黄色）：

• 突跃偏离导数基线不足 2σ（信噪比低）
• 15 s 以外存在导数值与之接近（比值 < 1.3）的另一极值（竞争 trough）

其余突跃点标记为绿色。

多色模式可选颜色（共 8 种）：

1	2	3	4	5	6	7	8
#1f77b4	#d95f02	#e377c2	#984ea3	#17becf	#a6761d	#b82e8a	#7570b3

---

5. 提取 + 绘图 -ep

-e + -p 的组合方法：先提取 .dat 文件为 CSV，再分别对每个 CSV 绘制分析图。支持传入文件夹或多个文件。

# 从单个 .dat 文件提取并绘图
kulun -ep data.dat

# 批量处理文件夹内所有 .dat 文件
kulun -ep ./data_folder/

# 一次传入多个 .dat 文件，分别提取并绘图
kulun -ep run1.dat run2.dat run3.dat

注意： -ep 不会合并数据，而是对每个 .dat 独立提取、独立绘图。如需合并后绘图请使用 -ecp。

---

6. 合并 + 绘图 -cp

-c + -p 的组合方法：合并多个 CSV，再绘制合并后的总图。支持传入文件夹。

kulun -cp part1.csv part2.csv part3.csv
kulun -cp ./data_folder/

---

7. 一步到位 -ecp

kulun 一步到位的命令：把原始 .dat 文件直接变成科研插图。支持传入文件夹。

kulun -ecp run1.dat run2.dat run3.dat
kulun -ecp ./data_folder/

等价于手动执行：

# -ecp 内部自动完成以下三步：
kulun -ec run1.dat run2.dat run3.dat   # 提取 + 合并
kulun -p combined.csv                  # 绘图

---

8. 多曲线对比图 -t

将多条 CSV 滴定曲线叠加在同一张图中对比，自动拟合平滑曲线并以不同颜色区分。支持传入文件夹，自动识别其中的 CSV/DAT 文件。

# 传入分立的 CSV 文件
kulun -t run1.csv run2.csv run3.csv

# 传入文件夹或混合路径
kulun -t ./data_folder/ run1.csv

# 同时显示数据散点
kulun -td run1.csv run2.csv run3.csv

等价写法：-tu = -t + -u（仅曲线，默认行为），-td = -t + -d（显示数据散点）。

---

9. 提取 + 对比 -et

-e + -t 的组合方法：先提取 .dat，再叠加绘制对比图。支持直接传入文件夹。

# 从多个 .dat 文件一步生成对比图
kulun -et run1.dat run2.dat run3.dat

# 使用文件夹：自动提取所有 .dat，并询问是否考虑已有的 .csv
kulun -et ./data_folder/

# 含数据点版本
kulun -etd run1.dat run2.dat

等价写法：-etu = -et + -u（默认行为），-etd = -et + -d。

文件夹智能识别： 程序会列出文件夹中无法转换的非 .dat 文件，若发现已有 .csv 文件，会逐个询问是否一并加入对比图，避免重复提取。

---

常见问题

Q: 安装时报错 pip: command not found

说明电脑上还没有 Python。请先去 python.org 下载安装 Python（安装时勾选 "Add Python to PATH"），然后再运行 pip install kulun。

Q: 绘图中文显示为方框

v2.2.0 已将绘图引擎从 matplotlib 迁移至 plotly，利用浏览器引擎的 CSS 字体回落机制处理中文，覆盖 Windows / macOS / Linux 的常见中文字体，无需用户手动配置。如果仍有问题，请提交 Issue。

对于 Ubuntu / Debian 等中文字体可能缺失的 Linux 发行版，程序启动时会自动检测并提示安装：

sudo apt-get install fonts-noto-cjk

Q: 绘图时报错缺少库

kulun 依赖以下 Python 包（安装时会自动带上）：

包名	用途
numpy	数值计算
scipy	信号平滑与插值
plotly	绘图引擎
kaleido	静态图像导出（PNG）

如果你用了虚拟环境，请确认已激活：

# 先激活虚拟环境，再安装
pip install kulun

Q: 如何在标题/图例中表示化学式

使用 _ ^ {} 即可，例如 SO_4^{2-} 渲染为 SO₄²⁻，Fe_2O_3 渲染为 Fe₂O₃。程序启动时会给出示例提示。

Q: 文件已存在时会发生什么

程序会自动检测同名文件（包括 xxx(1).csv 等编号变体），列出全部已有文件并询问是否替换。选择 n 后按 Enter 会自动采用下一个可用编号。用户手动输入的文件名若已存在，同样会先询问是否替换，拒绝后可继续输入新名称，任意层级均支持。

Q: 传入了不支持的文件类型

程序会对每个命令校验传入的文件类型——例如 -c / -p 只能接受 CSV，-e 只能接受 DAT（且仅限2列/5列格式，3列插值数据会被拦截）。若类型不匹配，会给出明确提示。文件或文件夹不存在时，程序会提示输入正确路径（敲 Enter 跳过），可交互式补录，不再直接丢弃。

Q: 图片坐标轴数字太小或排版不美观

排版已按科研绘图标准优化（全封闭坐标轴、物理量斜体单位正体、曲线粗度 2× 坐标轴、尺寸自适应）。如需进一步定制，请提交 Issue。

Q: 如何卸载

pip uninstall kulun

Q: 程序启动时提示新版本

kulun v2.0 起内置了自动更新检测：启动时后台静默查询 PyPI，若发现新版本会在终端打印提醒（24 小时内不会重复检查）。运行以下命令即可更新：

pip install --upgrade kulun

---

从源码安装（开发者）

git clone https://github.com/EricZhangpku/kulun.git
cd kulun
pip install -e .

---

许可证

MIT License · EricZhangpku

---

Full documentation on GitHub