Projeto TCC: Classificação de Emoções via EEG (Base DEAP)

Este repositório contém todo o código, dados e scripts necessários para pré-processamento, extração de características, treinamento e avaliação de classificadores (SVM, Random Forest e Dummy) voltados ao reconhecimento de emoções a partir de sinais EEG da base DEAP. A organização modular e reprodutível facilita experimentos e gerações de resultados consistentes.

---

1. Estrutura do Repositório

tcc_classificadores/
│
├── data/                             # Dados brutos e processados
│   ├── raw/                          # Arquivos originais da base DEAP (.pkl, .mat)
│   ├── split_data/                   # Splits de treino/teste (antes de PCA)
│   └── processed/                    # Dados processados (features e labels)
│       ├── features/                 # Atributos extraídos (_std e _pca)
│       └── labels/                   # Rótulos definitivos para cada tarefa
│
├── notebooks/                        # Notebooks de EDA, pré-processamento e análise
│   ├── 01_extracao_e_eda.ipynb       # Análise exploratória e extração de atributos
│   ├── 02_preprocessamento.ipynb     # Normalização, codificação e split de dados
│   ├── 03_treinamento_classificadores.ipynb  # Treinamento com RandomizedSearchCV
│   └── 04_avaliacao_e_analise.ipynb  # Avaliação de métricas e plotagem de resultados
│
├── src/                              # Módulos Python do pipeline
│   ├── config.py                     # Parâmetros globais e caminhos de diretórios
│   ├── data_utils.py                 # Carregamento, validação e split de dados
│   ├── hyperparams.py                # Definição de espaços de busca e grids de hiperparâmetros
│   ├── pipelines.py                  # Construção de pipelines (SMOTE → model)
│   ├── train_utils.py                # Funções de treino, salvamento e carregamento de modelos
│   ├── evaluation_utils.py           # Avaliação de métricas e geração de relatórios
│   ├── model_comparison_utils.py     # Comparação consolidada de múltiplos modelos
│   ├── compare_three_models.py       # Script para comparar SVM, RF e Dummy de forma integrada
│   ├── train_model.py                # Execução isolada de rotina de treino para uma tarefa
│   ├── evaluate_model.py             # Execução isolada de avaliação em conjunto de teste
│   ├── summarize_logs.py             # Agregação e formatação de logs de parâmetros e resultados
│   ├── feature_importance.py         # Geração de importância de atributos (Gini, SHAP)
│   ├── convert_params_to_json.py     # Conversão de parâmetros otimizados em JSON legível

│
├── results/                          # Saída de modelos e predições (gerado em runtime)
│   ├── modelos/                      # Modelos treinados (.joblib)
│   ├── predicoes/                    # CSVs com y_pred e probabilidades
│   └── logs/                         # Logs de parâmetros e métricas
│
├── environment.yml                   # Ambiente Conda para reprodutibilidade
├── requirements.txt                  # Dependências Python (pip)
└── README.md                         # Documento de orientação e referência

---

2. Descrição das Pastas Principais

• ``: Dados brutos originais da base DEAP. Não devem ser alterados.
• ``: Partições de treino/teste antes de transformações aplicadas.
• ``: Matrizes de características extraídas (_std e _pca).
• ``: Rótulos finais (_definitivo) para cada tarefa de classificação.
• ``: Jupyter Notebooks para EDA, pré-processamento, treino e análise.
• ``: Código-fonte organizado em módulos por funcionalidade.
• ``: Artefatos gerados após execução (modelos, predições e logs).

---

3. Instalação e Configuração

3.1. Usando Conda (recomendado)

git clone https://github.com/SEU_USUARIO/cmrcs/tcc_classificadores.git
cd tcc_classificadores
conda env create -f environment.yml
conda activate tcc_classificadores

3.2. Usando pip/venv (alternativa)

python -m venv venv
source venv/bin/activate   # macOS/Linux
venv\Scripts\activate     # Windows
pip install -r requirements.txt

---

4. Pipeline de Execução

Executar script principal:

python src/main.py

O fluxo completo envolve:

1. Carregamento de dados brutos
2. Pré-processamento e split
3. Extração de características e PCA
4. Balanceamento com SMOTE
5. Treino de modelos (RandomizedSearchCV)
6. Avaliação e salvamento em results/

---

5. Exemplos de Comandos

• Treinar modelo de valência:

  python src/train_model.py --task valence

• Avaliar modelo salvo:

  python src/evaluate_model.py --model-path results/modelos/svm_valence.joblib

• Gerar relatório comparativo:

  python src/compare_three_models.py

---

6. Contato e Referências

• Autor: Caio Marcos Santos

Referências:

1. Koelstra et al. (2012). DEAP: A Database for Emotion Analysis using Physiological Signals.
2. Pedregosa et al. (2011). Scikit-learn: Machine Learning in Python.

---