dfm-python 0.5.53__py3-none-any.whl → 0.5.54__py3-none-any.whl

dfm_python/__init__.py

@@ -40,7 +40,7 @@ Example (Standard Lightning Pattern):
     >>> model.load_config('config/default.yaml')
     >>> 
     >>> # Step 4: Create trainer and fit (standard Lightning pattern)
-    >>> trainer = DFMTrainer(max_epochs=100)
+    >>> trainer = DFMTrainer(max_epochs=100)  # DEFAULT_MAX_EPOCHS
     >>> trainer.fit(model, dm)
     >>> 
     >>> # Step 5: Predict
@@ -55,7 +55,7 @@ Example (Standard Lightning Pattern):
     >>> ddfm_model = DDFM(encoder_layers=[64, 32], num_factors=2)
     >>> ddfm_model.load_config('config/default.yaml')
     >>> 
-    >>> trainer_ddfm = DDFMTrainer(max_epochs=100)
+    >>> trainer_ddfm = DDFMTrainer(max_epochs=100)  # DEFAULT_MAX_EPOCHS
     >>> trainer_ddfm.fit(ddfm_model, dm_ddfm)
     >>> Xf, Zf = ddfm_model.predict(horizon=6)
     
@@ -65,7 +65,7 @@ Note: DFMConfig uses frequency dict to specify series (column names -> frequenci
 For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.5.53"
+__version__ = "0.5.54"
 
 # ============================================================================
 # PUBLIC API DEFINITION

dfm_python/config/adapter.py

@@ -28,7 +28,7 @@ from .constants import DEFAULT_CLOCK_FREQUENCY
 # Error helper to reduce repetitive imports
 def _get_config_error():
     """Get ConfigurationError (lazy import to avoid circular dependencies)."""
-    from ...utils.errors import ConfigurationError
+    from dfm_python.utils.errors import ConfigurationError
     return ConfigurationError
 
 
@@ -58,6 +58,22 @@ def _raise_config_error(message: str, details: Optional[str] = None) -> NoReturn
 # Helper Functions for Config Parsing
 # ============================================================================
 
+def _is_dict_like(obj: Any) -> bool:
+    """Check if object is dict-like (dict, OrderedDict, etc.).
+    
+    Parameters
+    ----------
+    obj : Any
+        Object to check
+        
+    Returns
+    -------
+    bool
+        True if object is dict-like, False otherwise
+    """
+    return isinstance(obj, dict) or hasattr(obj, 'keys') and hasattr(obj, '__getitem__')
+
+
 def _convert_series_to_frequency_dict(
     series_data: Any,
     default_clock: str = DEFAULT_CLOCK_FREQUENCY

dfm_python/config/constants.py

@@ -28,10 +28,15 @@ MIN_DIAGONAL_VARIANCE = 1e-8  # Minimum variance for diagonal elements
 MIN_OBSERVATION_NOISE = 1e-4  # Minimum observation noise for measurement error (used in EM updates)
 MIN_FACTOR_VARIANCE = 1e-10  # Minimum variance for factors
 MIN_STD = 1e-8  # Minimum standard deviation
+DEFAULT_VARIANCE_FALLBACK = 1.0  # Default variance fallback value for numerical stability
 
 # Maximum eigenvalues
 MAX_EIGENVALUE = 1e6  # Maximum eigenvalue cap
 
+# Eigenvalue stability thresholds
+DEFAULT_EIGENVALUE_MAX_MAGNITUDE = 1.0  # Default maximum eigenvalue magnitude for stability checks
+DEFAULT_EIGENVALUE_WARN_THRESHOLD = 0.99  # Default warning threshold for near-unstable eigenvalues
+
 # Matrix cleaning defaults
 DEFAULT_CLEAN_NAN = 0.0  # Default value for NaN replacement in clean_matrix
 DEFAULT_CLEAN_INF = MAX_EIGENVALUE  # Default value for Inf replacement in clean_matrix (uses MAX_EIGENVALUE)
@@ -39,6 +44,12 @@ DEFAULT_CLEAN_INF = MAX_EIGENVALUE  # Default value for Inf replacement in clean
 # Identity matrix defaults
 DEFAULT_IDENTITY_SCALE = 1.0  # Default scale for create_scaled_identity(n, 1.0)
 DEFAULT_ZERO_VALUE = 0.0  # Default zero value for explicit zero assignments
+DEFAULT_XAVIER_GAIN = 1.0  # Default gain for Xavier initialization
+DEFAULT_OUTPUT_LAYER_GAIN = 0.1  # Default gain for output layer Xavier initialization (smaller for stability)
+
+# Companion matrix initialization defaults
+DEFAULT_INIT_SCALE = 0.01  # Default initialization scale for companion matrix B and C matrices
+DEFAULT_KERNEL_INIT_SCALE = 0.1  # Default initialization scale for companion matrix coefficient matrices
 
 # Regularization scales
 DEFAULT_REGULARIZATION_SCALE = 1e-5  # Default ridge regularization scale
@@ -57,7 +68,6 @@ DEFAULT_MAX_ITER = 100  # Default maximum EM iterations (general)
 DEFAULT_EM_MAX_ITER = 5000  # Default maximum EM iterations (DFM-specific)
 DEFAULT_MAX_EPOCHS = 100  # Default maximum training epochs
 DEFAULT_MAX_MCMC_ITER = 200  # Default maximum MCMC iterations
-DEFAULT_EPOCHS_PER_ITER = 10  # Default epochs per MCMC iteration
 
 # Batch size defaults
 DEFAULT_BATCH_SIZE = 32  # Default batch size for neural networks
@@ -78,6 +88,10 @@ DEFAULT_LR_DECAY_RATE = 0.96  # Default exponential decay rate for learning rate
 
 # Loss function defaults
 DEFAULT_HUBER_DELTA = 1.0  # Default delta parameter for Huber loss
+HUBER_QUADRATIC_COEFF = 0.5  # Quadratic coefficient for Huber loss (0.5 * a^2 term)
+
+# Matrix computation defaults
+SYMMETRY_AVERAGE_FACTOR = 0.5  # Averaging factor for symmetric matrix computation (0.5 * (M + M.T))
 
 # Data clipping defaults
 DEFAULT_DDFM_CLIP_RANGE_DEEP = 8.0  # Clipping range for deep networks (>2 layers)
@@ -86,11 +100,15 @@ DEFAULT_DDFM_CLIP_RANGE_SHALLOW = 10.0  # Clipping range for shallow networks (<
 # Numerical stability for division
 DEFAULT_EPSILON = 1e-8  # Default epsilon for division operations to prevent division by zero
 
+# Random seed defaults
+DEFAULT_SEED = 3  # Default random seed for reproducibility
+
 # Structural identification defaults
 DEFAULT_STRUCTURAL_REG_WEIGHT = 0.1  # Default weight for structural regularization loss
 DEFAULT_STRUCTURAL_INIT_SCALE = 0.1  # Default initialization scale for structural matrices
 DEFAULT_STRUCTURAL_DIAG_SCALE = 1.0  # Default diagonal scale for structural matrices (FIXED Iteration 7: was 0.1, caused near-singular S)
 DEFAULT_CHOLESKY_EPS = 1e-6  # Default epsilon for Cholesky decomposition stability
+CHOLESKY_LOG_DET_FACTOR = 2.0  # Factor for log determinant computation from Cholesky decomposition (log det = 2.0 * sum(log(diag(L))))
 
 # ============================================================================
 # Network Architecture Defaults
@@ -112,17 +130,27 @@ DEFAULT_START_DATE = datetime(2000, 1, 1)
 
 # Default window size for DDFM
 DEFAULT_WINDOW_SIZE = 100
+DEFAULT_TENT_KERNEL_SIZE = 5  # Default tent kernel size for slower-frequency series aggregation
 # Note: DEFAULT_BATCH_SIZE is defined above (line 52) as 32 for general neural networks
 # Use DEFAULT_DDFM_BATCH_SIZE (100) for DDFM-specific batch size
 
 # Warning/display limits
 MAX_WARNING_ITEMS = 5  # Maximum number of items to show in warning messages
+MAX_ERROR_ITEMS = 20  # Maximum number of items to show in error message details
 
 # Minimum observations
 DEFAULT_MIN_OBS = 5  # Default minimum observations for estimation
 DEFAULT_MIN_OBS_IDIO = 5  # Default minimum observations for idio estimation
 DEFAULT_MIN_OBS_VAR = 7  # Minimum observations for VAR estimation (order + 5)
 
+# Dimension validation bounds
+MIN_TIME_STEPS = 1  # Minimum number of time steps (T) required for data
+MIN_VARIABLES = 1  # Minimum number of variables (N) required for data
+MIN_DDFM_TIME_STEPS = 2  # Minimum number of time steps (T) required for DDFM training (DDFM-specific, different from general MIN_TIME_STEPS=1)
+MIN_DDFM_DATASET_SIZE_WARNING = 10  # Minimum dataset size (T) below which DDFM denoising training warns about potential instability
+MIN_ITER_FOR_DELTA_COMPUTATION = 1  # Minimum iteration count required before computing delta (MSE change) in DDFM denoising training
+MIN_EPS_SHAPE_FOR_IDIO = 1  # Minimum eps shape dimension required for idiosyncratic component processing in DDFM
+
 # Idiosyncratic component defaults
 DEFAULT_IDIO_STD = 0.1  # Default idiosyncratic standard deviation (when estimation fails)
 DEFAULT_IDIO_RHO0 = 0.1  # Default initial AR coefficient for idiosyncratic components
@@ -130,9 +158,7 @@ DEFAULT_AR_COEF = 0.5  # Default AR coefficient for initialization (conservative
 DEFAULT_PROCESS_NOISE = 0.1  # Default process noise for initialization
 DEFAULT_TRANSITION_COEF = 0.9  # Default transition coefficient for DFM initialization
 
-# Standardization defaults
-DEFAULT_WX_VALUE = 1.0  # Default standard deviation when Wx is missing (unit scale)
-DEFAULT_MX_VALUE = 0.0  # Default mean when Mx is missing (zero-centered)
+# Standardization defaults removed - now using sklearn scalers directly
 
 # VAR stability and clipping
 VAR_STABILITY_THRESHOLD = 0.99  # Maximum eigenvalue for VAR stability
@@ -153,18 +179,20 @@ DEFAULT_DAMPING_FACTOR = 0.5  # Default damping factor for parameter updates (us
 
 # Numerical thresholds
 MIN_CONDITION_NUMBER = 1e-12  # Minimum value for condition number calculations
+MAX_CONDITION_NUMBER = 1e8  # Maximum condition number threshold for regularization (ill-conditioned matrix threshold)
 
 # ============================================================================
 # Display and Logging Defaults
 # ============================================================================
 
 DEFAULT_DISP = 10  # Default display interval for progress
+DEFAULT_LOG_INTERVAL = 10  # Default logging interval divisor (log every num_epochs // DEFAULT_LOG_INTERVAL epochs)
+DEFAULT_PROGRESS_LOG_INTERVAL = 5  # Default progress logging interval for EM algorithm
 
 # ============================================================================
 # Precision Defaults
 # ============================================================================
 
-DEFAULT_PRECISION = 32  # Default training precision
 DEFAULT_DTYPE = np.float32  # Default numpy dtype for arrays
 
 # PyTorch dtype (matches DEFAULT_DTYPE)
@@ -180,6 +208,34 @@ except ImportError:
 
 DEFAULT_IRF_HORIZON = 20  # Default horizon for IRF computation
 
+# ============================================================================
+# Forecast Defaults
+# ============================================================================
+
+DEFAULT_FORECAST_HORIZON = 6  # Default horizon for forecast computation
+
+# ============================================================================
+# Error Handling Constants
+# ============================================================================
+
+# Common exception types for computation error handling
+# Used to consolidate duplicate exception handling patterns across models
+COMPUTATION_ERROR_TYPES = (RuntimeError, ValueError, TypeError, AttributeError, KeyError)
+
+# ============================================================================
+# KDFM Defaults
+# ============================================================================
+
+DEFAULT_KDFM_AR_ORDER = 1  # Default AR order (VAR lag order p) for KDFM
+DEFAULT_KDFM_MA_ORDER = 0  # Default MA order (MA lag order q) for KDFM (0 = pure VAR)
+
+# ============================================================================
+# Tutorial Defaults
+# ============================================================================
+
+TUTORIAL_MAX_PERIODS = 100  # Default maximum periods for tutorial data (reduced for faster execution)
+TUTORIAL_MAX_EPOCHS = 10  # Default maximum epochs for tutorial training (reduced for faster execution)
+
 # ============================================================================
 # Matrix Type Constants
 # ============================================================================
@@ -248,6 +304,8 @@ TENT_WEIGHTS_LOOKUP: Dict[Tuple[str, str], np.ndarray] = {
     ('a', 'm'): np.array([1, 2, 3, 4, 5, 4, 3, 2, 1]),       # 9 periods: annual -> monthly
     ('m', 'w'): np.array([1, 2, 3, 2, 1]),                    # 5 periods: monthly -> weekly
     ('q', 'w'): np.array([1, 2, 3, 4, 5, 4, 3, 2, 1]),       # 9 periods: quarterly -> weekly
+    ('sa', 'w'): np.array([1, 2, 3, 4, 3, 2, 1]),             # 7 periods: semi-annual -> weekly
+    ('a', 'w'): np.array([1, 2, 3, 4, 5, 4, 3, 2, 1]),       # 9 periods: annual -> weekly
     ('sa', 'q'): np.array([1, 2, 1]),                         # 3 periods: semi-annual -> quarterly
     ('a', 'q'): np.array([1, 2, 3, 2, 1]),                    # 5 periods: annual -> quarterly
     ('a', 'sa'): np.array([1, 2, 1]),                         # 3 periods: annual -> semi-annual
@@ -271,19 +329,26 @@ __all__ = [
     'MIN_FACTOR_VARIANCE',
     'MIN_STD',
     'MAX_EIGENVALUE',
+    'DEFAULT_EIGENVALUE_MAX_MAGNITUDE',
+    'DEFAULT_EIGENVALUE_WARN_THRESHOLD',
     'DEFAULT_CLEAN_NAN',
     'DEFAULT_CLEAN_INF',
     'DEFAULT_IDENTITY_SCALE',
     'DEFAULT_ZERO_VALUE',
+    'DEFAULT_XAVIER_GAIN',
+    'DEFAULT_OUTPUT_LAYER_GAIN',
+    'DEFAULT_INIT_SCALE',
+    'DEFAULT_KERNEL_INIT_SCALE',
     'DEFAULT_REGULARIZATION_SCALE',
     'DEFAULT_REGULARIZATION',
     'DEFAULT_CLIP_THRESHOLD',
     'DEFAULT_DATA_CLIP_THRESHOLD',
+    'MIN_CONDITION_NUMBER',
+    'MAX_CONDITION_NUMBER',
     # Training
     'DEFAULT_MAX_ITER',
     'DEFAULT_MAX_EPOCHS',
     'DEFAULT_MAX_MCMC_ITER',
-    'DEFAULT_EPOCHS_PER_ITER',
     'DEFAULT_BATCH_SIZE',  # General neural network default (32)
     'DEFAULT_DDFM_BATCH_SIZE',  # DDFM-specific default (100)
     'DEFAULT_LEARNING_RATE',
@@ -292,9 +357,11 @@ __all__ = [
     'DEFAULT_WEIGHT_DECAY',
     'DEFAULT_LR_DECAY_RATE',
     'DEFAULT_HUBER_DELTA',
+    'HUBER_QUADRATIC_COEFF',
     'DEFAULT_DDFM_CLIP_RANGE_DEEP',
     'DEFAULT_DDFM_CLIP_RANGE_SHALLOW',
     'DEFAULT_EPSILON',
+    'DEFAULT_SEED',
     # Structural identification
     'DEFAULT_STRUCTURAL_REG_WEIGHT',
     'DEFAULT_STRUCTURAL_INIT_SCALE',
@@ -311,6 +378,13 @@ __all__ = [
     'DEFAULT_MIN_OBS',
     'DEFAULT_MIN_OBS_IDIO',
     'DEFAULT_MIN_OBS_VAR',
+    # Dimension validation
+    'MIN_TIME_STEPS',
+    'MIN_VARIABLES',
+    'MIN_DDFM_TIME_STEPS',
+    'MIN_DDFM_DATASET_SIZE_WARNING',
+    'MIN_ITER_FOR_DELTA_COMPUTATION',
+    'MIN_EPS_SHAPE_FOR_IDIO',
     'DEFAULT_IDIO_STD',
     'DEFAULT_IDIO_RHO0',
     'DEFAULT_AR_COEF',
@@ -325,19 +399,28 @@ __all__ = [
     'DEFAULT_SLOWER_FREQ_VARIANCE_DENOMINATOR',
     'DEFAULT_EXTREME_FORECAST_THRESHOLD',
     'DEFAULT_MAX_VARIANCE',
-    # Standardization
-    'DEFAULT_WX_VALUE',
-    'DEFAULT_MX_VALUE',
     # Correlation and validation
     'PERFECT_CORR_THRESHOLD',
     'HIGH_CORR_THRESHOLD',
     'DEFAULT_DAMPING_FACTOR',
     # Display
     'DEFAULT_DISP',
-    # Precision
-    'DEFAULT_PRECISION',
+    'DEFAULT_LOG_INTERVAL',
+    'DEFAULT_PROGRESS_LOG_INTERVAL',
+    'DEFAULT_TENT_KERNEL_SIZE',
+    'MAX_ERROR_ITEMS',
     # IRF
     'DEFAULT_IRF_HORIZON',
+    # Forecast
+    'DEFAULT_FORECAST_HORIZON',
+    # Error handling
+    'COMPUTATION_ERROR_TYPES',
+    # KDFM defaults
+    'DEFAULT_KDFM_AR_ORDER',
+    'DEFAULT_KDFM_MA_ORDER',
+    # Tutorial defaults
+    'TUTORIAL_MAX_PERIODS',
+    'TUTORIAL_MAX_EPOCHS',
     # Matrix types
     'MATRIX_TYPE_GENERAL',
     'MATRIX_TYPE_COVARIANCE',
@@ -345,6 +428,9 @@ __all__ = [
     'MATRIX_TYPE_LOADING',
     # Log-determinant
     'MAX_LOG_DETERMINANT',
+    'CHOLESKY_LOG_DET_FACTOR',
+    # Matrix computation
+    'SYMMETRY_AVERAGE_FACTOR',
     # Default frequency
     'DEFAULT_CLOCK_FREQUENCY',
     'DEFAULT_HIERARCHY_VALUE',

dfm_python/config/schema/model.py

@@ -68,6 +68,10 @@ from ..constants import (
     DEFAULT_NAN_METHOD,
     DEFAULT_NAN_K,
     DEFAULT_CLOCK_FREQUENCY,
+    DEFAULT_KDFM_AR_ORDER,
+    DEFAULT_KDFM_MA_ORDER,
+    FREQUENCY_HIERARCHY,
+    DEFAULT_HIERARCHY_VALUE,
 )
 
 
@@ -124,7 +128,7 @@ class BaseModelConfig:
     # Shared Data Handling Parameters
     # ========================================================================
     clock: str = 'm'  # Required: Base frequency for latent factors (global clock): 'd', 'w', 'm', 'q', 'sa', 'a' (defaults to 'm' for monthly)
-    target_scaler: Optional[ScalerType] = None  # Sklearn scaler instance (StandardScaler, RobustScaler, etc.) for target series only. Pass scaler object directly, not string. Feature series are assumed to be manually preprocessed.
+    target_scaler: Optional[ScalerType] = None  # Fitted sklearn scaler instance (StandardScaler, RobustScaler, etc.) for target series only. Must be a fitted scaler object (call .fit() on target data first). Pass scaler object directly, not string. Feature series are assumed to be manually preprocessed. If None, target series are assumed to be already in the desired scale.
     # Note: nan_method and nan_k are internal constants (DEFAULT_NAN_METHOD, DEFAULT_NAN_K) used during initialization only
     
     def __post_init__(self):
@@ -254,47 +258,38 @@ class DFMConfig(BaseModelConfig):
     # ========================================================================
     # EM Algorithm Parameters (HOW - controls the algorithm)
     # ========================================================================
-    ar_lag: int = 1  # Number of lags in AR transition equation (lookback window). Must be 1 or 2 (maximum supported order is VAR(2))
+    # Note: ar_lag removed - factors always use AR(1) dynamics (simplified)
     threshold: float = DEFAULT_EM_THRESHOLD  # EM convergence threshold
     max_iter: int = DEFAULT_EM_MAX_ITER  # Maximum EM iterations
     
     # ========================================================================
     # Numerical Stability Parameters (transparent and configurable)
     # ========================================================================
-    # AR Coefficient Clipping
-    clip_ar_coefficients: bool = True  # Enable AR coefficient clipping for stationarity
-    ar_clip_min: float = AR_CLIP_MIN  # Minimum AR coefficient (must be > -1 for stationarity)
-    ar_clip_max: float = AR_CLIP_MAX   # Maximum AR coefficient (must be < 1 for stationarity)
-    warn_on_ar_clip: bool = True  # Warn when AR coefficients are clipped (indicates near-unit root)
+    # AR Coefficient Clipping: If provided (not None), automatically enables clipping and always warns
+    ar_clip: Optional[Dict[str, float]] = None  # {"min": float, "max": float} - AR coefficient clipping bounds. If None, no clipping. If provided, clipping enabled and warnings always shown.
     
-    # Data Value Clipping
-    clip_data_values: bool = True  # Enable clipping of extreme data values
-    data_clip_threshold: float = 100.0  # Clip values beyond this many standard deviations
-    warn_on_data_clip: bool = True  # Warn when data values are clipped (indicates outliers)
+    # Data Value Clipping: If provided (not None), automatically enables clipping and always warns
+    data_clip: Optional[float] = None  # Clip values beyond this many standard deviations. If None, no clipping. If provided, clipping enabled and warnings always shown.
     
-    # Regularization
-    use_regularization: bool = True  # Enable regularization for numerical stability
-    regularization_scale: float = DEFAULT_REGULARIZATION_SCALE  # Scale factor for ridge regularization (relative to trace, default 1e-5)
-    min_eigenvalue: float = 1e-8  # Minimum eigenvalue for positive definite matrices
-    max_eigenvalue: float = 1e6   # Maximum eigenvalue cap to prevent explosion
-    warn_on_regularization: bool = True  # Warn when regularization is applied
-    
-    # Damped Updates
-    use_damped_updates: bool = True  # Enable damped updates when likelihood decreases
-    damping_factor: float = 0.8  # Damping factor (0.8 = 80% new, 20% old)
-    warn_on_damped_update: bool = True  # Warn when damped updates are used
-    
-    # Idiosyncratic Component Augmentation
-    augment_idio: bool = True  # Enable state augmentation with idiosyncratic components (default: True)
-    augment_idio_slow: bool = True  # Enable tent-length chains for slower-frequency series (default: True)
+    # Regularization: If provided (not None), automatically enables regularization and always warns
+    regularization: Optional[Dict[str, float]] = None  # {"scale": float, "min_eigenvalue": float, "max_eigenvalue": float} - Regularization parameters. If None, no regularization. If provided, regularization enabled and warnings always shown.
+    
+    # Damped Updates: If provided (not None), automatically enables damping and always warns
+    damping_factor: Optional[float] = None  # Damping factor (0.8 = 80% new, 20% old). If None, no damping. If provided, damping enabled and warnings always shown.
+    
+    # Idiosyncratic Component Parameters (auto-detected from frequencies)
     idio_rho0: float = DEFAULT_IDIO_RHO0  # Initial AR coefficient for idiosyncratic components (default: 0.1)
-    idio_min_var: float = 1e-8  # Minimum variance for idiosyncratic innovation covariance (default: 1e-8)
+    idio_min_var: float = MIN_DIAGONAL_VARIANCE  # Minimum variance for idiosyncratic innovation covariance (defaults to MIN_DIAGONAL_VARIANCE)
+    # Note: augment_idio and augment_idio_slow are auto-detected from frequency configuration
+    # - If all series use clock frequency: augment_idio=False, augment_idio_slow=False
+    # - If mixed frequencies detected: augment_idio=True, augment_idio_slow=True (auto-enabled)
     
     def __post_init__(self):
         """Validate blocks structure and derive block properties."""
         super().__post_init__()
         
         from ...config.adapter import _raise_config_error
+        from ..constants import FREQUENCY_HIERARCHY, DEFAULT_HIERARCHY_VALUE
         
         if not self.blocks:
             _raise_config_error("DFM configuration must contain at least one block.")
@@ -327,6 +322,67 @@ class DFMConfig(BaseModelConfig):
         from ...config.adapter import _raise_config_error
         if any(f < 1 for f in self.factors_per_block):
             _raise_config_error("factors_per_block must contain positive integers >= 1")
+        
+        # Auto-detect mixed frequencies and set augment_idio/augment_idio_slow
+        # If frequency dict exists, check if all frequencies match clock
+        if self.frequency is not None and len(self.frequency) > 0:
+            frequencies = list(self.frequency.values())
+            clock_hierarchy = FREQUENCY_HIERARCHY.get(self.clock, DEFAULT_HIERARCHY_VALUE)
+            is_mixed_freq = any(
+                FREQUENCY_HIERARCHY.get(freq, DEFAULT_HIERARCHY_VALUE) != clock_hierarchy
+                for freq in frequencies
+            )
+            # Auto-set augment_idio and augment_idio_slow based on frequency detection
+            # Store as internal attributes (not in __init__ signature)
+            object.__setattr__(self, '_augment_idio', is_mixed_freq)
+            object.__setattr__(self, '_augment_idio_slow', is_mixed_freq)
+        else:
+            # No frequency info yet - will be auto-detected when data is loaded
+            object.__setattr__(self, '_augment_idio', False)
+            object.__setattr__(self, '_augment_idio_slow', False)
+    
+    @property
+    def augment_idio(self) -> bool:
+        """Auto-detected: True if mixed frequencies detected, False if single frequency."""
+        return getattr(self, '_augment_idio', False)
+    
+    @property
+    def augment_idio_slow(self) -> bool:
+        """Auto-detected: True if mixed frequencies detected, False if single frequency."""
+        return getattr(self, '_augment_idio_slow', False)
+    
+    def _update_idio_flags_from_frequencies(self, frequencies: List[str]) -> None:
+        """Update augment_idio flags based on detected frequencies (called when data is loaded)."""
+        from ..constants import FREQUENCY_HIERARCHY, DEFAULT_HIERARCHY_VALUE
+        clock_hierarchy = FREQUENCY_HIERARCHY.get(self.clock, DEFAULT_HIERARCHY_VALUE)
+        is_mixed_freq = any(
+            FREQUENCY_HIERARCHY.get(freq, DEFAULT_HIERARCHY_VALUE) != clock_hierarchy
+            for freq in frequencies
+        )
+        object.__setattr__(self, '_augment_idio', is_mixed_freq)
+        object.__setattr__(self, '_augment_idio_slow', is_mixed_freq)
+    
+    def to_em_config(self) -> 'EMConfig':
+        """Create EMConfig from DFMConfig consolidated parameters."""
+        from ...functional.em import EMConfig
+        from ..constants import DEFAULT_REGULARIZATION, VAR_STABILITY_THRESHOLD
+        
+        # Extract regularization parameters directly from dict
+        if self.regularization is not None and isinstance(self.regularization, dict):
+            reg_scale = self.regularization.get('scale', DEFAULT_REGULARIZATION_SCALE)
+            min_eigenval = self.regularization.get('min_eigenvalue', MIN_EIGENVALUE)
+            max_eigenval = self.regularization.get('max_eigenvalue', VAR_STABILITY_THRESHOLD)
+        else:
+            reg_scale = DEFAULT_REGULARIZATION
+            min_eigenval = MIN_EIGENVALUE
+            max_eigenval = VAR_STABILITY_THRESHOLD
+        
+        return EMConfig(
+            regularization=reg_scale,
+            min_norm=min_eigenval,
+            max_eigenval=max_eigenval,
+            # Other parameters use defaults from EMConfig
+        )
     
     def get_blocks_array(self, columns: Optional[List[str]] = None) -> np.ndarray:
         """Get blocks as numpy array (N x B) where N is number of series and B is number of blocks.
@@ -357,38 +413,43 @@ class DFMConfig(BaseModelConfig):
         return self._cached_blocks
     
     @classmethod
-    def _extract_dfm_params(cls, data: Dict[str, Any]) -> Dict[str, Any]:
-        """Extract DFM-specific parameters from config dict."""
-        base_params = cls._extract_base(data)
-        dfm_params = cls._extract_params(data, {
-            'ar_lag': 1,
-            'threshold': DEFAULT_EM_THRESHOLD,
-            'max_iter': DEFAULT_EM_MAX_ITER,
-            'clip_ar_coefficients': True,
-            'ar_clip_min': -0.99,
-            'ar_clip_max': 0.99,
-            'use_regularization': True,
-            'regularization_scale': 1e-5,
-            'min_eigenvalue': MIN_EIGENVALUE,
-            'max_eigenvalue': MAX_EIGENVALUE,
-            'augment_idio': True,
-            'augment_idio_slow': True,
-            'idio_rho0': 0.1,
-            'idio_min_var': MIN_DIAGONAL_VARIANCE,
-        })
-        base_params.update(dfm_params)
-        return base_params
+    def _extract_dfm_params(cls, data: Dict[str, Any], base_params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Extract DFM-specific parameters from config dict.
+        
+        Parameters
+        ----------
+        data : Dict[str, Any]
+            Config dictionary
+        base_params : Dict[str, Any], optional
+            Pre-extracted base parameters. If provided, avoids duplicate extraction.
+            If None, extracts base params internally.
+        """
+        if base_params is None:
+            base_params = cls._extract_base(data)
+        
+        # Extract consolidated parameters (new format only)
+        dfm_params = {
+            'threshold': data.get('threshold', DEFAULT_EM_THRESHOLD),
+            'max_iter': data.get('max_iter', DEFAULT_EM_MAX_ITER),
+            'idio_rho0': data.get('idio_rho0', DEFAULT_IDIO_RHO0),
+            'idio_min_var': data.get('idio_min_var', MIN_DIAGONAL_VARIANCE),
+            'ar_clip': data.get('ar_clip', None),
+            'data_clip': data.get('data_clip', None),
+            'regularization': data.get('regularization', None),
+            'damping_factor': data.get('damping_factor', None),
+        }
+        
+        result = base_params.copy()
+        result.update(dfm_params)
+        return result
     
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> Union['DFMConfig', 'DDFMConfig']:
         """Create DFMConfig or DDFMConfig from dictionary.
         
-        Handles multiple formats:
-        1. New format: {'frequency': {'column_name': 'frequency'}, ...}
-        2. Legacy format (Hydra): {'series': {'series_id': {...}}, 'blocks': {...}}
-        3. Legacy format (list): {'series': [{'series_id': ..., 'frequency': ...}], ...}
+        Expected format: {'frequency': {'column_name': 'frequency'}, 'blocks': {...}, ...}
         
-        Also accepts estimation parameters: ar_lag, threshold, max_iter, etc.
+        Also accepts estimation parameters: threshold, max_iter, etc.
         """
         from ...config.adapter import detect_config_type, MODEL_TYPE_DDFM, _normalize_blocks_dict
         from ...utils.errors import ConfigurationError
@@ -411,7 +472,9 @@ class DFMConfig(BaseModelConfig):
             _raise_config_error(f"blocks must be a dict, got {type(blocks_dict)}")
         
         blocks_dict_normalized = _normalize_blocks_dict(blocks_dict)
-        return DFMConfig(blocks=blocks_dict_normalized, **base_params, **DFMConfig._extract_dfm_params(data))
+        # Pass base_params to _extract_dfm_params to avoid duplicate extraction
+        dfm_params = DFMConfig._extract_dfm_params(data, base_params=base_params)
+        return DFMConfig(blocks=blocks_dict_normalized, **dfm_params)
 
 
 @dataclass
@@ -438,7 +501,7 @@ class DDFMConfig(BaseModelConfig):
     learning_rate: float = 0.001  # Learning rate for Adam optimizer (default: 0.001)
     epochs: int = 100  # Number of training epochs (default: 100)
     batch_size: int = 100  # Batch size for training (default: 100 to match original DDFM)
-    factor_order: int = 1  # VAR lag order for factor dynamics. Must be 1 or 2 (maximum supported order is VAR(2), default: 1)
+    # Note: factor_order removed - factors always use AR(1) dynamics (simplified)
     use_idiosyncratic: bool = True  # Model idio components with AR(1) dynamics (default: True)
     min_obs_idio: int = 5  # Minimum observations for idio AR(1) estimation (default: 5)
     
@@ -465,7 +528,6 @@ class DDFMConfig(BaseModelConfig):
             'learning_rate': DEFAULT_LEARNING_RATE,
             'epochs': DEFAULT_MAX_EPOCHS,
             'batch_size': DEFAULT_DDFM_BATCH_SIZE,
-            'factor_order': 1,
             'use_idiosyncratic': True,
             'min_obs_idio': DEFAULT_MIN_OBS_IDIO,
             'max_iter': DEFAULT_MAX_MCMC_ITER,
@@ -482,7 +544,11 @@ class DDFMConfig(BaseModelConfig):
         result = DFMConfig.from_dict(data)
         if isinstance(result, DDFMConfig):
             return result
-        raise ValueError("Expected DDFMConfig but got DFMConfig")
+        from ..utils.errors import ConfigurationError
+        raise ConfigurationError(
+            "Expected DDFMConfig but got DFMConfig",
+            details=f"Result type: {type(result).__name__}, expected: DDFMConfig"
+        )
 
 
 @dataclass
@@ -493,8 +559,8 @@ class KDFMConfig(BaseModelConfig):
     It inherits from BaseModelConfig and adds KDFM-specific parameters.
     """
     # VARMA parameters
-    ar_order: int = 1  # VAR order p
-    ma_order: int = 0  # MA order q (0 = pure VAR)
+    ar_order: int = DEFAULT_KDFM_AR_ORDER  # VAR order p
+    ma_order: int = DEFAULT_KDFM_MA_ORDER  # MA order q (0 = pure VAR)
     
     # Structural identification
     structural_method: str = 'cholesky'  # 'cholesky', 'full', 'low_rank'