简介：这份资源是面向Linux平台心电信号处理与分析的WFDB软件包，适合生物医学工程、心电算法研究及信号处理方向的学习者与开发者。WFDB由MIT-BIH心律失常实验室开发，支持C、C++、Java、Python等多种语言，可用于读取、显示、分析心电记录，并结合MIT-BIH基准数据库开展算法验证。压缩包共545个文件，约1.91MB，以C源码、头文件、makefile、hea头文件、dat数据文件及readme说明为主，另含sh脚本、png图示与tex文档，覆盖编译安装、命令行工具与示例数据。已有213人学习下载。借助其中的rdann、rdsamp、pg等工具与库函数，读者可完成滤波去噪、基线漂移校正、PQRST波群检测、心率与RR间期计算及心律失常异常检测，快速搭建Linux下的心电分析环境，为心脏病诊断与预防研究提供可复用的开发基础。
1. 拿到 wfdb.tar.gz 之后：Linux 上跑通心电信号分析的第一道坎
很多人第一次接触心电信号分析，是从 PhysioNet 上拖下来一个wfdb.tar.gz压缩包开始的。解压一看，里面是.hea、.dat、.atr这类陌生后缀，既不是 CSV 也不是图片，用 Excel 打不开，用文本编辑器看是乱码。这个包本质上就是 WFDB（WaveForm DataBase）格式的物理信号文件集合，配套的是wfdb这个 Python 工具链。它解决的核心问题很具体：把 MIT-BIH、PTB 这类标准心电数据库的原始采样点读进内存，转成 numpy 数组，再叠加注释文件做 R 波定位、心率变异性分析。适合谁？做可穿戴心电算法验证的嵌入式工程师、跑信号处理课程设计的学生、以及需要在 Linux 服务器上批量处理心电记录的运维兼算法角色。如果你手上正好有这个压缩包，下面这套流程能让你在两小时内从解压走到画出第一张 RR 间期图。
2. 环境搭建与 wfdb 工具链：从 tar.gz 到可导入的 Python 模块
2.1 为什么优先在 Linux 上处理 WFDB 数据
WFDB 的官方参考实现是 C 语言写的，Python 包wfdb底层通过 ctypes 调用这些库，在 Linux 上的兼容性最稳。Windows 上经常遇到libwfdb.so找不到的问题，而 Linux 发行版自带的包管理器能直接补齐依赖。另一个现实原因是心电数据库动辄几个 GB，Linux 的文件系统和命令行工具在批量解压、校验、切分上效率明显更高。我一般会在 Ubuntu 22.04 或 Rocky Linux 9 上做这件事，两者都验证过。需要提前确认的是 Python 版本，wfdb4.x 要求 Python 3.8 以上，3.11 也跑得通。
2.2 解压与目录结构确认
拿到wfdb.tar.gz后不要急着tar -xzf一把梭，先看一眼压缩包里的顶层目录名，避免解压出一堆散文件污染当前目录。
# 先列出压缩包内容，确认顶层目录结构 tar -tzf wfdb.tar.gz | head -20 # 确认无误后解压到指定目录，保持目录层级 mkdir -p ~/ecg_data tar -xzf wfdb.tar.gz -C ~/ecg_data # 查看解压后的文件类型分布 find ~/ecg_data -type f | sed 's/.*\.//' | sort | uniq -c第一行tar -tzf只列出不解压，是防止压缩包内文件散落的关键习惯。-C参数指定解压目标目录，避免在当前工作目录制造混乱。最后那条find配合sed和uniq -c能快速告诉你这个包里到底有几种文件后缀，正常应该看到hea、dat、atr三类，如果出现xws或edf说明数据来源不止一种，后续读取方式要区分。
2.3 安装 wfdb 与依赖
不要用pip install wfdb直接装完就完事，心电分析还需要 numpy、scipy、matplotlib 这三个基础库，版本不匹配会在滤波环节报奇怪的错误。
# 创建独立虚拟环境，避免污染系统 Python python3 -m venv ~/ecg_env source ~/ecg_env/bin/activate # 安装核心依赖，指定版本范围避免 API 变动 pip install "wfdb>=4.1,<5.0" "numpy>=1.24" "scipy>=1.10" "matplotlib>=3.7" # 验证 wfdb 能否正常加载底层库 python -c "import wfdb; print(wfdb.__version__); print(wfdb.rdrecord.__doc__[:80])"虚拟环境这一步在 Linux 上尤其重要，因为系统自带的 Python 往往被其他工具依赖，直接pip install可能触发权限问题或版本冲突。wfdb的版本锁定在 4.x 是因为 3.x 和 4.x 的rdrecord返回对象结构有差异，网上很多老教程用的是 3.x 写法，照抄会报AttributeError。最后那条验证命令如果打印出版本号和函数文档片段，说明底层libwfdb已经就位。
2.4 读取一条记录并确认采样参数
环境就绪后，先用一条记录验证整条链路。假设解压后的目录里有一个名为100的记录（MIT-BIH 格式的常见命名）。
import wfdb import numpy as np # 读取记录，path 指向解压目录，sampto 限制读取长度便于快速验证 record = wfdb.rdrecord( '100', pn_dir=None, sampto=5000, physical=True ) # 打印关键参数，确认采样率和导联数 print(f"采样率: {record.fs} Hz") print(f"导联名: {record.sig_name}") print(f"信号形状: {record.p_signal.shape}") print(f"单位: {record.units}") # 取第一导联前 10 个采样点看看数值范围 print(record.p_signal[:10, 0])physical=True表示返回的是经过物理单位换算的毫伏值，如果设为False则返回原始 ADC 整数。sampto=5000只读前 5000 个采样点，在调试阶段能省掉大量等待时间。p_signal的 shape 是(采样点数, 导联数)，这一点和很多人的直觉相反，不是行优先。打印出的数值范围正常应该在 -5 到 5 毫伏之间，如果看到几千的整数说明物理换算没生效。
3. 信号预处理与 R 波检测：把原始采样点变成可分析的心搏序列
3.1 基线漂移与工频干扰的处理顺序
原始心电信号里混着两类主要噪声：基线漂移（0.5 Hz 以下的低频漂移）和工频干扰（50 Hz 或 60 Hz）。处理顺序有讲究，先做带通滤波把两者一起压掉，再做 Notch 滤波专门针对工频。如果反过来，Notch 滤波器的瞬态响应会被基线漂移放大，反而引入新的伪影。
from scipy.signal import butter, filtfilt, iirnotch def bandpass_filter(signal, fs, low=0.5, high=40.0, order=3): """巴特沃斯带通滤波，保留 0.5-40 Hz 心电主要能量""" nyq = fs / 2.0 b, a = butter(order, [low / nyq, high / nyq], btype='band') # filtfilt 零相位滤波，避免 R 波位置偏移 return filtfilt(b, a, signal) def notch_filter(signal, fs, freq=50.0, quality=30.0): """IIR Notch 滤波，压制工频干扰""" b, a = iirnotch(freq, quality, fs) return filtfilt(b, a, signal) # 对第一导联依次处理 sig = record.p_signal[:, 0] sig_bp = bandpass_filter(sig, record.fs) sig_clean = notch_filter(sig_bp, record.fs, freq=50.0)filtfilt而不是lfilter是关键，前者做正向和反向两次滤波，相位偏移为零，R 波位置不会移动。order=3是经验值，阶数太高会在 QRS 复合波边缘产生振铃。Notch 的quality=30决定了陷波带宽，值越大带宽越窄，对 50 Hz 的压制越精准但对频率漂移越敏感。国内工频是 50 Hz，如果数据来自北美设备则要改成 60 Hz，这个参数搞错等于没滤。
3.2 用 wfdb 自带注释做 R 波定位
WFDB 格式的一大优势是注释文件里已经标好了专家标注的 R 波位置，不需要自己写检测算法就能拿到基准。但要注意注释的采样点编号和信号采样点是一一对应的。
# 读取注释文件 annotation = wfdb.rdann('100', 'atr', sampto=5000) # 筛选出正常心搏的注释类型 # 'N' 表示正常搏动，'L' 和 'R' 表示左右束支阻滞 normal_beats = [ (pos, sym) for pos, sym in zip(annotation.sample, annotation.symbol) if sym in ('N', 'L', 'R') ] # 提取 R 波位置数组 r_peaks = np.array([pos for pos, _ in normal_beats]) print(f"检测到 {len(r_peaks)} 个正常心搏") # 计算 RR 间期，单位毫秒 rr_intervals = np.diff(r_peaks) / record.fs * 1000 print(f"平均心率: {60000 / np.mean(rr_intervals):.1f} bpm")rdann的第二个参数'atr'是注释文件的后缀，不同数据库可能用'qrs'或'ecg'。annotation.symbol是一个字符列表，每个字符对应一个心搏类型，'N'是最常见的正常搏动。RR 间期计算用np.diff得到相邻 R 波采样点差值，除以采样率再乘 1000 转成毫秒。平均心率用 60000 除以平均 RR 间期，这是标准算法，但要注意如果 RR 间期方差很大，平均值会掩盖心律失常，这时候要看 RR 间期的标准差。
3.3 没有注释文件时自己写 Pan-Tompkins 检测
有些数据库不带注释，或者你想验证自己的检测算法，就需要实现一个 QRS 检测器。Pan-Tompkins 是经典方案，核心是微分、平方、移动窗积分三步。
def pan_tompkins(signal, fs): """简化版 Pan-Tompkins QRS 检测""" # 1. 带通滤波已在外部完成，这里直接微分 diff_sig = np.ediff1d(signal, to_begin=0) # 2. 平方，放大高频成分 squared = diff_sig ** 2 # 3. 移动窗积分，窗口宽度约 150ms window_size = int(0.15 * fs) integrated = np.convolve(squared, np.ones(window_size) / window_size, mode='same') # 4. 自适应阈值，取积分信号的最大值的 0.3 倍作为初始阈值 threshold = 0.3 * np.max(integrated) peaks = [] for i in range(1, len(integrated) - 1): if integrated[i] > threshold and integrated[i] > integrated[i-1] and integrated[i] > integrated[i+1]: # refractory period 200ms 内不重复检测 if not peaks or (i - peaks[-1]) > int(0.2 * fs): peaks.append(i) return np.array(peaks)微分用np.ediff1d而不是np.diff，前者会在开头补零保持长度一致。移动窗积分用np.convolve配合全一数组除以窗口长度，等价于滑动平均。阈值取最大值的 0.3 倍是 Pan-Tompkins 论文里的经验值，但实际数据中如果噪声大，这个阈值会漏检，常见做法是用0.3 * np.percentile(integrated, 99)替代np.max来抗离群点。 refractory period 设为 200ms 是因为生理上两次心搏不可能间隔这么短，这个约束能过滤掉 T 波误检。
4. 避坑与排查：心电信号处理里那些让人怀疑数据的瞬间
4.1 读取时报FileNotFoundError但文件明明存在
现象：wfdb.rdrecord('100')报找不到文件，但ls能看到100.hea和100.dat。
原因：rdrecord的第一个参数是记录名，不是文件名。如果当前工作目录不在数据目录下，或者记录名带了路径分隔符，就会解析失败。
解决：用os.chdir切到数据目录，或者给rdrecord传完整路径但去掉后缀。例如wfdb.rdrecord('/home/user/ecg_data/100')，注意不要写成100.hea。
4.2 画出来的波形是一条直线
现象：plt.plot(record.p_signal[:, 0])显示一条平线，数值全为零或接近零。
原因：physical=True时如果.hea文件里的增益和基线字段格式不标准，物理换算会得到全零。或者读取时channels参数选错了导联索引。
解决：先用physical=False读原始 ADC 值确认信号存在，再检查record.adc_gain和record.baseline是否合理。如果原始值正常但物理值为零，手动做换算：(raw - baseline) / gain。
4.3 R 波检测数量远多于实际心搏
现象：自己写的检测算法报出几百个 R 波，但 10 秒数据里正常只有十几次心搏。
原因：阈值设得太低，把 T 波和噪声都算进去了。或者没有做 refractory period 约束。
解决：把阈值从0.3 * max提高到0.5 * max，并强制 200ms 的不应期。更稳妥的做法是先对积分信号做一次 5 点中值滤波，把毛刺压掉再检测。
4.4 滤波后 R 波幅度变小甚至消失
现象：带通滤波后波形变平滑，但 R 波峰值从 1.5mV 降到 0.3mV。
原因：带通滤波的高截止频率设得太低，比如设成 15 Hz，QRS 复合波的主要能量在 10-40 Hz 之间，被削掉了。
解决：高截止频率至少设到 40 Hz，诊断级心电分析常用 0.05-100 Hz，但那样会保留更多噪声。常规分析用 0.5-40 Hz 是平衡点。
4.5 注释文件里的采样点和信号对不上
现象：annotation.sample的最大值超过了record.p_signal的长度。
原因：读取信号时用了sampto限制长度，但读取注释时没加同样的限制，导致注释索引越界。
解决：rdann也要传sampto参数，保持和rdrecord一致。或者先读完整信号再截取，不要在两处分别限制。
5. 批量处理与结果验证：把单条记录的经验固化成脚本
单条记录跑通只是起点，真正干活时面对的是几十上百条记录。我一般会写一个批处理脚本，把读取、滤波、R 波检测、RR 间期计算、结果保存串起来，并且加一个验证环节——用注释文件的 R 波位置和自己检测的结果做比对，算敏感度和阳性预测值。
import os import glob import numpy as np import wfdb from scipy.signal import butter, filtfilt def process_record(record_path, fs_target=None): """处理单条记录，返回 RR 间期和检测指标""" record = wfdb.rdrecord(record_path) annotation = wfdb.rdann(record_path, 'atr') sig = record.p_signal[:, 0] fs = record.fs # 带通滤波 nyq = fs / 2.0 b, a = butter(3, [0.5 / nyq, 40.0 / nyq], btype='band') sig_clean = filtfilt(b, a, sig) # 用注释作为基准，计算 RR 间期 r_peaks = annotation.sample rr = np.diff(r_peaks) / fs * 1000 # 简单的异常值过滤：RR 间期在 300-2000ms 之外视为伪影 valid_rr = rr[(rr > 300) & (rr < 2000)] return { 'record': os.path.basename(record_path), 'fs': fs, 'n_beats': len(r_peaks), 'mean_rr': np.mean(valid_rr) if len(valid_rr) > 0 else 0, 'std_rr': np.std(valid_rr) if len(valid_rr) > 0 else 0, 'hr': 60000 / np.mean(valid_rr) if len(valid_rr) > 0 else 0 } # 批量处理目录下所有 .hea 文件 data_dir = os.path.expanduser('~/ecg_data') hea_files = glob.glob(os.path.join(data_dir, '*.hea')) results = [] for hea in hea_files: record_name = hea[:-4] # 去掉 .hea 后缀 try: res = process_record(record_name) results.append(res) print(f"{res['record']}: HR={res['hr']:.1f} bpm, beats={res['n_beats']}") except Exception as e: print(f"{record_name} 处理失败: {e}") # 汇总统计 if results: hrs = [r['hr'] for r in results if r['hr'] > 0] print(f"\n共处理 {len(results)} 条记录") print(f"平均心率范围: {min(hrs):.1f} - {max(hrs):.1f} bpm")这个脚本里glob.glob匹配所有.hea文件，然后用切片去掉后缀得到记录名。try/except包住每条记录的处理，避免一条坏数据中断整个批次。RR 间期的 300-2000ms 过滤范围对应心率 30-200 bpm，超出这个范围的通常是漏检或误检。最后汇总时只统计心率大于零的记录，防止除零错误。
验证环节我习惯抽三条记录，把注释的 R 波位置和滤波后的信号画在一起，肉眼确认对齐。这一步不能省，因为有些数据库的注释文件本身就有标注错误，盲目相信注释会导致后续分析全盘偏差。画图代码很短：
import matplotlib.pyplot as plt # 抽一条记录画图验证 record = wfdb.rdrecord(os.path.join(data_dir, '100'), sampto=3000) ann = wfdb.rdann(os.path.join(data_dir, '100'), 'atr', sampto=3000) fig, ax = plt.subplots(figsize=(12, 4)) ax.plot(record.p_signal[:, 0], linewidth=0.8, label='ECG') ax.scatter(ann.sample, record.p_signal[ann.sample, 0], color='red', s=20, zorder=5, label='Annotation') ax.set_xlabel('Sample') ax.set_ylabel('mV') ax.legend() plt.tight_layout() plt.savefig('verify_100.png', dpi=150)zorder=5保证红点画在波形上方，s=20控制点的大小。保存成 PNG 而不是直接show，是因为在服务器上跑没有图形界面，保存文件再下载查看更实际。
从那以后我每次拿到新的 WFDB 数据包，都强制先跑一遍这个验证流程：读一条、画一张、对一次注释。这个习惯帮我拦下过好几次采样率标错和导联顺序颠倒的问题。希望帮到你。
本文还有配套的精品资源，点击获取
