NeuroKit2 0.2.13 心电信号处理实战指南ecg_process 流程、R 峰校正与 ECG 质量评估【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本篇技术指南以 scientific-agent-skills 仓库中 NeuroKit2 技能的 ecg_cardiac.md 参考文档为主体围绕 NeuroKit2 0.2.13 稳定版的 ECG 处理管线展开从采集契约、ecg_process()默认流程与输出 schema到清洗/峰值检测方法选型、Lipponen–Tarvainen 伪迹校正、方法依赖的 ECG 质量评分、DWT 分波以及仓库内置的有界 CLI 流水线 ecg_hrv_pipeline.py。读者读完可掌握一套可复现、可审计、方法意识明确的科研级 ECG 处理与 HRV 前置工作流并学会把输出 schema 当作运行时观测而非通用承诺来对待。应用场景与研究边界NeuroKit2 是面向科研与教学的开源生理时间序列工具箱。本技能将其锁定在0.2.13 稳定版2026-03-02 发布见 SKILL.md 的 Scope 一节并明确要求输出不能作为诊断、治疗建议、患者监护决策或报警依据输出不构成医疗设备的验证、认证或监管证据输出不能证明某个生理构念在新型传感器、协议、环境、人群或疾病组中测量有效。该边界在 SKILL.md 的 Boundary 小节与 ecg_cardiac.md 中反复强调也在 ecg_hrv_pipeline.py 的research_use_only与warning字段中落地为报告输出。任何使用本流程的研究者都应在报告中保留原始数据与可审计的排除日志且只处理去标识化的本地文件不把受保护健康信息PHI写入提示词、日志或示例。采集契约进管线之前先记录什么ecg_cardiac.md 的 Acquisition contract 一节强调进入任何处理管线之前必须记录以下元数据导联/配置、电极放置位置、参考/接地方式硬件增益与滤波器设置ADC 分辨率/量程、物理单位、原生采样率、时间戳时钟姿势/任务、用药情况和相关人群变量、伪影标注。绝不从名为ECG的列推断毫伏单位——这一约束在 SKILL.md 的 Required data contract 中也以Never infer units from a column name的形式重复。采样率必须支撑预期终点心率/R 峰时序与 P–QRS–T 形态学对带宽和精度需求不同。心理生理学指南通常要求至少 125 Hz并把 500 Hz 视为 HRV 计时上的保守选择但这不是普适验证阈值形态学分波delineation常用 250–1000 Hz。正确的做法是在具有代表性的信号上整体验证采集 检测器组合而不是依赖某个默认采样率。ecg_process()在稳定版 0.2.13 中的处理步骤核心入口是ecg_process()signals, info nk.ecg_process( ecg, sampling_rate250, methodneurokit, )根据 ecg_cardiac.md 对照 0.2.13 稳定版源码的核验该函数内部依次执行signal_sanitize()仅重置索引按所选方法调用ecg_clean()清洗ecg_peaks(..., correct_artifactsTrue)检峰插值得到瞬时心率默认ecg_quality(..., methodaverageQRS)质量评估DWT 分波delineation心房/心室相位估计。输出 schema 是运行时观测不是通用承诺固定默认探针pinned default probe观测到 19 个输出列ECG_Raw, ECG_Clean, ECG_Rate, ECG_Quality, ECG_R_Peaks, ECG_P_Peaks, ECG_P_Onsets, ECG_P_Offsets, ECG_Q_Peaks, ECG_R_Onsets, ECG_R_Offsets, ECG_S_Peaks, ECG_T_Peaks, ECG_T_Onsets, ECG_T_Offsets, ECG_Phase_Atrial, ECG_Phase_Completion_Atrial, ECG_Phase_Ventricular, ECG_Phase_Completion_Ventricular文档明确强调这是已验证的默认 schema不是普适承诺。返回列会随 NeuroKit2 版本、函数、方法、信号可用性与分析模式变化因此应当持久化list(signals.columns)与sorted(info)而不是硬编码一份完整列清单。这一原则同样落实在 SKILL.md 的 Treat schemas as runtime observations 小节并直接写入了 ecg_hrv_pipeline.py 的output_schema_observed报告字段。info是一个扁平 dict在默认固定运行中它包含校正前/后的 R 峰、ECG_fixpeaks_*诊断信息、采样率、方法以及分波波峰索引不嵌套在ECG键下。清洗与 R 峰检测的方法选型ecg_process()文档化的高层方法包括方法说明neurokit默认NeuroKit2 内置组合策略pantompkins1985经典的 Pan–Tompkins 实时 QRS 检测hamilton2002Hamilton 改进版针对噪声鲁棒性elgendi2010基于带通滤波与移动平均的能量检测engzeemod2012Engzee 改进版ecg_clean()与更低层的峰值检测还暴露额外方法。清洗方法与检测器编码了不同的假设——不要为了得到期望的组效应而挑选方法。需要自定义控制时可拆开执行clean nk.ecg_clean(ecg, sampling_rate250, methodneurokit) markers, peak_info nk.ecg_peaks( clean, sampling_rate250, methodneurokit, correct_artifactsFalse, )检峰后必须验证R 峰精度、假阳性、漏搏与异位搏动ectopy运动、心率变化、低幅 QRS 场景下的表现导联极性与可能的倒置滤波器边缘区域与不连续处按被试、条件、设备与人群分解的失败模式。这一验证清单在仓库的 SKILL.md Core workflow 中被编排为先检查后变换的 10 步处理顺序并强调不要对峰值索引数组做普通连续信号的降采样。R 峰伪迹校正Lipponen–Tarvainen 算法0.2.13 的ecg_process()总是请求 Lipponen–Tarvainen 校正correct_artifactsTrue。校正信息可从info中取回uncorrected info[ECG_R_Peaks_Uncorrected] corrected info[ECG_R_Peaks] categories { key: info.get(fECG_fixpeaks_{key}, []) for key in [ectopic, missed, extra, longshort] }四个类别分别对应异位搏动、漏检、多余检与长-短间期异常。校正既能改善 tachogram也可能改变 HRV 结果——报告时必须给出校正比例、类别计数、阈值/方法、被排除的片段以及与未校正或替代策略的敏感性对比。不要假设算法无需波形复核或恰当标签就能区分异位搏动与误检。仓库的 ecg_hrv_pipeline.py 用同一组类别键从info聚合_artifact_counts并在 L245-L251 发现任何校正事件时发出警告R-peak corrections were applied by ecg_process(); inspect the raw trace, uncorrected peaks, and correction categories。这与 hrv.md 的 Ectopy and artifact policy 六步流程一致校正后的序列不等于有效的 NN 序列重校正可能制造平滑的 HRV异位/脱落/运动过多的片段应当排除而非插值。ECG 质量评估是方法相关的质量评估可独立调用quality nk.ecg_quality( clean, rpeakspeak_info[ECG_R_Peaks], sampling_rate250, methodaverageQRS, )稳定版可选方法包括averageQRS、templatematch、zhao2018、dissimilarity和ho2025语义各不相同averageQRS连续数组该实现将其缩放到 0–1templatematch连续形态模板相关性相对记录本身而言zhao2018输出单个分类字符串Unacceptable、Barely acceptable或Excellentdissimilarity方向/尺度与相似性评分不同不可混读ho2025基于检测器一致性的搏动/间期导向质量。关键结论是不存在跨方法的通用0.6验收规则质量输出不等于设备验证。应在独立的带标签数据上定义阈值并保留方法名与尺度。仓库中 ecg_hrv_pipeline.py 将ECG_Quality的 count/mean/min/max 汇总进报告tests/neurokit2/test_scripts.py 的冒烟测试则断言 0.2.13 固定运行时输出 schema 中包含ECG_Quality列。分波Delineation的返回顺序与验证delineation_signals, waves nk.ecg_delineate( clean, rpeakspeak_info[ECG_R_Peaks], sampling_rate250, methoddwt, )第一个返回对象是与信号等长的标记 DataFrame第二个是波形样本索引的 dict。稳定版方法包括peak、prominence、cwt与dwt。缺失的波形索引可能是 NaN。R 峰准确并不能验证 P/T 分波——任何基于间期/形态学的结论都要逐一验证所用的每个波形端点。相位与事件相关分析ECG_Phase_Atrial与ECG_Phase_Ventricular是二值相位标签*_Completion_*列是 0 到 1 的分数其有效性依赖分波质量。对心脏锁定的刺激触发延迟/抖动应独立于软件相位估计进行刻画。事件相关分析可用features nk.ecg_analyze( epochs, sampling_rate250, methodevent-related, )ecg_eventrelated()与ecg_intervalrelated()的输出列是条件性的——取决于输入中存在哪些列。文档建议使用显式分发并保存观测到的列名避免把不存在的特征当成已计算值。相关的事件/epoch 细节events_find()的零基样本索引、epoch 切片 end-exclusive 等可参考 SKILL.md 的 Events, epochs, and baseline 小节。ECG 衍生呼吸EDRecg_rsp()接收的是心率序列而非原始/清洗 ECGedr nk.ecg_rsp(signals[ECG_Rate], sampling_rate250, methodvangent2019)EDR 是代理指标依赖 ECG 形态与心率调制不能与校准过的呼吸传感器互换使用——尤其不能用于 RSA、潮气量或呼吸诊断。有界 CLI 流水线ecg_hrv_pipeline.py仓库在 skills/neurokit2/scripts/ecg_hrv_pipeline.py 提供了开箱即用的有界流水线支持真实去标识 CSV 或可复现合成信号python skills/neurokit2/scripts/ecg_hrv_pipeline.py \ --input deidentified.csv --column ECG --root . --deidentified \ --sampling-rate 250 --method neurokit --domains time \ --signals-output ecg_processed.csv --output ecg_report.json参数要点与源码 build_parser 对应--input与--synthetic互斥必须二选一真实数据必须加--deidentified--sampling-rate必填范围 20–20000 HzL106-L111合成模式要求整数--method可选neurokit|pantompkins1985|hamilton2002|elgendi2010|engzeemod2012默认neurokit--domains为time,frequency,nonlinear的逗号子集默认time未知域会直接报错L112-L117合成模式下--duration5–3600 秒、--heart-rate20–240 BPM、--seed有符号 32 位整数输出 CSV 与 JSON 均要求唯一、非符号链接的本地路径默认拒绝覆盖需--force。流水线的三个关键行为拒绝缺失/非有限样本CSV 读取在 read_numeric_columns 中遇到na/nan等缺失 token 或非有限值即报错而不是静默插值——要求先分段或声明有界插值策略报告观测到的 schema 与校正类别输出output_schema_observedinfo 键与信号列、artifact_correction算法、类别计数、校正事件总数、未校正峰数按时长与搏数门控 HRV 域时间域要求 ≥20 拍且提示短于常规 5 分钟窗口L198-L212频域要求 ≥120 秒且 ≥50 拍否则跳过并警告不要解读 VLF/ULFL213-L230非线性域要求 ≥100 拍L231-L243。这些门控与 hrv.md 的 Recording duration 原则一致五分钟后是常规短期 HRV 参考窗口ULF 属长时记录指标短记录解读 VLF 不安全。合成信号可用 generate_synthetic.py 生成确定性夹具单元标注为arbitrary_unit报告明确physiological_validation: False也可直接让流水线走--synthetic内部调用nk.ecg_simulate。安全与测试保障所有 CLI helperinspect_signal.py、ecg_hrv_pipeline.py、eda_pipeline.py、plan_epochs.py、validate_multimodal.py、generate_synthetic.py由 tests/neurokit2/test_scripts.py 守护AST 级检查禁止eval/exec/__import__/compile及网络相关导入aiohttp、httpx、requests、socket、urllib等也禁止.pklL56-L97--help在-S不带 site-packages下即可工作保证无 NeuroKit2 依赖也能查看用法L99-L107严格本地 IO拒绝 URL、符号链接、重复 JSON 键与非有限 JSONL122-L153固定运行时冒烟测试断言neurokit2_version 0.2.13且输出 schema 包含ECG_QualityL328-L368。这些约束源于 skills/neurokit2/scripts/_common.py 的共享边界定义MAX_CSV_BYTES 64 MiB、MAX_ROWS 500_000、MAX_CHANNELS 64、MAX_CELL_CHARS 4096输出以0o600权限原子写入保证可复现性与隐私安全。落地检查清单结合 ecg_cardiac.md 与 hrv.md 的 Analysis/report checklist一份合格的心电处理报告至少应包含包版本固定 0.2.13与观测到的输出 schemaECG 来源、传感器/位置、采样、时钟、单位与原始数据访问方式时长、可用时长、搏数与排除记录峰值检测器、质量方法、异位/伪影标准与校正百分比RRI/NN/PRV 术语的严格区分校正后的 RR 不得直接改标为 NN频域 PSD/插值/去趋势/频带/归一化设置呼吸测量与速率/深度背景涉及 RSA 时预设指标与多重比较控制无诊断、监护或医疗设备声明除非另行独立验证。把本指南的 API 用法、schema 观测与流水线门控结合起来即可在科研项目中获得一套可审计、可复现、方法意识明确的 NeuroKit2 ECG 处理基线。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考