企业官网建设流程全解析

NeuroKit2 EEG 与微状态分析实战指南：基于 scientific-agent-skills 的可复现科研流程

【免费下载链接】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

本指南围绕 skills/neurokit2/references/eeg.md 展开，系统讲解在 scientific-agent-skills 仓库的 neurokit2 技能（skill）中，如何正确使用 NeuroKit2 0.2.13 的 EEG 辅助函数完成功率分析、坏通道筛查、重参考、源重建与微状态（microstate）分割，并给出与之配套的可复现安装、数据契约与结果报告规范。读完本文，你将掌握 NeuroKit2 EEG 函数族的精确签名与返回结构、Microstate 输出的字段语义，以及如何与 MNE 分工构建端到端且可审计的 EEG 研究流程。

一、范围界定：NeuroKit2 在 EEG 工作流中的位置

NeuroKit2 并没有提供类似 ECG/EDA 的eeg_process()端到端管线。从 skills/neurokit2/references/eeg.md 的核对结论看，它只提供一组精选的 EEG 辅助能力：

• 频段功率计算（eeg_power）
• 坏通道统计筛查（eeg_badchannels）
• 重参考、全局场势（GFP）与相异性（eeg_rereference、eeg_gfp、eeg_diss）
• 需要 MNE 的对象辅助与源重建（eeg_source、eeg_source_extract）
• 微状态分割与指标（microstates_*系列）

因此完整的数据采集与预处理工作流（滤波、坏段标记、ICA 等）应由MNE 或其他经过验证的 EEG 框架承担，NeuroKit2 负责特征、质检与微状态层面。原文档特别强调：进行任何变换和坏段决策时都要逐条记录（every transform and bad-segment decision），这与该 skill 整体的"可复现、可审计"设计一脉相承——skills/neurokit2/SKILL.md 中同样要求"保存原始数据和可审计的排除日志"。

1.1 输入数据形状契约（最易踩坑）

对于 NumPy 数组输入，NeuroKit2 的 EEG 函数期望的形状是：

(channels, time_samples)

即第一维是通道、第二维是时间样本。不要静默地传入(time, channels)——这会直接导致按通道计算功率、GFP、微状态聚类时语义完全错位。同时必须保留并记录：

• 通道名称与顺序；
• 电极布局（montage）；
• 参考电极方案（reference）；
• 传感器位置；
• 物理单位（MNE 中通常为伏特）；
• 采样率；
• 坏通道/坏段标注。

从 skills/neurokit2/references/signal_processing.md 可以推断，该 skill 对其他生理信号同样强调"先建立信号契约再变换"，EEG 通道元数据正是这种契约在脑电场景下的具体化。

二、频段功率分析：eeg_power()

频段功率是最常用的 EEG 特征。稳定版本的正确调用方式如下：

power = nk.eeg_power( eeg_channels_by_time, sampling_rate=250, frequency_band=["Gamma", "Beta", "Alpha", "Theta", "Delta"], )

两个值得注意的细节：

1. 参数名是单数frequency_band，不是frequency_bands。传错参数名在 0.2.13 中会报TypeError。
2. 锁定在 0.2.13 的运行环境探测结果显示，返回的 DataFrame每通道一行，列结构为：

Channel, Gamma, Beta, Alpha, Theta, Delta

即首列是通道标识，随后每列对应一个请求频带的功率值。

官方文档中列出的标准命名频带及其边界为：

此外还提供额外的子频带划分。关键认知：频带边界是约定（conventions），不是普适生理学事实——不同文献、不同分析管线对边界定义并不统一。因此在任何研究报告或论文中，都必须明确写出：

• 使用的精确频带边界；
• PSD（功率谱密度）估计参数（估计器、窗函数、分段长度等）；
• 参考方案；
• 伪迹处理方式；
• 是绝对功率还是相对归一化功率；
• 可用的有效数据时长。

这与 skills/neurokit2/references/signal_processing.md 中对signal_psd()的建议一致：normalize=True只是按 PSD 最大值缩放，并非物理标定，需要绝对频谱单位时应保持normalize=False并从采集与估计器推导单位。

三、坏通道统计筛查：eeg_badchannels()

坏通道的初步筛选可以借助统计指标：

bads, channel_info = nk.eeg_badchannels( eeg_channels_by_time, bad_threshold=0.5, distance_threshold=0.99, show=False, )

返回约定：

• 返回顺序是一个列表加一个 DataFrame（bads为坏通道列表，channel_info为逐通道统计信息表），解包顺序不能颠倒。
• 0.2.13 锁定环境下观测到的信息表字段包含：

SD, Mean, MAD, Median, Skewness, Kurtosis, Amplitude, 区间边界（interval bounds）, n_ZeroCrossings, Bad

即标准差、均值、中位数绝对偏差、中位数、偏度、峰度、振幅、区间边界、过零次数以及最终的Bad标记列。

必须强调，这是一个统计筛查器，不是普适的拒绝规则。被标记为 bad 的通道是否真正剔除，还需要结合：

• 原始波形目检；
• 电极布局与桥接（bridging）情况；
• 工频噪声（line noise）与漂移；
• 通道所在位置及其与研究任务、实验条件的相关性。

同时在拟合阈值时不能泄漏组别/条件的结果（fit thresholds without leaking group/condition outcomes）——即阈值选取不能使用后续要检验的分组信息，这与仓库测试中强调的"避免阈值调参作用于被检验的效应"（见 skills/neurokit2/references/epochs_events.md 的 Trial QC 一节）是同一原则。

四、重参考、全局场势与相异性

微状态分析和拓扑特征分析通常需要先重参考、再计算全局场势：

rereferenced = nk.eeg_rereference(eeg_channels_by_time, reference="average") gfp = nk.eeg_gfp(rereferenced, method="l1") diss = nk.eeg_diss(rereferenced, gfp=gfp)

各函数的行为要点：

• eeg_rereference()：数组输入时返回数组；MNE 对象输入时返回 MNE 对象。默认/常用reference="average"平均参考。平均参考要求通道覆盖充分且坏通道处理得当，对于稀疏电极布局（sparse montages）并不自动适用——通道太少时平均参考会引入显著偏差。
• eeg_gfp()：NeuroKit2 中默认使用L1 范数计算全局场势，而文献中可能使用其他定义（如 L2）。因此报告中必须写明所用方法、标准化/归一化方式、平滑方式和参考方案。
• eeg_diss()：计算通道间相异性（dissimilarity），需要传入已计算好的gfp。

这些函数构成微状态分割前的标准前置步骤——微状态分析的典型流程正是在重参考后的数据上计算 GFP、以 GFP 峰值或阈值选取训练样本，再对拓扑进行聚类。

五、可选 MNE 依赖：安装与版本锁定

核心 NeuroKit2 安装不包含 MNE。0.2.13 中需要 MNE 才能使用的稳定函数包括：

• eeg_simulate()（已在锁定运行环境中确认）；
• mne_data()及各类 MNE 对象辅助函数；
• eeg_source()/eeg_source_extract()；
• mne_templateMRI()。

因此，凡是涉及 MNE 的 EEG 工作流，都必须单独添加可选依赖。本 skill 给出的可复现安装规范是：

uv pip install "neurokit2==0.2.13"

对于可选功能，应创建 uv 项目，只添加分析实际需要的包，且使用经过审阅的精确版本，提交并审阅生成的uv.lock后再执行：

uv sync --locked

原文档明确警告：不要在自动化工作流中直接安装上游浮动的fullextra，因为其依赖集合是变动的，无法保证可复现。skills/neurokit2/SKILL.md 中同样记录了"NeuroKit2 暴露了上游fullextra，但本 skill 刻意不在自动化工作流中安装这组浮动传递依赖"，可选能力可能涉及 MNE、cvxopt、Plotly、PyEMD、pyRQA、Pillow、OpenCV 或文件读取器等包。仓库测试 tests/neurokit2/test_scripts.py 中的test_pinned_version_and_synthetic_ecg_pipeline也验证了锁定版本 0.2.13 的一致性，而 skills/neurokit2/scripts/_common.py 中以NEUROKIT2_VERSION = "0.2.13"和PINNED_INSTALL常量把这一约束固化进了每个 CLI 帮助器。

另外需要注意：部分 MNE 辅助函数会从网络下载数据集/模板。下载行为、缓存路径、许可证、版本与校验和都应视为研究依赖项；在受限/离线工作流中，必须预先完成资源准备（provisioning），否则不应使用这些函数。

六、源重建（Source Reconstruction）：eeg_source()

稳定版本签名：

eeg_source(raw, src, bem, method="sLORETA", show=False, ...)

它要求调用方提供：

• MNE Raw 对象；
• 源空间（source space）；
• BEM/头部模型（boundary element model / head model）；
• 电极布局与电极位置；
• 适当的坐标配准（co-registration）。

配套的eeg_source_extract(stc, src, ...)根据分割（segmentation）返回区域时间序列（region time series）。

原文档对源重建给出了非常明确的使用边界：

• 模板 MRI 不能验证针对某个个体或某个群体的定位精度；
• 报告中必须交代坐标框架、数字化信息、头部/电导率模型、逆问题方法、正则化、噪声协方差、深度/方向选择、图谱以及不确定性；
• 不得将 NeuroKit2 的源估计用于诊断、手术规划或临床定位。

这与该 skill 总体的边界声明一致：NeuroKit2 是研究与教育工具箱，其输出不能作为诊断、治疗建议、监护决策或医疗设备验证证据。

七、微状态分析（Microstates）

微状态分析是 EEG 空间拓扑动态研究的核心方法。NeuroKit2 的microstates_*系列覆盖了从分割到指标计算的主要环节。

7.1 分割：microstates_segment()

out = nk.microstates_segment( eeg_channels_by_time, n_microstates=4, train="gfp", method="kmod", sampling_rate=250, n_runs=50, random_state=42, )

参数语义：

• n_microstates：期望的微状态数量（示例为 4）；
• train：训练样本选择策略（"gfp"表示基于 GFP 选取）；
• method：聚类算法。0.2.13 中稳定支持的方法包括kmod、kmeans、kmedoids、pca、ica、aahc；
• n_runs：聚类重复运行次数（提高初始化稳定性）；
• random_state：随机种子（保证可复现）。

0.2.13 锁定环境下观测到的返回字典包含以下键：

Microstates, Sequence, GEV, GEV_per_microstate, GFP, Polarity, Info, Info_algorithm

注意命名语义：

• 没有小写的maps、labels、gfp、gev这些键；
• Microstates存放的是各微状态的拓扑地图（maps）；
• Sequence是逐样本的类别指派（class assignment），即每个时间点属于哪个微状态。

GEV（Global Explained Variance，全局解释方差）与GEV_per_microstate是评估分割质量的核心指标，报告微状态结果时应一并给出。

7.2 数据准备与汇总指标

clean, train_indices, gfp, input_info = nk.microstates_clean( eeg_channels_by_time, sampling_rate=250, train="gfp", ) static = nk.microstates_static(out["Sequence"], sampling_rate=250) dynamic = nk.microstates_dynamic(out["Sequence"])

• microstates_clean()是一个工具函数：负责数组的归一化/标准化以及训练样本选择，返回(clean, train_indices, gfp, input_info)四元组。它并不实现完整的 EEG 伪迹处理管线，前置的滤波、坏段处理仍需在 MNE 中完成。
• microstates_static()需要分割结果中的Sequence与sampling_rate，产出静态指标。
• microstates_dynamic()只需Sequence，产出动态指标（转移概率、停留时长等）。

7.3 实验性分类与状态数选择

microstates_classify()在 0.2.13 中属于实验性功能，且必须传两个参数：

sequence, maps = nk.microstates_classify( out["Sequence"], out["Microstates"], )

它的分类结果依赖通道顺序，因此不能可靠替代"基于已定义电极布局的模板匹配"（template matching with a defined montage）。如果通道顺序在数据集之间不一致，分类结果会失真。

microstates_findnumber()返回二元组：

optimal_number, scores_dataframe = nk.microstates_findnumber(...)

即(最优状态数, 评分数据框)。原文档在这里给出一条重要的统计警示：如果用同一份数据集来选择状态数、又在该状态数下检验选定状态的效应，会夸大研究的灵活性（research flexibility）。正确的做法是：

• 预先设定（prespecify）聚类选择策略，或通过交叉验证选取；
• 评估聚类初始化的稳定性（即n_runs与不同random_state下结果是否一致）。

这与 skills/neurokit2/references/epochs_events.md 中"避免阈值调参作用于被检验效应"的方法学红线完全一致。

八、最低报告清单：EEG 研究的可复现输出

无论使用 NeuroKit2 的哪些 EEG 功能，最终报告至少需要包含以下信息（原文档清单）：

• 采集层：硬件、电极布局/位置/参考/接地、单位、采样率、在线滤波器；
• 预处理层：重采样、离线滤波/陷波、边缘处理、工频频率；
• 数据质量：坏通道/坏段及其插值方式；
• 伪迹处理：眼电/肌电/心电伪迹校正及 ICA 细节；
• 分段：epoch/baseline 定义、保留的试验数；
• 谱分析：PSD/时频估计器与归一化方式；
• 微状态：输入频带/参考、GFP 定义、训练点、算法、状态数、运行次数/种子、极性、平滑、拟合与稳定性指标；
• 版本：精确的 NeuroKit2/MNE 版本号及实际观测到的输出 schema。

同时要严格避免"频带即心理状态标签"式的过度解读，例如"beta = 焦虑"、"theta/beta = ADHD"。原文档明确指出：EEG 特征本身不是诊断，在没有独立的验证系统和使用意图证据的情况下，不能将其当作诊断、意识监测、麻醉控制、癫痫检测或神经反馈验证的依据。这一条与 skills/neurokit2/SKILL.md 的 Boundary 小节完全一致——本 skill 面向研究与教育用途，而非临床决策。

九、与仓库其他文档的协同

本文档不是孤立的：EEG 分析中涉及的通用信号处理（滤波、重采样、PSD）细节见 skills/neurokit2/references/signal_processing.md；事件与分段（epoch/baseline）语义见 skills/neurokit2/references/epochs_events.md；EEG 中常见的眼电（EOG）伪迹处理见 skills/neurokit2/references/eog.md。其中 EOG 文档与 EEG 的整合路径（同步保留专用 EOG 通道、在适当数据上拟合伪迹识别/校正、验证组件选择不损伤神经信号、对比校正前后的 ERP/频谱/拓扑）正是本文档所要求的"伪迹校正细节需报告"的落地指引。

从 tests/neurokit2/test_scripts.py 可以看到，整个 skill 的 CLI 帮助器都遵循"无动态执行、拒绝 URL/符号链接、字节与行数受限、强制--deidentified"等安全约束（其依赖的 skills/neurokit2/scripts/_common.py 实现了checked_input_file、checked_output_file、require_deidentified等检查）。在把 EEG 数据接入这些工作流时，同样应遵守本地化、去标识化的数据处理原则，不将受保护的健康信息放入提示词或日志。

结语

NeuroKit2 0.2.13 为 EEG 分析提供的是"精选组件"而非"一键管线"：eeg_power负责频段功率、eeg_badchannels负责统计筛查、eeg_rereference/eeg_gfp/eeg_diss负责拓扑前置处理、microstates_*负责微状态全流程，而数据预处理与源重建需要借助可选安装的 MNE。掌握每个函数的精确签名、返回 schema 与命名陷阱（如frequency_band单数、Microstates/Sequence大写键、返回元组顺序），并结合 uv 锁定版本、完整报告清单与"不越界解读"的方法学纪律，就能在 scientific-agent-skills 的框架下构建出真正可复现、可审计、可引用的 EEG 研究流程。

【免费下载链接】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