docs/CONFIGURATION_EN.md

# Configuration Documentation

This document provides a detailed overview of all configuration options, parameter descriptions, and usage examples for the Emotion and Physiological State Change Prediction Model.

## Table of Contents

1. [Configuration System Overview](#configuration-system-overview)
2. [Model Configuration](#model-configuration)
3. [Training Configuration](#training-configuration)
4. [Data Configuration](#data-configuration)
5. [Inference Configuration](#inference-configuration)
6. [Logging Configuration](#logging-configuration)
7. [Hardware Configuration](#hardware-configuration)
8. [Experiment Tracking Configuration](#experiment-tracking-configuration)
9. [Configuration Best Practices](#configuration-best-practices)
10. [Configuration Validation](#configuration-validation)

## Configuration System Overview

### Configuration Format

The project uses YAML format for configuration files, supporting:
- Hierarchical structure
- Comments
- Variable references
- Environment variable substitution
- Configuration inheritance

### Loading Order

1. Default Configuration (Built-in)
2. Global Config File (`~/.emotion-prediction/config.yaml`)
3. Project Config Files (`configs/`)
4. Command-line argument overrides

### Configuration Manager

```python
from src.utils.config import ConfigManager

# Load configuration
config_manager = ConfigManager()
config = config_manager.load_config("configs/training_config.yaml")

# Access configuration
learning_rate = config.training.optimizer.learning_rate
batch_size = config.training.batch_size

# Validate configuration
config_manager.validate_config(config)
```

## Model Configuration

### Main Config: `configs/model_config.yaml`

```yaml
# ========================================
# Model Configuration File
# ========================================

# Model basic info
model_info:
  name: "MLP_Emotion_Predictor"
  type: "MLP"
  version: "1.0"
  description: "MLP-based emotion and physiological state change prediction model"
  author: "Research Team"
  
# Input/Output dimensions
dimensions:
  input_dim: 7    # Input: User PAD (3D) + Vitality (1D) + Current PAD (3D)
  output_dim: 3   # Output: ΔPAD (3D: ΔPleasure, ΔArousal, ΔDominance)
  
# Network architecture
architecture:
  # Hidden layers config
  hidden_layers:
    - size: 128
      activation: "ReLU"
      dropout: 0.2
      batch_norm: false
      layer_norm: false
    - size: 64
      activation: "ReLU"
      dropout: 0.2
      batch_norm: false
      layer_norm: false
    - size: 32
      activation: "ReLU"
      dropout: 0.1
      batch_norm: false
      layer_norm: false
  
  # Output layer config
  output_layer:
    activation: "Linear"  # Linear activation for regression
    
  # Regularization
  use_batch_norm: false
  use_layer_norm: false
  
# Weight initialization
initialization:
  weight_init: "xavier_uniform"  # Options: xavier_uniform, xavier_normal, kaiming_uniform, kaiming_normal
  bias_init: "zeros"             # Options: zeros, ones, uniform, normal
  
# Regularization config
regularization:
  # L2 regularization
  weight_decay: 0.0001
  
  # Dropout config
  dropout_config:
    type: "standard"      # standard dropout
    rate: 0.2            # Dropout probability
    
  # Batch normalization
  batch_norm_config:
    momentum: 0.1
    eps: 1e-5
    
# Model saving config
model_saving:
  save_best_only: true          # Save only the best model
  save_format: "pytorch"        # Formats: pytorch, onnx, torchscript
  checkpoint_interval: 10       # Save checkpoint every 10 epochs
  max_checkpoints: 5           # Maximum number of checkpoints to keep
  
# PAD emotion space specific config
emotion_model:
  # PAD value range constraints
  pad_space:
    pleasure_range: [-1.0, 1.0]
    arousal_range: [-1.0, 1.0]
    dominance_range: [-1.0, 1.0]
    
  # Vitality config
  vitality:
    range: [0.0, 100.0]
    normalization: "min_max"        # Methods: min_max, z_score, robust
    
  # Prediction output constraints
  prediction:
    # Reasonable range for ΔPAD changes
    delta_pad_range: [-0.5, 0.5]
    # Pressure change range
    delta_pressure_range: [-0.3, 0.3]
    # Confidence range
    confidence_range: [0.0, 1.0]
```

## Training Configuration

### Main Config: `configs/training_config.yaml`

```yaml
# ========================================
# Training Configuration File
# ========================================

# Training basic info
training_info:
  experiment_name: "emotion_prediction_v1"
  description: "Training of MLP-based emotion prediction model"
  seed: 42
  tags: ["baseline", "mlp", "emotion_prediction"]
  
# Data configuration
data:
  # Data paths
  paths:
    train_data: "data/train.csv"
    val_data: "data/val.csv"
    test_data: "data/test.csv"
    
  # Preprocessing
  preprocessing:
    # Feature scaling
    feature_scaling:
      method: "standard"        # standard, min_max, robust, none
      pad_features: "standard"
      vitality_feature: "min_max"
      
    # Label scaling
    label_scaling:
      method: "standard"
      delta_pad: "standard"
      delta_pressure: "standard"
      confidence: "none"
    
    # Data augmentation
    augmentation:
      enabled: false
      noise_std: 0.01
      mixup_alpha: 0.2
      augmentation_factor: 2
    
    # Data validation
    validation:
      check_ranges: true
      check_missing: true
      check_outliers: true
      outlier_method: "iqr"  # iqr, zscore, isolation_forest
  
  # Dataloader config
  dataloader:
    batch_size: 32
    num_workers: 4
    pin_memory: true
    shuffle: true
    drop_last: false
    persistent_workers: true
    
  # Data split
  split:
    train_ratio: 0.8
    val_ratio: 0.1
    test_ratio: 0.1
    stratify: false
    random_seed: 42

# Training hyperparameters
training:
  # Epochs
  epochs:
    max_epochs: 200
    warmup_epochs: 5
    
  # Early stopping
  early_stopping:
    enabled: true
    patience: 15
    min_delta: 1e-4
    monitor: "val_loss"
    mode: "min"
    restore_best_weights: true
    
  # Gradient config
  gradient:
    clip_enabled: true
    clip_value: 1.0
    clip_norm: 2          # 1: L1 norm, 2: L2 norm
    
  # Mixed precision training
  mixed_precision:
    enabled: false
    opt_level: "O1"       # O0, O1, O2, O3
    
  # Gradient accumulation
  gradient_accumulation:
    enabled: false
    accumulation_steps: 4

# Optimizer config
optimizer:
  type: "AdamW"          # Adam, SGD, AdamW, RMSprop, Adagrad
  
  # Adam/AdamW parameters
  adam_config:
    lr: 0.0005
    weight_decay: 0.01
    betas: [0.9, 0.999]
    eps: 1e-8
    amsgrad: false
    
  # SGD parameters
  sgd_config:
    lr: 0.01
    momentum: 0.9
    weight_decay: 0.0001
    nesterov: true

# Scheduler config
scheduler:
  type: "CosineAnnealingLR"  # StepLR, CosineAnnealingLR, ReduceLROnPlateau, ExponentialLR
  
  # Cosine Annealing
  cosine_config:
    T_max: 200
    eta_min: 1e-6
    last_epoch: -1
    
  # Step LR
  step_config:
    step_size: 30
    gamma: 0.1
    
  # Plateau
  plateau_config:
    patience: 10
    factor: 0.5
    min_lr: 1e-7

# Loss function config
loss:
  type: "WeightedMSELoss"  # MSELoss, L1Loss, SmoothL1Loss, HuberLoss, WeightedMSELoss
  
  # Base loss parameters
  base_config:
    reduction: "mean"
    
  # Weighted loss config
  weighted_config:
    delta_pad_weight: 1.0      # Weight for ΔPAD
    delta_pressure_weight: 1.0 # Weight for ΔPressure
    confidence_weight: 0.5     # Weight for Confidence
```

---
*(English translation continues for the rest of the document)*