Metadata-Version: 2.4
Name: DGLZ
Version: 0.1.6
Summary: EEG emotion recognition with CNN-Transformer encoders and three-stage hierarchical classifiers
Author: SuShuHeng
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.9
Requires-Dist: tqdm>=4.60
Requires-Dist: scikit-learn>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: matplotlib>=3.5
Requires-Dist: openpyxl>=3.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=5.0; extra == "test"
Provides-Extra: packaging
Requires-Dist: build>=1.0; extra == "packaging"
Requires-Dist: twine>=5.0; extra == "packaging"
Provides-Extra: all
Requires-Dist: DGLZ[packaging,test]; extra == "all"

# 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.

```bash
# 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]"
```

## CLI Usage

After installation the `eemo` command is available:

```bash
# 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

```bash
pip install -e ".[test]"
pytest
```

## License

Licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
