DGLZ

EEG emotion recognition with CNN-Transformer encoders and three-stage hierarchical classifiers.

Overview

DGLZ is a Python toolkit for EEG-based emotion recognition. It combines convolutional neural network (CNN) feature extractors with Transformer encoders to model both local and global temporal patterns in EEG signals. A three-stage hierarchical classification pipeline progressively refines emotion predictions.

Key components:

• Data processing -- EEG I/O, channel selection, band filtering, signal transforms, and index building.
• Resampling -- Truncated-Gaussian and subject-state-aware resampling strategies for balanced training data.
• Datasets -- PyTorch-style dataset classes for resampled, subject-state, normal-emotion, and depression-emotion data with configurable collation and splitting.
• Models -- CNN blocks, Transformer blocks, token embeddings, and specialised encoder architectures for trial-level, subject-state, normal-emotion, and depression-emotion classification.
• Training -- Loss functions, optimizers, schedulers, early stopping, checkpointing, and metric tracking.
• Prediction -- Post-processing, prediction aggregation, three-stage inference pipeline, and submission formatting.
• CLI -- A unified eemo command-line interface built on Typer.

Installation

Requires Python 3.13 or later.

# Clone the repository
git clone https://github.com/SuShuHeng/DGLZ.git
cd DGLZ

# Install in editable (development) mode
pip install -e .

# Or with all optional dependencies (test + packaging tools)
pip install -e ".[all]"

Updating

# Check and update from PyPI, fallback to GitHub Release (default)
eemo update

# Update from GitHub Release only (skip PyPI)
eemo update --dist-repo

# Install a specific version from GitHub Release
eemo update --dist-repo --tag v0.1.2

# Use a custom distribution repository
eemo update --dist-repo --dist-repo-url https://github.com/example/repo.git --tag v0.1.2

# Use a custom wheel filename pattern
eemo update --dist-repo --tag v0.1.2 --asset-pattern "dglz-*.whl"

# Preview without installing
eemo update --dry-run

CLI Usage

After installation the eemo command is available:

# Show available commands
eemo --help

# Prepare raw EEG data for processing
eemo prepare --help

# Resample datasets for balanced training
eemo resample --help

# Train a model
eemo train --help

# Run the three-stage hierarchical inference pipeline
eemo infer-three-stage --help

# Run predictions with a trained model
eemo pred --help

# Display the current version
eemo version

# Manage configuration files
eemo config --help

# Run experiment training sweeps
eemo exp-train --help

# Run experiment prediction sweeps
eemo exp-pred --help

# Manage model checkpoints
eemo ckpt --help

Project Structure

DGLZ/
├── pyproject.toml          # Package metadata and build configuration
├── README.md               # This file
├── .python-version         # Python version pin (3.13)
├── configs/                # Configuration files
├── docs/                   # Documentation
├── src/
│   └── eemoclas/           # Main package
│       ├── __init__.py
│       ├── __version__.py
│       ├── cli/            # Command-line interface
│       │   └── main.py     # Entry point (registers as `eemo`)
│       ├── data/           # EEG I/O, splitting, transforms
│       ├── datasets/       # PyTorch dataset classes
│       ├── model/          # CNN-Transformer architectures
│       ├── prediction/     # Inference and post-processing
│       ├── resampling/     # Data resampling strategies
│       ├── training/       # Training loop utilities
│       └── utils/          # Configuration, logging, metrics, paths
└── tests/                  # Test suite

Running Tests

pip install -e ".[test]"
pytest

License

Licensed under the Apache License 2.0.