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
2. Model Configuration
3. Training Configuration
4. Data Configuration
5. Inference Configuration
6. Logging Configuration
7. Hardware Configuration
8. Experiment Tracking Configuration
9. Configuration Best Practices
10. 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

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

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

# ========================================
# 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)