简介

这是美国陆军研究实验室（ARL）的EEGModels项目：一组基于Keras和TensorFlow编写的用于脑电图（EEG）信号处理与分类的卷积神经网络（CNN）模型。本项目的目的是：

• 提供一套经过充分验证的用于EEG信号处理和分类的CNN模型；
• 促进可重复性研究；
• 使其他研究人员能够在其数据上尽可能简便地使用和比较这些模型。

需求

• Python == 3.7 或 3.8
• tensorflow == 2.X（已验证在2.0至2.3版本上均可正常运行，支持CPU和GPU）

若要运行EEG/MEG ERP分类示例脚本，您还需要：

• mne >= 0.17.1
• PyRiemann >= 0.2.5
• scikit-learn >= 0.20.1
• matplotlib >= 2.2.3

已实现的模型

• EEGNet [1]。原版模型及修订版模型均已实现。
• 用于稳态视觉诱发电位（SSVEP）信号分类的EEGNet变体 [2]
• DeepConvNet [3]
• ShallowConvNet [3]

使用方法

要使用本包，请将此文件夹的内容添加到您的PYTHONPATH环境变量中。随后，您可以直接导入任意模型并进行配置，如下所示：

from EEGModels import EEGNet, ShallowConvNet, DeepConvNet

model  = EEGNet(nb_classes = ..., Chans = ..., Samples = ...)

model2 = ShallowConvNet(nb_classes = ..., Chans = ..., Samples = ...)

model3 = DeepConvNet(nb_classes = ..., Chans = ..., Samples = ...)

使用相应的损失函数和优化器编译模型（在本例中分别为分类交叉熵和Adam优化器）。然后拟合模型并对新的测试数据进行预测。

model.compile(loss = 'categorical_crossentropy', optimizer = 'adam')
fittedModel    = model.fit(...)
predicted      = model.predict(...)

EEGNet特征可解释性

注意：请参阅https://github.com/vlawhern/arl-eegmodels/issues/29，以获取在TensorFlow 2中运行此功能所需的额外步骤。

为重现我们在[1]中报告的EEGNet单次试验特征重要性结果，请下载并安装位于[此处]的DeepExplain工具，该工具实现了多种相关性归因方法（包括基于梯度和基于扰动的方法）。其使用方法简述如下：

from EEGModels import EEGNet
from tensorflow.keras.models import Model
from deepexplain.tensorflow import DeepExplain
from tensorflow.keras import backend as K

# 配置、编译并拟合模型
 
model          = EEGNet(nb_classes = ..., Chans = ..., Samples = ...)
model.compile(loss = 'categorical_crossentropy', optimizer = 'adam')
fittedModel    = model.fit(...)

# 使用DeepExplain获取部分测试数据（X_test, Y_test）的单次试验特征重要性。
# 注意，model.layers[-2]指向的是softmax激活之前的全连接层。此外，我们在此处采用了论文中的DeepLIFT方法，当然也可以选择其他方法，例如epsilon-LRP。
# 此方法适用于所有已实现的模型。

# 其中，Y_test和X_test分别是类别标签的独热编码和输入数据。

with DeepExplain(session = K.get_session()) as de:
	input_tensor   = model.layers[0].input
	fModel         = Model(inputs = input_tensor, outputs = model.layers[-2].output)    
	target_tensor  = fModel(input_tensor)    

	# 如果需要，也可以使用epsilon-LRP。
	attributions   = de.explain('deeplift', target_tensor * Y_test, input_tensor, X_test)
	# attributions = de.explain('elrp', target_tensor * Y_test, input_tensor, X_test)	

论文引用

如果您在研究中使用了EEGNet模型并认为它有所帮助，请引用以下论文：

@article{Lawhern2018,
  author={Vernon J Lawhern and Amelia J Solon and Nicholas R Waytowich and Stephen M Gordon and Chou P Hung and Brent J Lance},
  title={EEGNet: a compact convolutional neural network for EEG-based brain–computer interfaces},
  journal={Journal of Neural Engineering},
  volume={15},
  number={5},
  pages={056013},
  url={http://stacks.iop.org/1741-2552/15/i=5/a=056013},
  year={2018}
}

如果您在研究中使用了EEGNet模型的SSVEP变体并认为它有所帮助，请引用以下论文：

@article{Waytowich2018,
  author={Nicholas Waytowich and Vernon J Lawhern and Javier O Garcia and Jennifer Cummings and Josef Faller and Paul Sajda and Jean M
Vettel},
  title={Compact convolutional neural networks for classification of asynchronous steady-state visual evoked potentials},
  journal={Journal of Neural Engineering},
  volume={15},
  number={6},
  pages={066031},
  url={http://stacks.iop.org/1741-2552/15/i=6/a=066031},
  year={2018}
}
	

同样地，如果您使用了ShallowConvNet或DeepConvNet模型并认为它们有所帮助，请引用以下论文：

@article{hbm23730,
author = {Schirrmeister Robin Tibor and 
          Springenberg Jost Tobias and 
          Fiederer Lukas Dominique Josef and 
          Glasstetter Martin and 
          Eggensperger Katharina and 
          Tangermann Michael and 
          Hutter Frank and 
          Burgard Wolfram and 
          Ball Tonio},
title = {Deep learning with convolutional neural networks for EEG decoding and visualization},
journal = {Human Brain Mapping},
volume = {38},
number = {11},
pages = {5391-5420},
keywords = {脑电图, EEG分析, 机器学习, 端到端学习, 脑机接口, 模型可解释性, 脑映射},
doi = {10.1002/hbm.23730},
url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/hbm.23730}
}

法律声明

本项目受知识共享署名CC0 1.0公共领域奉献协议（以下简称“协议”）约束。您应随本软件收到一份该协议的副本。如未收到，请访问https://github.com/USArmyResearchLab/ARLDCCSO。无论以源代码形式还是二进制形式，无论全部或部分，您对ARL EEGModels的使用或分发均视为您完全同意遵守该协议中的各项条款。

本项目的其他部分受美国法典第17章第105节的国内版权保护。这些部分采用Apache 2.0许可证授权。管理本材料的完整许可文本包含在本项目官方发行版中的LICENSE.TXT文件中。

arl-eegmodels以“希望其有用”的态度发布，但不提供任何担保；甚至不提供适销性或特定用途适用性的默示担保。

您可在本目录下的LICENSE文件中找到完整的许可文本。

贡献

鉴于法律方面的要求，每位贡献者都需要提交一份已签署的贡献者许可协议。ARL 贡献者许可协议（ARL 表格 266）可在此处找到：链接。

每位外部贡献者必须为其拟参与的每个项目分别签署并提交一份该协议的副本。

一旦 ARL 收到已签署的协议，该协议将永久有效。

因此，外部贡献者只需为其计划参与的每个项目签署一次该协议即可。

arl-eegmodels 快速上手指南

arl-eegmodels 是由美国陆军研究实验室（ARL）开源的 EEG（脑电图）信号处理与分类卷积神经网络模型集合，基于 Keras 和 TensorFlow 构建。本项目提供了经过验证的 EEGNet、ShallowConvNet、DeepConvNet 等经典模型，旨在简化科研复现与对比实验。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Python 版本：3.7 或 3.8
• 核心框架：TensorFlow 2.X (已验证支持 2.0 - 2.3，适用于 CPU 和 GPU)
• 可选依赖（如需运行 EEG/MEG ERP 分类示例脚本）：
  • mne >= 0.17.1
  • PyRiemann >= 0.2.5
  • scikit-learn >= 0.20.1
  • matplotlib >= 2.2.3

国内加速建议：安装依赖时推荐使用清华或阿里镜像源以提升下载速度。

安装步骤

本项目无需通过 pip 安装，只需将代码库添加到 Python 路径即可使用。

1. 克隆项目代码

   git clone https://github.com/vlawhern/arl-eegmodels.git
   

2. 安装 Python 依赖 进入项目目录并安装所需库（推荐国内镜像）：

   cd arl-eegmodels
   pip install tensorflow==2.3 mne PyRiemann scikit-learn matplotlib -i https://pypi.tuna.tsinghua.edu.cn/simple
   

   (注：请根据实际需要的 TensorFlow 版本调整 tensorflow==2.3)

3. 配置环境变量 将项目文件夹路径添加到 PYTHONPATH 环境变量中，以便直接导入模块。

   • Linux / macOS:

     export PYTHONPATH="${PYTHONPATH}:/path/to/arl-eegmodels"
     

     (请将 /path/to/arl-eegmodels 替换为实际的绝对路径)

   • Windows (PowerShell):

     $env:PYTHONPATH = "$env:PYTHONPATH;C:\path\to\arl-eegmodels"
     

     (请将 C:\path\to\arl-eegmodels 替换为实际的绝对路径)

基本使用

配置完成后，您可以直接在 Python 脚本中导入模型并进行训练。以下是最简使用示例：

1. 导入与初始化模型

支持 EEGNet, ShallowConvNet, DeepConvNet 等模型。需指定类别数 (nb_classes)、通道数 (Chans) 和时间采样点数 (Samples)。

from EEGModels import EEGNet, ShallowConvNet, DeepConvNet

# 初始化 EEGNet 模型
model  = EEGNet(nb_classes = 2, Chans = 64, Samples = 128)

# 初始化 ShallowConvNet 模型
model2 = ShallowConvNet(nb_classes = 2, Chans = 64, Samples = 128)

# 初始化 DeepConvNet 模型
model3 = DeepConvNet(nb_classes = 2, Chans = 64, Samples = 128)

2. 编译、训练与预测

使用分类交叉熵损失函数和 Adam 优化器编译模型，随后进行拟合与预测。

# 编译模型
model.compile(loss = 'categorical_crossentropy', optimizer = 'adam', metrics=['accuracy'])

# 训练模型 (X_train, Y_train 需替换为您的实际数据)
fittedModel = model.fit(X_train, Y_train, batch_size=32, epochs=50, validation_split=0.2)

# 在新测试数据上进行预测
predicted = model.predict(X_test)

3. 特征可解释性（可选）

若需复现论文中的单试次特征相关性分析（如 DeepLIFT 方法），需额外安装 DeepExplain。注意：在 TensorFlow 2 环境下使用时，可能需要参考项目 Issue #29 进行额外配置。

from EEGModels import EEGNet
from tensorflow.keras.models import Model
from deepexplain.tensorflow import DeepExplain
from tensorflow.keras import backend as K

# 假设模型已配置、编译并拟合完毕
model = EEGNet(nb_classes=2, Chans=64, Samples=128)
# ... compile and fit ...

# 使用 DeepExplain 获取特征归因
with DeepExplain(session=K.get_session()) as de:
    input_tensor  = model.layers[0].input
    # 指向 softmax 激活前的全连接层
    fModel        = Model(inputs=input_tensor, outputs=model.layers[-2].output)    
    target_tensor = fModel(input_tensor)    

    # X_test: 测试数据，Y_test: 标签的 one-hot 编码
    attributions = de.explain('deeplift', target_tensor * Y_test, input_tensor, X_test)