neurokit2

NeuroKit2

范围与证据截止时间

在使用 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 数据／模板下载作为明确且经过校验和验证的研究输入进行准备。可复现的研究中不要安装不断变动的开发分支。

必需的数据约定

处理前，请记录：

1. 信号标识及传感器／通道配置；
2. 原生采样率（Hz）和物理单位（或明确指定为 arbitrary_unit）；
3. 时钟、时间戳起点、漂移校正及同步证据；
4. 极性／方向以及采集端滤波／增益；
5. 缺失样本、间断、饱和、平线、运动及注释；
6. 事件起始位置使用从零开始的样本索引还是秒；
7. 计划的预处理顺序、方法、参数、排除项及输出；以及
8. 后续统计分析中防止数据泄漏所需的参与者级分组。

切勿根据列名推断单位。不要默默地将样本视为毫秒、伏特、微西门子或任意单位。

核心工作流

1. 转换前先检查

python skills/neurokit2/scripts/inspect_signal.py \
  --input recording.csv --root . --deidentified \
  --columns ECG,RSP,EDA --time-column time_s \
  --units ECG=mV,RSP=a.u.,EDA=uS

检查器的输出范围有限，不会输出任何行值或路径。滤波前，请处理非单调时间、重复样本、间隙、非有限值、平线段和采样率不一致的问题。

2. 保持预处理顺序

采用以下默认推理顺序，并根据采集情况和引用的方法进行调整：

1. 保留不可变的原始信号和标注；
2. 验证时间基准、单位、极性、削波、间断和伪迹；
3. 在较长间断处进行分段；只有在明确声明策略的情况下，才对较短间断进行插值；
4. 以原生采样率进行特定模态的清理；
5. 检测峰值／起始点或分解成分；
6. 检查质量输出和原始信号叠加图；
7. 仅在记录分类并进行敏感性检查的情况下修正峰值；
8. 派生速率／特征；
9. 将连续模态对齐到明确声明的公共时间网格；以及
10. 将事件索引映射到该网格，进行分段、基线处理和分析。

不要将二进制标记或峰值索引数组作为普通连续信号进行重采样。 应将其时间戳映射到目标网格。滤波和插值可能产生边缘伪迹和虚假的精确度；应保留填充、缺失和剔除区域的掩码。

3. 将架构视为运行时观测结果

返回的列取决于 NeuroKit2 版本、函数、方法、信号可用性和分析模式。切勿声称某个列清单适用于所有情况。

signals, info = nk.ecg_process(ecg, sampling_rate=250)
observed_schema = {
    "columns": list(signals.columns),
    "info_keys": sorted(info),
}

保存观测到的架构，以及软件包版本、方法参数、采样率和质量／排除摘要。参考文件列出了针对 0.2.13 验证过的默认架构，但不保证每种方法都如此。

当前模式

ECG、修正后的峰值和考虑时长的 HRV

在稳定版 0.2.13 中，ecg_process() 会进行清理、使用 correct_artifacts=True 检测 R 峰、计算速率、采用默认的 averageQRS 质量评估、进行 DWT 描记并确定阶段。

signals, info = nk.ecg_process(ecg, sampling_rate=250, method="neurokit")
time_hrv = nk.hrv_time(info, sampling_rate=250)

检查 ECG_R_Peaks_Uncorrected 和 ECG_fixpeaks_*；修正后的序列不会自动成为有效的 NN 序列。对于频域／非线性 HRV，应满足特定指标的时长和心搏数量要求。5 分钟是传统的短时参考；ULF 是长时记录指标，而根据短时记录解释 VLF 并不可靠。不要将 LF/HF 解读为直接的交感－迷走神经平衡指标。PPG 脉率变异性不能与 ECG HRV 互换。

使用有界流水线：

python skills/neurokit2/scripts/ecg_hrv_pipeline.py \
  --synthetic --sampling-rate 250 --duration 300 \
  --domains time,frequency,nonlinear

明确分解方式的 EDA

稳定版的默认设置 eda_process(method="neurokit") 使用高通紧张／相位分解，而不是 cvxEDA。应明确选择并报告分解方式：

clean = nk.eda_clean(eda, sampling_rate=100, method="neurokit")
components = nk.eda_phasic(clean, sampling_rate=100, method="highpass")
markers, info = nk.eda_peaks(
    components["EDA_Phasic"],
    sampling_rate=100,
    method="neurokit",
    amplitude_min=0.1,
)

对于 neurokit／kim2004，amplitude_min 相对于检测到的最大响应值，而不是绝对微西门子阈值。cvxEDA 需要可选依赖 cvxopt。

python skills/neurokit2/scripts/eda_pipeline.py \
  --synthetic --sampling-rate 100 --duration 60 \
  --phasic-method highpass --peak-method neurokit

事件、分段和基线

events_find() 报告从零开始的样本起始位置；时长／间隔参数以样本为单位。epochs_create() 的分段边界以秒为单位。

events = nk.events_find(trigger, threshold=0.5, duration_min=2)
epochs = nk.epochs_create(
    signals,
    events,
    sampling_rate=100,
    epochs_start=-0.2,
    epochs_end=0.8,
    baseline_correction=False,
)

应先规划精确到样本的窗口：

python skills/neurokit2/scripts/plan_epochs.py \
  --events 1000,2500,4000 --event-unit samples \
  --sampling-rate 100 --recording-samples 5000 \
  --epoch-start -0.2 --epoch-end 0.8 \
  --baseline-start -0.2 --baseline-end 0

在 0.2.13 中，分段切片不包含结束位置，但生成的浮点时间索引包含 epochs_end。内置基线校正会从分段起始位置到 t=0，用分段均值进行减法；如果预先指定的基线范围更窄，请使用手动校正。边界分段会填充数据，且可能包含 NaN。应在分析前决定是丢弃、填充还是报错。

RSA 和多模态处理

bio_process() 假定所有输入已具有相同的采样率和对齐方式。它不会重采样、同步、估算漂移或创建嵌套的模态字典；其 info 输出是扁平的。长度不等的输入会按索引拼接，并可能引入 NaN。只有在存在同步的 ECG 和 RSP 时才会添加 RSA。

调用前应验证严格的本地清单：

python skills/neurokit2/scripts/validate_multimodal.py \
  --manifest streams.json --root . --deidentified

独立完成各模态的质量控制和对齐后：

bio_signals, bio_info = nk.bio_process(
    ecg=ecg_aligned,
    rsp=rsp_aligned,
    eda=eda_aligned,
    sampling_rate=common_rate,
)
rsa_summary = nk.hrv_rsa(
    bio_signals,
    bio_signals,
    rpeaks=bio_info,
    sampling_rate=common_rate,
    continuous=False,
)

汇总 RSA 是一个字典；在经过验证的默认工作流中，continuous=True 会返回包含 RSA_P2T 和 RSA_Gates 的 DataFrame。应同步记录呼吸，并报告其速率／深度／背景信息；RSA 不是直接且脱离背景的迷走神经张力指标。

复杂度函数会返回数值及元数据

0.2.13 中的大多数复杂度函数都会返回 (value, info)。便捷函数也会返回两个对象：

features, details = nk.complexity(signal)  # default which="makowski2022"
sampen, sampen_info = nk.entropy_sample(signal)
dfa, dfa_info = nk.fractal_dfa(signal)

默认的便捷选项并非“所有指标”。复杂度估计会受到长度、平稳性、归一化、延迟、维度、容差、尺度和实现方式的影响。请预先定义这些参数，并进行敏感性分析和替代数据分析。

捆绑的命令行辅助工具

所有辅助工具都会拒绝 URL、路径遍历和符号链接；限制字节数、行数和通道数；除非指定 --force，否则拒绝覆盖；使用延迟加载的科学计算导入，因此无需安装 NeuroKit2 也能运行 --help；从不使用 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 skills/neurokit2/scripts/generate_synthetic.py \
  --output synthetic.csv --root . --duration 30 \
  --sampling-rate 250 --seed 42

安全说明

示例和辅助工具均不使用 Python 的 eval() 或 exec()。NeuroKit2 中的 eeg_*、events_* 和 *_eventrelated() 等名称都是普通的库调用。如果静态扫描器根据子字符串报告 eval/exec 模式，请检查具体代码行；只有在确认不存在动态执行后，才能将其记录为扫描器误报。

参考资料

只阅读与模态或决策相关的文件： 以下所有捆绑的 Markdown 路径均位于 references/ 下；此技能没有 templates/ 或 assets/ 参考路径。

文件	内容
references/signal_processing.md	滤波、间隙、重采样、峰值、PSD、模式
references/epochs_events.md	事件索引、分段边界、基线
references/ecg_cardiac.md	ECG 处理、质量评估、波形标注、峰值校正
references/hrv.md	HRV/RSA 输入、持续时间、异位搏动、解读
references/eda.md	清理、分解、SCR 检测
references/emg.md	EMG 清理、幅度、激活
references/eog.md	EOG 极性、MNE 默认值、眨眼特征
references/eeg.md	EEG/MNE 辅助工具、功率、质量控制、微状态
references/ppg.md	PPG 方法、质量语义、PRV 局限性
references/rsp.md	呼吸极性、频率、RRV/RVT/RAV
references/bio_module.md	多模态对齐和 bio_* 模式
references/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：构建和排查 TorchDrug 0.2.1 工作流，涵盖分子图、属性预测、自监督预训练、分子生成……