NeuroKit2 HRV 与 RSA 实操指南基于 0.2.13 的区间序列、频域分析与可复现报告规范【免费下载链接】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 技能 的 HRV/RSA 参考文档 hrv.md 为主体系统讲解基于 NeuroKit2 0.2.13 稳定版构建可复现的心率变异性Heart-rate Variability, HRV与呼吸窦性心律不齐Respiratory Sinus Arrhythmia, RSA分析工作流。你将掌握RR/NN/PP 区间序列的正确定义与输入格式、hrv_time/hrv_frequency/hrv_nonlinear/hrv四类函数的输出 schema 观测方法、异位搏动与伪迹校正策略、频域参数的选择陷阱、PPG 衍生变异性PRV的边界以及 RSA 分析的前置条件并结合仓库内可运行管线与测试学会把版本、时长、校正比例等元数据写进报告避免把 HRV 指标过度解释为诊断或迷走张力证据。从区间序列开始RR、NN 与 PP 的严格区分HRV 分析的第一步不是调用函数而是确立你手上到底是什么区间。NeuroKit2 0.2.13 相关的分析实践中必须严格区分三类序列依据 hrv.mdRR / RRI相邻 R 峰之间的间隔是峰值检测的直接产物与是否为窦性心律无关NN仅由被判定为正常窦性搏动normal sinus beats的搏动间隔构成是正常-正常区间PP / PRV外周脉搏波PPG峰值之间的间隔。核心红线不要自动把经过校正的 RR 或 PPG 区间重新标注为 NN。校正后的区间依然只是修正过的 RR只有当你确实通过波形审查或相应标注识别出了非窦性/异位搏动才有资格称 NN。与此同时原始波形、原始峰值、校正后峰值、被排除的片段、校正类别以及区间单位都必须完整保留作为可审计的中间产物。这一要求与仓库中 signal_processing.md 的峰值校正章节相互印证signal_fixpeaks()的 Kubios/Lipponen–Tarvainen 路径只负责修正峰位它并不能自动识别异位搏动文档明确要求保留原始与校正峰值、按伪迹类别的计数、受影响的时间范围、以及校正与否两套结果并且不要称校正后的搏动间隔为 normal-to-normal除非研究确实识别了非窦性/异位搏动。NeuroKit2 接受的输入形态根据 hrv.mdHRV 函数可接受的输入包括一个包含峰值样本索引的列表/数组来自ecg_peaks()、ppg_peaks()、ecg_process()或bio_process()的 marker/info 对象一个包含RRI毫秒与RRI_Time秒键的字典。无论哪种形态都必须传入峰值索引所依托的连续信号的采样率sampling_rate否则时间换算无从谈起。这也是 SKILL.md 中数据契约的要求记录原生采样率Hz与物理单位绝不从列名臆测单位。当前函数与 schema把输出当作运行时观测hrv.md 给出了 0.2.13 稳定版的四个核心入口time nk.hrv_time(peaks, sampling_rate250) frequency nk.hrv_frequency(peaks, sampling_rate250) nonlinear nk.hrv_nonlinear(peaks, sampling_rate250) all_domains nk.hrv(peaks, sampling_rate250)四个函数都返回单行 DataFrame。hrv()会拼接可用的域domains并且当输入包含已处理的呼吸数据时还会附加 RSA 结果。列集合取决于数据长度、kwargs、可用模态以及版本——因此文档给出的 0.2.13 钉定观测值只能作为该版本的参考快照而不是通用承诺。钉定 0.2.13 的观测快照hrv_time()在钉定探测中返回 25 列包括HRV_MeanNN、HRV_SDNN、HRV_RMSSD、HRV_SDSD、HRV_CVNN、HRV_CVSD、稳健区间摘要、HRV_pNN50、HRV_pNN20、HRV_HTI与HRV_TINN。长片段指标SDANN*、SDNNI*在时长不足时可为 NaN。hrv_frequency()在默认探测中恰好返回HRV_ULF、HRV_VLF、HRV_LF、HRV_HF、HRV_VHF、HRV_TP、HRV_LFHF、HRV_LFn、HRV_HFn、HRV_LnHF。hrv_nonlinear()返回 Poincaré、不对称性、碎片化fragmentation、DFA/MFDFA、熵/分形、Lempel–Ziv 与符号动力学symbolic dynamics等列0.2.13 稳定版新增了默认的HRV_Symbolic_EqualProb4_*特征。不要硬编码一份完整的 HRV 列清单。正确做法是持久化list(result.columns)并且只映射预先指定prespecified的输出。这与仓库测试 test_scripts.py 和管线 ecg_hrv_pipeline.py 的约定完全一致管线报告中的output_schema_observed字段记录了info_keys与signal_columns把观测到的 schema作为可复现产物随报告一起保存。测试test_pinned_version_and_synthetic_ecg_pipeline也断言了ECG_Quality出现在信号列中验证了 schema 是运行时事实而非静态承诺。为什么 schema 会变化列集合随以下因素漂移记录时长长片段指标需要足够时长、传入的 kwargs例如hrv_frequency的psd_method、可用的模态是否含呼吸数据以追加 RSA、以及 NeuroKit2 的版本开发版文档可能领先于稳定 wheel。因此任何报告都必须同时给出包版本、方法参数、采样率与质量/排除摘要——这正是 SKILL.md 中把 schema 当作运行时观测一节的要求。单位与区间辅助函数时域指标适用毫秒ms频域功率基于毫秒区间计算因此常见单位为 ms² 派生单位但归一化与估计器设置会改变其解释含义。当你的数据来自外部设备以区间而非峰值为形态时hrv.md 提供了两个转换/处理辅助函数processed_rri, processed_time, interpolation_rate nk.intervals_process( rri_ms, intervals_timetime_s, interpolateTrue, interpolation_rate4, detrendNone, ) peaks nk.intervals_to_peaks(rri_ms, sampling_rate1000)intervals_process()返回三个对象毫秒单位区间、秒单位时间戳、插值率。它可以在交给 HRV 频域分析前对区间做插值与可选去趋势。intervals_to_peaks()返回整数峰值索引并会构造第一个峰值作为基准。在转换前必须先核实外部设备对区间的定义以及是否丢拍了——例如有的设备区间以峰值到峰值定义有的以起搏到起搏定义直接转换会引入系统性偏差。intervals_process(..., interpolation_rate4)接近 Kubios 的常用插值选择已插值区间或 Lomb–Scargle 场景应设为None详见下文频域节。记录时长指标特定、保守规划时长要求是指标特定、人群特定、协议特定、估计器特定的不存在一把通用尺子。文档给出的保守规划原则五分钟是标准的短期 HRV 窗口惯例RMSSD 可以在更短窗口上计算但超短ultra-short估计必须有端点与人群特定的信度/效度证据频谱片段应包含所解释最低频率的足够周期数五分钟是常规 LF/HF 短期分析的实用参考不要从短记录解释 ULF它惯例上与长记录常为 24 小时关联短记录中的 VLF 生理学解释不确定熵、DFA、MFDFA、相关维数与 RQA 需要足够的搏动数才能稳定估计默认值返回了一个数字并不等于样本量足够。同时不要在没有验证策略的情况下比较不同时长估计出的指标报告应写排除后的精确可用时长与搏动数而不是名义采集时长。仓库中的 ecg_hrv_pipeline.py 把上述原则落实为可执行的时长/搏动数门槛main()中逐域 gatingHRV 域保守门槛触发警告的条件time至少 20 个检测搏动少于 20 搏动则跳过时长 300s 时提示短于惯用 5 分钟短期记录需要指标特定验证frequency至少 120 秒且 50 个检测搏动不满足则跳过时长 300s 时提示不要解释 VLF/ULF并需论证频带nonlinear至少 100 个检测搏动不满足则跳过并提示许多熵/分形指标需要更多搏动这些门槛是该管线的保守设计选择源码注释明确写了 in this conservative CLI不是 NeuroKit2 本身的硬性限制但恰好呼应了参考文档默认返回数字不等于样本充足的告诫。测试 test_scripts.py 用 30 秒、250 Hz 合成 ECG 验证了detected_r_peaks 20的时域通路可运行。异位搏动与伪迹策略hrv.md 给出六步策略检查 ECG/PPG 质量与峰值叠加图raw overlay审查 tachogram逐搏间期图与区间直方图尽可能把非窦性搏动与检测器错误分开识别报告原始与校正后的搏动数及百分比按预先指定的排除规则限制插值/校正量在合理备选校正方案下重复关键分析敏感性分析。关键事实0.2.13ecg_process()在稳定版中会自动请求伪迹校正correct_artifactsTrue。如果这不是你预定的策略就必须显式调用ecg_clean()与ecg_peaks()自行控制。参考 ecg_cardiac.md 中的对应写法clean nk.ecg_clean(ecg, sampling_rate250, methodneurokit) markers, peak_info nk.ecg_peaks( clean, sampling_rate250, methodneurokit, correct_artifactsFalse, )校正使用的算法为 Lipponen–Tarvainen通过ecg_process(correct_artifactsTrue)管线在报告中以ECG_fixpeaks_ectopic、ECG_fixpeaks_missed、ECG_fixpeaks_extra、ECG_fixpeaks_longshort四类计数呈现校正分布见 ecg_hrv_pipeline.py 的_artifact_counts。同时检查ECG_R_Peaks_Uncorrected与ECG_fixpeaks_*——校正后的序列不会自动成为有效的 NN 序列。重校正会制造平滑的 HRV过度异位、脱离或运动片段可能需要排除整段而非插值。管线在检测到任何校正事件时都会追加警告R-peak corrections were applied by ecg_process(); inspect the raw trace, uncorrected peaks, and correction categories正是对这一风险的显式提醒。频域分析参数与解读陷阱0.2.13 稳定版签名hrv.mdhrv_frequency( peaks, sampling_rate1000, ulf(0, 0.0033), vlf(0.0033, 0.04), lf(0.04, 0.15), hf(0.15, 0.4), vhf(0.4, 0.5), psd_methodwelch, normalizeTrue, interpolation_rate100, ... )实操要点默认interpolation_rate100设interpolation_rate4可近似 Kubios 常用插值选择已插值区间或 Lomb–Scargle 场景设为None报告中必须记录去趋势detrending、插值、PSD 方法、窗/阶数、频带与归一化设置。从源码层面看hrv_frequency依赖底层signal_psd()。参考 signal_processing.md0.2.13 中signal_psd()返回一个 DataFrameWelch 探测观测到Frequency与Power两列不要把它解包成(psd, frequencies)二元组normalizeTrue是按最大 PSD 功率缩放并非物理标定需要绝对谱单位时应使用normalizeFalse并从采集与估计器推导单位。这些底层行为直接决定了hrv_frequency输出的解释方式。解读红线不要把HRV_LFHF直接解读为交感-迷走平衡。LF 含有混合影响HF 依赖呼吸频率与深度且会漏掉默认 0.15–0.4 Hz 频带之外的呼吸变异。这与 SKILL.md 的明确告诫一致不要将 LF/HF 解释为直接的交感-迷走平衡。PPG 衍生变异性PRV不可与 ECG HRV 互换PPG 脉冲时序包含射血前期pre-ejection与脉搏传递pulse-transit效应并随部位、血管状态、姿势、温度、运动、接触压力与传感器设计而变化。因此结果必须标注为PRV / PPG 衍生 HRV必须针对端点、条件、部位与人群与同步 ECG 做验证静息状态的一致不能外推到运动或应激状态。SKILL.md 同样强调PPG 脉率变异性不可与 ECG HRV 互换。这条边界也呼应了仓库中 ppg.md 参考文件的存在意义——PPG 的质量语义与 PRV 限制是独立成章讨论的。RSA呼吸窦性心律不齐稳定版签名hrv_rsa( ecg_signals, rsp_signalsNone, rpeaksNone, sampling_rate1000, continuousFalse, windowNone, window_numberNone )使用同步的已处理 ECG 与呼吸 DataFrame 的推荐调用hrv.mdrsa nk.hrv_rsa( ecg_signals, rsp_signals, rpeaksecg_info, sampling_rate100, continuousFalse, )钉定观测摘要模式返回一个字典含 P2T 与 Gates 统计包括RSA_P2T_Mean、RSA_P2T_SD、RSA_P2T_NoRSA、RSA_PorgesBohrer以及 Gates 的 mean/SD/log 字段continuousTrue返回同长度 DataFrame含RSA_P2T与RSA_Gates两列。RSA 的前置条件必须全部满足共享时钟、采样网格以及明确的滞后/漂移策略有效的 R 峰与呼吸周期所选方法足够的周期/窗口数实测的呼吸频率及其背景信息报告 P2T/Gates 方法与所有窗口参数。在多模态场景下SKILL.md 提醒bio_process()假设所有输入已共享同一采样率与对齐它不会重采样、同步、估计漂移或创建嵌套模态字典不等长输入按索引拼接可能引入 NaN只有同时存在同步 ECG 与 RSP 时才追加 RSA。建议先用 validate_multimodal.py 校验严格的本地位点清单streams manifest再调用bio_process()——仓库测试test_multimodal_validator_detects_resampling_need正是验证了该校验器能在 ECG 100 Hz、RSP 50 Hz 这类不兼容场景下给出bio_process_direct_input_compatible False与警告防止未经对齐就计算 RSA。解读红线RSA/HF-HRV 常与心脏迷走调节相关但不是直接的、脱离情境的迷走张力测定。呼吸、活动、β-肾上腺素影响、年龄、姿势以及个体内 vs 个体间对比都会改变其解释。分析与报告检查清单hrv.md 给出了可直接复用的最终清单包版本与观测到的输出 schemaECG/PPG 来源、传感器/部位、采样、时钟、单位与原始数据可访问性时长、可用时长、搏动数与排除情况峰值检测器、质量方法、异位/伪迹判据与校正百分比RRI/NN/PRV 术语的正确使用PSD/插值/去趋势/频带/归一化记录呼吸测量与频率/深度背景预先指定的指标与多重比较控制在未单独验证前不得宣称诊断、监护或医疗器械能力。仓库对可复现的最后一道保障在安全层所有 scripts 拒绝 URL、路径穿越与符号链接限制字节/行/通道数非--force拒绝覆盖惰性导入科学包使--help无需安装 NeuroKit2 即可运行且绝不使用 pickle见 test_scripts.py 的SafetyAndManifestTests它静态断言脚本不含eval/exec/网络导入。这意味着你可以放心地把管线接入批处理工作流。在仓库中实操从文档到可运行证据要复现本文全部结论可依次执行以下仓库内资源安装钉定版本uv pip install neurokit20.2.13见 SKILL.md生成确定性合成 ECG 夹具generate_synthetic.py运行时长感知的 HRV 管线源码ecg_hrv_pipeline.pypython skills/neurokit2/scripts/ecg_hrv_pipeline.py \ --synthetic --sampling-rate 250 --duration 300 \ --domains time,frequency,nonlinear用真实去标识数据时补充--input、--column、--root . --deidentified并按需导出--signals-output与--output运行 test_scripts.py 中的PinnedNeuroKitSmokeTests验证钉定版本行为。每个关键结论时长门槛、校正类别、schema 观测、RSA 返回形态、安全约束都可以在上述源码与测试文件中直接核对从而保证你的 HRV/RSA 分析既能跑通、也经得起审阅。参考与核对范围本文所有事实基于仓库内以下文件核对均于 2026-07-23 对照 NeuroKit2 0.2.13 稳定版核心参考hrv.md、ecg_cardiac.md、signal_processing.md技能边界与安装SKILL.md可运行管线ecg_hrv_pipeline.py 与共享工具 _common.py测试证据test_scripts.py。参考文档所依据的行业背景包括 NeuroKit2 官方 HRV API/教程、Pham et al. (2021) 的 NeuroKit2 HRV 综述、Quigley et al. (2024) 的 SPR 心率/HRV 指南、ESC/NASPE Task Force (1996)、Berntson et al. (1997) 的解读性警示、Laborde et al. (2017) 的规划/报告建议以及 Grossman Taylor (2007) 的 RSA 警示。使用时请记住本文及该技能的输出仅用于研究与教学不能作为诊断、治疗建议、监护决策或医疗器械验证证据。【免费下载链接】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），仅供参考