NeuroKit2 是一个研究与教育用途的生物信号工具箱。本技能用于以方法感知、可复现的方式开展生理时间序列研究，涵盖预处理、事件/间期分析与多模态对齐。资料快照检查于 2026-07-23，对照稳定版 PyPI 0.2.13（2026-03-02 发布）、Python 元数据（>=3.10；分类器 3.10–3.14）与 wheel 依赖、GitHub 发布说明/标签、NEWS.rst、v0.2.13 标签源码、官方 API 页面/示例（在线站点标识为 0.2.13.dev214），以及固定 0.2.13 的运行时签名与合成输出模式。在线文档可能领先于稳定 wheel；可复现工作应优先使用固定运行时，若参考开发文档需同时注明两个版本。
边界 NeuroKit2 是研究与教育工具箱。不得将其输出呈现为：诊断、治疗建议、患者监测决策或警报；医疗器械的验证、认证或监管证据；或证明某一生理构念在新传感器、协议、环境、人群或疾病组中被有效测量。需针对预期研究验证采集硬件、电极/光极放置、单位、采样与时钟精度、预处理、检测器/分解方法、人群、任务与结局。保留原始数据与可审计的排除日志。仅使用去标识化的本地文件；不得将 PHI 放入提示、日志、示例或捆绑夹具。
可复现安装 uv pip install "neurokit2==0.2.13" 如需可选功能，创建 uv 项目，仅添加实际需要的包并固定到经审查的确切版本，在 uv sync --locked 前提交/审查生成的 uv.lock。NeuroKit2 提供上游 full extra，但本技能有意不在自动化工作流中安装该浮动传递依赖集。可选能力可能需要 MNE、cvxopt、Plotly、PyEMD、pyRQA、Pillow、OpenCV 或文件读取器。随分析记录解析后的环境。将任何 MNE 数据/模板下载作为显式、带校验和的研究输入进行准备。可复现研究不要安装移动的开发分支。
必需的数据契约 处理前记录：信号身份与传感器/通道配置；原生采样率（Hz）与物理单位（或显式 arbitrary_unit）；时钟、时间戳原点、漂移校正与同步证据；极性/方向与采集侧滤波器/增益；缺失样本、不连续、饱和、平线、运动与标注；事件起点是基于零的样本索引还是秒；计划中的预处理顺序、方法、参数、排除与输出；以及防止后续统计泄漏所需的参与者级分组。切勿从列名推断单位。不要静默地把样本当作毫秒、伏特、微西门子或任意单位。
核心工作流
- 变换前先检查：使用 scripts/inspect_signal.py 进行有界检查，不输出行值或路径。在滤波前解决非单调时间、重复样本、间隙、非有限值、平坦段与采样率不一致。
- 保留预处理顺序：默认推理顺序为——保留不可变原始信号与标注；验证时间基准、单位、极性、削波、间隙与伪迹；在长间隙处分段，仅在声明策略下插值短间隙；在原生采样率下进行模态特定清洗；检测峰/起点或分解成分；检查质量输出与原始叠加；仅以记录类别与敏感性检查校正峰；导出速率/特征；在声明的公共时间网格上对齐连续模态；将事件索引映射到该网格、分段、基线并分析。不要将二值标记或峰索引数组当作普通连续信号重采样，应将其时间戳映射到目标网格。滤波与插值可能产生边缘伪迹与虚假精度；保留填充、缺失与拒绝区域的掩码。
- 将模式视为运行时观测：返回列取决于 NeuroKit2 版本、函数、方法、信号可用性与分析模式。切勿声称某一列列表是通用的。示例：signals, info = nk.ecg_process(ecg, sampling_rate=250)，随后记录 observed_schema（列与 info 键）。将观测到的模式与包版本、方法参数、采样率及质量/排除摘要一并持久化。参考文件列出 0.2.13 已验证的默认模式，而非对所有方法的保证。
当前模式 ECG、校正峰与时长感知 HRV：在稳定 0.2.13 中，ecg_process() 执行清洗、带 correct_artifacts=True 的 R 峰检测、速率、默认 averageQRS 质量、DWT 描记与相位。检查 ECG_R_Peaks_Uncorrected 与 ECG_fixpeaks_*；校正序列不自动等于有效 NN 序列。频率/非线性 HRV 需满足指标特定的时长与心搏数要求。五分钟是常规短期参考；ULF 是长记录指标，从短记录解释 VLF 不安全。不要将 LF/HF 解释为直接的自主神经平衡。PPG 脉率变异性与 ECG HRV 不可互换。 EDA 显式分解：稳定默认 eda_process(method="neurokit") 使用高通 tonic/phasic 分解，而非 cvxEDA。需显式选择并报告分解。对 neurokit/kim2004，amplitude_min 相对于检测到的最大响应，不是绝对微西门子阈值。cvxEDA 需要可选 cvxopt。 事件、分段与基线：events_find() 报告基于零的样本起点；duration/spacing 参数以样本为单位。epochs_create() 的 epoch 限值以秒为单位。在 0.2.13 中 epoch 切片为末端排除，但生成的浮点时间索引包含 epochs_end。内置基线校正从 epoch 起点到 t=0 减去 epoch 均值；更窄的预设基线需手动校正。边界 epoch 会被填充且可能含 NaN。分析前决定丢弃/填充/报错。 RSA 与多模态处理：bio_process() 假定所有输入已共享同一采样率与对齐。它不重采样、不同步、不估计漂移、不创建嵌套模态字典；其 info 输出是扁平的。长度不等时按索引拼接可能引入 NaN。仅当存在同步的 ECG 与 RSP 时才添加 RSA。调用前用 scripts/validate_multimodal.py 验证严格的本地清单。摘要 RSA 是字典；continuous=True 在已验证默认工作流中返回含 RSA_P2T 与 RSA_Gates 的 DataFrame。需共同记录呼吸并报告其速率/深度/情境；RSA 不是直接、无情境的迷走张力测量。 复杂度返回值与元数据：0.2.13 中多数复杂度函数返回 (value, info)。便捷函数也返回两个对象。默认便捷选择不是“所有度量”。复杂度估计对长度、平稳性、归一化、延迟、维度、容差、尺度与实现敏感。需预定义并运行敏感性/替代分析。
捆绑命令行辅助工具 所有辅助工具拒绝 URL、路径遍历与符号链接；限制字节/行/通道；除非 --force 否则拒绝覆盖；使用惰性科学导入使 --help 无需 NeuroKit2 即可工作；从不使用 pickle；产生确定性 JSON/CSV。真实数据命令需要 --deidentified。辅助工具包括：scripts/generate_synthetic.py（无依赖确定性 CSV 夹具）、scripts/inspect_signal.py（有界 CSV/时间/间隙/平线检查）、scripts/ecg_hrv_pipeline.py（固定 ECG、质量、峰校正、HRV 工作流）、scripts/eda_pipeline.py（显式清洗、分解、SCR 工作流）、scripts/plan_epochs.py（样本精确的事件、边界、基线规划器）、scripts/validate_multimodal.py（严格的单位/速率/时钟/对齐模式校验器）。
安全说明 任何示例或辅助工具都不使用 Python eval() 或 exec()。NeuroKit2 名称如 eeg_、events_ 与 *_eventrelated() 是普通库调用。若静态扫描器基于子串报告 eval/exec 模式，检查确切行并在确认不存在动态执行后记录为扫描器误报。
参考文件 仅阅读模态或决策所需的文件。所有捆绑 Markdown 路径位于 references/ 下；本技能没有 templates/ 或 assets/ 参考路径。文件包括：signal_processing.md（滤波器、间隙、重采样、峰、PSD、模式）、epochs_events.md（事件索引、epoch 边界、基线）、ecg_cardiac.md（ECG 处理、质量、描记、峰校正）、hrv.md（HRV/RSA 输入、时长、异位搏动、解释）、eda.md（清洗、分解、SCR 检测）、emg.md（EMG 清洗、幅度、激活）、eog.md（EOG 极性、MNE 默认、眨眼特征）、eeg.md（EEG/MNE 辅助、功率、QC、微状态）、ppg.md（PPG 方法、质量语义、PRV 局限）、rsp.md（呼吸极性、速率、RRV/RVT/RAV）、bio_module.md（多模态对齐与 bio_* 模式）、complexity.md（元组返回、参数敏感性、RQA）。
主要来源检查于 2026-07-23：PyPI 0.2.13、官方文档、API 索引、GitHub 发布、Makowski et al. (2021) NeuroKit2、Pham et al. (2021) HRV 教程、Makowski et al. (2022) 复杂度比较、SPR 指南索引、Quigley et al. (2024) HR/HRV 指南。相关技能：torchdrug。