dfm-python 0.5.54__tar.gz → 0.5.55__tar.gz

{dfm_python-0.5.54 → dfm_python-0.5.55}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfm-python
-Version: 0.5.54
+Version: 0.5.55
 Summary: Dynamic Factor Model (DFM) estimation and forecasting in Python
 Project-URL: Homepage, https://github.com/yourusername/dfm-python
 Project-URL: Documentation, https://github.com/yourusername/dfm-python#readme

{dfm_python-0.5.54 → dfm_python-0.5.55}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dfm-python"
-version = "0.5.54"
+version = "0.5.55"
 description = "Dynamic Factor Model (DFM) estimation and forecasting in Python"
 readme = "README.md"
 requires-python = ">=3.10"

{dfm_python-0.5.54 → dfm_python-0.5.55}/src/dfm_python/__init__.py

@@ -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.54"
+__version__ = "0.5.55"
 
 # ============================================================================
 # PUBLIC API DEFINITION

{dfm_python-0.5.54 → dfm_python-0.5.55}/src/dfm_python/config/schema/model.py

@@ -444,14 +444,14 @@ class DFMConfig(BaseModelConfig):
         return result
     
     @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> Union['DFMConfig', 'DDFMConfig']:
-        """Create DFMConfig or DDFMConfig from dictionary.
+    def from_dict(cls, data: Dict[str, Any]) -> Union['DFMConfig', 'DDFMConfig', 'KDFMConfig']:
+        """Create DFMConfig, DDFMConfig, or KDFMConfig from dictionary.
         
         Expected format: {'frequency': {'column_name': 'frequency'}, 'blocks': {...}, ...}
         
         Also accepts estimation parameters: threshold, max_iter, etc.
         """
-        from ...config.adapter import detect_config_type, MODEL_TYPE_DDFM, _normalize_blocks_dict
+        from ...config.adapter import detect_config_type, MODEL_TYPE_DDFM, MODEL_TYPE_KDFM, _normalize_blocks_dict
         from ...utils.errors import ConfigurationError
         
         # Extract base params (handles frequency conversion from series if needed)
@@ -463,6 +463,9 @@ class DFMConfig(BaseModelConfig):
         if config_type == MODEL_TYPE_DDFM:
             return DDFMConfig(**base_params, **DDFMConfig._extract_ddfm(data))
         
+        if config_type == MODEL_TYPE_KDFM:
+            return KDFMConfig(**base_params, **KDFMConfig._extract_kdfm(data))
+        
         # Handle blocks for DFM
         from ...config.adapter import _raise_config_error, _is_dict_like
         blocks_dict = data.get('blocks', {})
@@ -519,7 +522,7 @@ class DDFMConfig(BaseModelConfig):
     @classmethod
     def _extract_ddfm(cls, data: Dict[str, Any]) -> Dict[str, Any]:
         """Extract DDFM-specific parameters from config dict."""
-        base_params = cls._extract_base(data)
+        # Don't extract base params here - they're already in base_params from from_dict
         ddfm_params = cls._extract_params(data, {
             'encoder_layers': None,
             'num_factors': None,
@@ -535,8 +538,7 @@ class DDFMConfig(BaseModelConfig):
             'disp': DEFAULT_DISP,
             'seed': None,
         })
-        base_params.update(ddfm_params)
-        return base_params
+        return ddfm_params
     
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> 'DDFMConfig':
@@ -557,6 +559,8 @@ class KDFMConfig(BaseModelConfig):
     
     This dataclass contains all configuration parameters for the KDFM model.
     It inherits from BaseModelConfig and adds KDFM-specific parameters.
+    
+    Note: KDFM does not use blocks structure (unlike DFM). Only frequency dict is needed.
     """
     # VARMA parameters
     ar_order: int = DEFAULT_KDFM_AR_ORDER  # VAR order p
@@ -577,6 +581,42 @@ class KDFMConfig(BaseModelConfig):
     structural_reg_weight: float = DEFAULT_STRUCTURAL_REG_WEIGHT  # Weight for structural loss
     use_regularization: bool = True
     regularization_scale: float = DEFAULT_REGULARIZATION_SCALE
+    
+    # ========================================================================
+    # Factory Methods
+    # ========================================================================
+    
+    @classmethod
+    def _extract_kdfm(cls, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract KDFM-specific parameters from config dict."""
+        # Don't extract base params here - they're already in base_params from from_dict
+        kdfm_params = cls._extract_params(data, {
+            'ar_order': DEFAULT_KDFM_AR_ORDER,
+            'ma_order': DEFAULT_KDFM_MA_ORDER,
+            'structural_method': 'cholesky',
+            'structural_rank': None,
+            'learning_rate': DEFAULT_LEARNING_RATE,
+            'max_epochs': DEFAULT_MAX_EPOCHS,
+            'batch_size': DEFAULT_BATCH_SIZE,
+            'weight_decay': DEFAULT_REGULARIZATION_SCALE,
+            'grad_clip_val': DEFAULT_GRAD_CLIP_VAL,
+            'structural_reg_weight': DEFAULT_STRUCTURAL_REG_WEIGHT,
+            'use_regularization': True,
+            'regularization_scale': DEFAULT_REGULARIZATION_SCALE,
+        })
+        return kdfm_params
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'KDFMConfig':
+        """Create KDFMConfig from dictionary (delegates to DFMConfig.from_dict for type detection)."""
+        result = DFMConfig.from_dict(data)
+        if isinstance(result, KDFMConfig):
+            return result
+        from ..utils.errors import ConfigurationError
+        raise ConfigurationError(
+            f"Expected KDFMConfig but got {type(result).__name__}",
+            details=f"Result type: {type(result).__name__}, expected: KDFMConfig"
+        )
 
 
 # ============================================================================

{dfm_python-0.5.54 → dfm_python-0.5.55}/src/dfm_python/functional/em.py

@@ -545,6 +545,9 @@ def _update_observation_matrix_blocked(
         
         # Update clock-frequency variables
         for t in range(T):
+            # Safety check: ensure t is within valid range for nanY
+            if t < 0 or t >= nanY.shape[0]:
+                continue
             # Selection matrix for non-missing values
             # Final defensive check: ensure idx_iM indices are valid for nanY
             # Filter out any indices that are out of bounds
@@ -559,15 +562,21 @@ def _update_observation_matrix_blocked(
             idx_iM_valid = idx_iM_valid[(idx_iM_valid >= 0) & (idx_iM_valid < nanY.shape[1])]
             if len(idx_iM_valid) == 0:
                 continue
+            # nanY has shape (T, N), so index as nanY[t, idx_iM_valid] not nanY[idx_iM_valid, t]
             try:
-                Wt = np.diag(~nanY[idx_iM_valid, t])
+                Wt = np.diag(~nanY[t, idx_iM_valid])
             except IndexError:
                 # If this still fails, there's a deeper issue - log and skip
-                _logger.warning(f"IndexError in Wt computation: idx_iM_valid={idx_iM_valid}, nanY.shape={nanY.shape}")
+                _logger.warning(f"IndexError in Wt computation: idx_iM_valid={idx_iM_valid}, nanY.shape={nanY.shape}, t={t}")
                 continue
             
             # E[f_t*f_t' | Omega_T]
+            # EZ has shape (T+1, m), so EZ[t+1] corresponds to time t (t+1 must be <= T)
+            if t + 1 >= EZ.shape[0]:
+                continue
             Z_t = EZ[t+1, bl_idxM_i]  # (rs,)
+            if t + 1 >= V_smooth.shape[0]:
+                continue
             V_t = V_smooth[t+1, bl_idxM_i, :][:, bl_idxM_i]  # (rs, rs)
             EZZ_t = np.outer(Z_t, Z_t) + V_t
             
@@ -578,7 +587,7 @@ def _update_observation_matrix_blocked(
             nom += np.outer(y_t, Z_t)
             
             # Subtract idiosyncratic component contribution
-            if len(i_idio_ii) > 0:
+            if len(i_idio_ii) > 0 and t + 1 < EZ.shape[0] and t + 1 < V_smooth.shape[0]:
                 idio_idx = (rp1 + i_idio_ii - 1).astype(int)  # Convert to 0-based, ensure integer type
                 Z_idio_t = EZ[t+1, idio_idx]  # (n_idio,)
                 V_idio_t = V_smooth[t+1, idio_idx, :][:, bl_idxM_i]  # (n_idio, rs)
@@ -596,7 +605,10 @@ def _update_observation_matrix_blocked(
             fallback_func=lambda: None
         )
         if loadings is not None:
-            C_new[idx_iM, bl_idxM_i] = loadings
+            # Use broadcasting for advanced indexing assignment
+            # idx_iM[:, None] creates shape (n_i, 1) and bl_idxM_i creates shape (rs,)
+            # This broadcasts to (n_i, rs) matching loadings.shape
+            C_new[idx_iM[:, None], bl_idxM_i] = loadings
         
         # Update slower-frequency variables
         # Filter to slower-frequency series and validate indices
@@ -668,17 +680,24 @@ def _update_observation_matrix_blocked(
                 nom = np.zeros(rps)
                 
                 for t in range(T):
+                    # Safety check: ensure t is within valid range for nanY
+                    if t < 0 or t >= nanY.shape[0]:
+                        continue
                     # Selection matrix
                     # Final safety check: ensure j is valid for nanY
+                    # nanY has shape (T, N), so j is column index (series), t is row index (time)
                     if j < 0 or j >= nanY.shape[1]:
                         continue
                     try:
-                        Wt = np.diag([~nanY[j, t]])
+                        Wt = np.diag([~nanY[t, j]])
                     except IndexError:
                         # Skip this iteration if j is out of bounds
                         continue
                     
                     # E[f_t*f_t' | Omega_T]
+                    # EZ has shape (T+1, m), so EZ[t+1] corresponds to time t (t+1 must be <= T)
+                    if t + 1 >= EZ.shape[0] or t + 1 >= V_smooth.shape[0]:
+                        continue
                     Z_t = EZ[t+1, bl_idxQ_i]  # (rps,)
                     V_t = V_smooth[t+1, bl_idxQ_i, :][:, bl_idxQ_i]  # (rps, rps)
                     EZZ_t = np.outer(Z_t, Z_t) + V_t
@@ -690,7 +709,7 @@ def _update_observation_matrix_blocked(
                     nom += y_t * Z_t
                     
                     # Subtract idiosyncratic component contribution
-                    if tent_weights is not None and len(i_idio_jQ) == len(tent_weights):
+                    if tent_weights is not None and len(i_idio_jQ) == len(tent_weights) and t + 1 < EZ.shape[0] and t + 1 < V_smooth.shape[0]:
                         Z_idio_t = EZ[t+1, i_idio_jQ]  # (tent_kernel_size,)
                         V_idio_t = V_smooth[t+1, i_idio_jQ, :][:, bl_idxQ_i]  # (tent_kernel_size, rps)
                         nom -= Wt[0, 0] * (tent_weights @ (np.outer(Z_idio_t, Z_t) + V_idio_t))

{dfm_python-0.5.54 → dfm_python-0.5.55}/src/dfm_python/models/base.py

@@ -61,6 +61,14 @@ from typing import Optional, Union, Tuple, Any, Dict, List, TYPE_CHECKING
 from pathlib import Path
 import numpy as np
 
+if TYPE_CHECKING:
+    from torch import Tensor
+else:
+    try:
+        from torch import Tensor
+    except ImportError:
+        Tensor = Any
+
 if TYPE_CHECKING:
     from ..datamodule import KDFMDataModule, DFMDataModule, DDFMDataModule
 
@@ -71,7 +79,7 @@ from ..config import (
 from ..config.constants import DEFAULT_BLOCK_NAME, DEFAULT_DTYPE, DEFAULT_FORECAST_HORIZON, MAX_WARNING_ITEMS, MAX_ERROR_ITEMS, DEFAULT_CLOCK_FREQUENCY
 from ..logger import get_logger
 from ..utils.errors import ConfigurationError, ModelNotTrainedError, ModelNotInitializedError
-from ..utils.validation import check_has_attr
+from ..utils.validation import check_has_attr, check_condition
 
 _logger = get_logger(__name__)
 
@@ -99,6 +107,7 @@ class BaseFactorModel(ABC):
         self._result: Optional[BaseResult] = None
         self.training_state: Optional[Any] = None
         self._data_module: Optional[Any] = None
+        self.data_processed: Optional[np.ndarray] = None  # Store processed training data for shape validation
     
     @property
     def config(self) -> DFMConfig:
@@ -128,7 +137,7 @@ class BaseFactorModel(ABC):
         
         Raises
         ------
-        ValueError
+        ModelNotTrainedError
             If model has not been trained yet
         """
         if self._result is None:
@@ -147,6 +156,30 @@ class BaseFactorModel(ABC):
                 details="Please call fit() or train the model before accessing results"
             )
     
+    def _ensure_result(self) -> BaseResult:
+        """Ensure result exists, computing it if necessary.
+        
+        This helper method ensures that self._result is available. If it's None,
+        it attempts to compute it from training_state. This is a common pattern
+        used in update(), predict(), and result property.
+        
+        Returns
+        -------
+        BaseResult
+            The model result (computed if necessary)
+            
+        Raises
+        ------
+        ModelNotTrainedError
+            If model has not been trained yet
+        """
+        if self._result is None:
+            self._check_trained()  # This will try to compute result if training_state exists
+            if self._result is None:
+                # If still None after _check_trained, explicitly compute
+                self._result = self.get_result()
+        return self._result
+    
     def _create_temp_config(self, block_name: Optional[str] = None) -> DFMConfig:
         """Create a temporary configuration for model initialization.
         
@@ -263,30 +296,6 @@ class BaseFactorModel(ABC):
             )
         return data_module
     
-    @staticmethod
-    def _validate_ndarray(arr: Any, name: str, expected_ndim: int) -> None:
-        """Validate a numpy array has expected number of dimensions.
-        
-        Parameters
-        ----------
-        arr : Any
-            Array to validate
-        name : str
-            Name of the array for error messages
-        expected_ndim : int
-            Expected number of dimensions
-            
-        Raises
-        ------
-        DataValidationError
-            If array is not a numpy array or has wrong number of dimensions
-        """
-        from ..utils.errors import DataValidationError
-        if not isinstance(arr, np.ndarray) or arr.ndim != expected_ndim:
-            raise DataValidationError(
-                f"{name} must be {expected_ndim}D numpy array, got shape {arr.shape if isinstance(arr, np.ndarray) else 'not array'}"
-            )
-    
     def _forecast_var_factors(
         self,
         Z_last: np.ndarray,
@@ -297,142 +306,30 @@ class BaseFactorModel(ABC):
     ) -> np.ndarray:
         """Forecast factors using AR(1) dynamics.
         
-        Uses iterative matrix multiplication for efficient computation.
-        
-        **AR(1) Dynamics**: f_t = A @ f_{t-1}
-        
-        This method is used by both KDFM and DDFM for factor forecasting, ensuring
-        consistent AR dynamics computation across models.
+        This is a convenience wrapper around forecast_ar1_factors() from numeric.estimator.
+        The `p` and `Z_prev` parameters are kept for backward compatibility but are ignored
+        (AR(1) dynamics only).
         
         Parameters
         ----------
         Z_last : np.ndarray
-            Last factor state of shape (m,) where m is number of factors.
-            Must be 1D array with m >= 1.
+            Last factor state of shape (m,)
         A : np.ndarray
-            Transition matrix of shape (m, m) for AR(1).
-            Must be 2D array with compatible dimensions.
+            Transition matrix of shape (m, m)
         p : int, default 1
-            AR order (always 1).
+            AR order (ignored, always uses AR(1))
         horizon : int, default 1
-            Number of periods to forecast. Must be >= 1.
+            Number of periods to forecast
         Z_prev : np.ndarray, optional
-            Ignored (unused parameter).
+            Ignored (unused parameter)
             
         Returns
         -------
         np.ndarray
-            Forecasted factors of shape (horizon, m) where:
-            - horizon: Number of forecast periods
-            - m: Number of factors (matches Z_last.shape[0])
-            
-        Raises
-        ------
-        DataValidationError
-            If input shapes are incompatible or invalid
-        NumericalError
-            If matrix operations produce NaN/Inf values
-            If forecast computation produces NaN/Inf values
-            
-        Examples
-        --------
-        >>> # AR(1) forecast
-        >>> from dfm_python.numeric.stability import create_scaled_identity
-        >>> Z_last = np.array([1.0, 2.0, 3.0])  # 3 factors
-        >>> A = create_scaled_identity(3, 0.9)  # Use helper function for scaled identity
-        >>> Z_forecast = model._forecast_var_factors(Z_last, A, p=1, horizon=5)
-        >>> assert Z_forecast.shape == (5, 3)
+            Forecasted factors of shape (horizon, m)
         """
-        from ..utils.errors import DataValidationError, NumericalError
-        from ..numeric.validator import validate_no_nan_inf
-        
-        # Validate inputs
-        self._validate_ndarray(Z_last, "Z_last", 1)
-        self._validate_ndarray(A, "A", 2)
-        
-        m = Z_last.shape[0]
-        if m < 1:
-            raise DataValidationError(f"Z_last must have at least 1 factor, got m={m}")
-        
-        if horizon < 1:
-            raise DataValidationError(f"horizon must be >= 1, got {horizon}")
-        
-        validate_no_nan_inf(Z_last, name="Z_last")
-        validate_no_nan_inf(A, name="transition matrix A")
-        
-        # Helper function to validate array shape consistently
-        def _validate_shape(
-            array: np.ndarray,
-            expected_shape: Tuple[int, ...],
-            name: str
-        ) -> None:
-            """Validate array has expected shape.
-            
-            Args:
-                array: Array to validate
-                expected_shape: Expected shape tuple
-                name: Name of array for error message
-            """
-            if array.shape != expected_shape:
-                raise DataValidationError(
-                    f"{name} must have shape {expected_shape}, got {array.shape}"
-                )
-        
-        if Z_prev is not None:
-            validate_no_nan_inf(Z_prev, name="Z_prev")
-            _validate_shape(Z_prev, (m,), "Z_prev")
-        
-        # Helper function to handle forecast computation errors consistently
-        def _handle_forecast_error(
-            error: Exception,
-            error_message: str,
-            error_details: str,
-            exceptions_to_re_raise: Tuple[Any, ...]
-        ) -> None:
-            """Handle forecast computation errors consistently.
-            
-            Args:
-                error: The exception that occurred
-                error_message: Main error message
-                error_details: Detailed diagnostic information
-                exceptions_to_re_raise: Tuple of exception types to re-raise without wrapping
-            """
-            if isinstance(error, exceptions_to_re_raise):
-                raise
-            raise NumericalError(
-                error_message,
-                details=error_details
-            ) from error
-        
-        try:
-            # AR(1) dynamics only (simplified)
-            # Validate AR(1) shape
-            _validate_shape(A, (m, m), "A (transition matrix)")
-            
-            # AR(1): f_t = A @ f_{t-1}
-            Z_forecast = np.zeros((horizon, m), dtype=DEFAULT_DTYPE)
-            Z_forecast[0, :] = A @ Z_last
-            for h in range(1, horizon):
-                Z_forecast[h, :] = A @ Z_forecast[h - 1, :]
-            
-            # Validate output
-            validate_no_nan_inf(Z_forecast, name="forecasted factors")
-            _validate_shape(Z_forecast, (horizon, m), "Forecast output")
-            
-            return Z_forecast
-            
-        except (RuntimeError, ValueError, TypeError, AttributeError, KeyError, IndexError) as e:
-            # Specific exceptions for forecast computation failures
-            _handle_forecast_error(
-                error=e,
-                error_message=f"Forecast computation failed: {e}",
-                error_details=(
-                    f"Z_last shape: {Z_last.shape}, A shape: {A.shape}, "
-                    f"p={p}, horizon={horizon}. Check: (1) Matrix dimensions, "
-                    f"(2) Numerical stability, (3) Input validity."
-                ),
-                exceptions_to_re_raise=(ConfigurationError, DataValidationError)
-            )
+        from ..numeric.estimator import forecast_ar1_factors
+        return forecast_ar1_factors(Z_last, A, horizon, dtype=DEFAULT_DTYPE)
     
     # Legacy method removed: _transform_factors_to_observations()
     # This method used Mx/Wx arrays which are no longer used.
@@ -445,8 +342,8 @@ class BaseFactorModel(ABC):
     ) -> Tuple[Optional[List[str]], Optional[List[int]]]:
         """Resolve target series from DataModule.
         
-        This helper method resolves target series from the DataModule's target_series attribute.
-        Target series should be set during DataModule initialization.
+        This is a convenience wrapper around resolve_target_series() from utils.misc.
+        It gets the DataModule and series_ids, then calls the utility function.
         
         Parameters
         ----------
@@ -467,17 +364,14 @@ class BaseFactorModel(ABC):
         DataError
             If target series are not found in available series
         """
-        from ..utils.errors import DataError
+        from ..utils.misc import resolve_target_series
         
-        # Get target series from DataModule
-        target_series = None
+        # Get DataModule (may raise ModelNotInitializedError)
+        data_module = None
         try:
             data_module = self._get_datamodule()
-            target_series = getattr(data_module, 'target_series', None)
-            if target_series is not None and len(target_series) > 0:
-                target_series = target_series if isinstance(target_series, list) else [target_series]
         except (ModelNotInitializedError, AttributeError):
-            target_series = None
+            pass
         
         # Get series_ids for validation
         if series_ids is None:
@@ -486,31 +380,19 @@ class BaseFactorModel(ABC):
             if series_ids is None and self._config is not None:
                 series_ids = self._config.get_series_ids()
         
-        # Resolve indices if we have both target_series and series_ids
-        target_indices = None
-        if target_series is not None and series_ids is not None:
-            target_indices = []
-            for tgt_id in target_series:
-                if tgt_id in series_ids:
-                    target_indices.append(series_ids.index(tgt_id))
-                else:
-                    _logger.warning(
-                        f"{self.__class__.__name__} prediction: target series '{tgt_id}' not found in series_ids. "
-                        f"Available: {series_ids[:MAX_WARNING_ITEMS]}{'...' if len(series_ids) > MAX_WARNING_ITEMS else ''}. "
-                        f"Skipping this target series."
-                    )
-            
-            if len(target_indices) == 0:
-                raise DataError(
-                    f"{self.__class__.__name__} prediction failed: none of the specified target series found",
-                    details=f"Target: {target_series}, Available: {series_ids[:MAX_ERROR_ITEMS]}{'...' if len(series_ids) > MAX_ERROR_ITEMS else ''}"
-                )
-        
-        return target_series, target_indices
+        # Call utility function
+        return resolve_target_series(
+            datamodule=data_module,
+            series_ids=series_ids,
+            result=result,
+            model_name=self.__class__.__name__
+        )
     
     def _compute_default_horizon(self, default: Optional[int] = None) -> int:
         """Compute default forecast horizon from clock frequency.
         
+        This is a convenience wrapper around compute_default_horizon() from utils.misc.
+        
         Parameters
         ----------
         default : int, optional
@@ -522,53 +404,8 @@ class BaseFactorModel(ABC):
         int
             Default horizon in periods (typically 1 year worth of periods)
         """
-        if default is None:
-            default = DEFAULT_FORECAST_HORIZON
-        
-        try:
-            from ..config import get_periods_per_year
-            from ..utils.misc import get_clock_frequency
-            
-            if self._config is not None:
-                clock = get_clock_frequency(self._config)
-                return get_periods_per_year(clock)
-        except (AttributeError, ImportError, ValueError):
-            _logger.debug(f"Could not determine horizon from clock frequency, using default={default}")
-        
-        return default
-    
-    
-    @staticmethod
-    def _create_default_standardization_arrays(
-        n_series: int,
-        dtype: Optional[type] = None
-    ) -> Tuple[np.ndarray, np.ndarray]:
-        """Create default standardization arrays (for internal use only).
-        
-        Creates arrays representing standardized data (mean=0, std=1).
-        Used internally when data is already standardized and no scaler is provided.
-        
-        Parameters
-        ----------
-        n_series : int
-            Number of series
-        dtype : type, optional
-            Data type for arrays. If None, uses DEFAULT_DTYPE.
-            
-        Returns
-        -------
-        Tuple[np.ndarray, np.ndarray]
-            (mean_array, std_array) both of shape (n_series,)
-            mean_array: zeros (standardized data has zero mean)
-            std_array: ones (standardized data has unit variance)
-        """
-        if dtype is None:
-            dtype = DEFAULT_DTYPE
-        
-        mean_array = np.zeros(n_series, dtype=dtype)
-        std_array = np.ones(n_series, dtype=dtype)
-        
-        return mean_array, std_array
+        from ..utils.misc import compute_default_horizon
+        return compute_default_horizon(self._config, default=default)
     
     # Legacy method removed: _standardize_data()
     # This method used Mx/Wx arrays which are no longer used.
@@ -582,6 +419,46 @@ class BaseFactorModel(ABC):
         self._data_module = None
         return self
     
+    
+    @abstractmethod
+    def update(self, data: Union[np.ndarray, Any]) -> None:
+        """Update model state with new observations.
+        
+        This method updates the model's internal state (factors) with new observations,
+        but keeps model parameters fixed. The implementation differs by model type:
+        - DFM: Uses Kalman filtering/smoothing
+        - DDFM: Uses neural network forward pass
+        - KDFM: Uses companion matrix forward pass
+        
+        **Data Shape**: The input data must be 2D with shape (T_new x N) where:
+        - T_new: Number of new time steps (can be any positive integer)
+        - N: Number of series (must match training data)
+        
+        **Supported Types**:
+        - numpy.ndarray: (T_new x N) array
+        - pandas.DataFrame: DataFrame with N columns, T_new rows
+        - polars.DataFrame: DataFrame with N columns, T_new rows
+        
+        **Important**: Data must be preprocessed by the user (same preprocessing as training).
+        Only target scaler is handled internally if needed.
+        
+        Parameters
+        ----------
+        data : np.ndarray, pandas.DataFrame, or polars.DataFrame
+            New preprocessed observations with shape (T_new x N) where:
+            - T_new: Number of new time steps (any positive integer)
+            - N: Number of series (must match training data)
+            Data must be preprocessed by user (same preprocessing as training).
+            
+        Raises
+        ------
+        ModelNotTrainedError
+            If model has not been trained yet
+        DataValidationError
+            If data shape doesn't match training data (N must match)
+        """
+        raise NotImplementedError("Subclasses must implement update()")
+    
     @abstractmethod
     def get_result(self) -> BaseResult:
         """Extract result from trained model.