dfm-python 0.5.5__py3-none-any.whl → 0.5.11__py3-none-any.whl

dfm_python/__init__.py

@@ -6,6 +6,7 @@ This package implements a comprehensive Dynamic Factor Model framework with supp
 - Tent kernel aggregation for low-to-high frequency mapping
 - Expectation-Maximization (EM) algorithm for parameter estimation
 - Kalman filtering and smoothing for factor extraction
+- News decomposition for nowcasting
 - Deep Dynamic Factor Models (DDFM) with nonlinear encoders (requires PyTorch)
 
 The package implements a clock-based approach to mixed-frequency DFMs, where all latent 
@@ -22,6 +23,7 @@ Key Features:
     - Flexible block structure for factor modeling
     - Robust handling of missing data (internal spline interpolation)
     - Automatic standardization and data clipping
+    - News decomposition for forecast updates
 
 Example (Standard Lightning Pattern):
     >>> from dfm_python import DFM, DFMDataModule, DFMTrainer
@@ -65,7 +67,7 @@ Note: DFMConfig and SeriesConfig are internal implementation details.
 For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.5.5"
+__version__ = "0.5.11"
 
 # ============================================================================
 # PUBLIC API DEFINITION
@@ -79,14 +81,15 @@ __version__ = "0.5.5"
 # 2. High-level API: DFM, DDFM, module-level convenience functions
 # 3. Core utilities: TimeIndex, diagnostics
 # 4. Models: BaseFactorModel, DDFM (low-level)
-# 5. Data & Results: DFMResult
+# 5. Nowcasting: Nowcast, result classes, para_const
+# 6. Data & Results: DFMResult
 # ============================================================================
 
 # Configuration (from config/ subpackage)
 from .config import (
     DEFAULT_BLOCK_NAME,
-    ConfigSource, YamlSource, HydraSource,
-    make_config_source,
+    ConfigSource, YamlSource, DictSource, HydraSource,
+    MergedConfigSource, make_config_source,
 )
 # Internal imports (for backward compatibility, but not recommended)
 from .config import DFMConfig, SeriesConfig  # Internal use only
@@ -102,13 +105,22 @@ from .utils.time import calculate_rmse
 # Users can import these directly from dfm_python
 from .lightning import (
     DFMDataModule,
-    DDFMDataModule,  # DDFM-specific DataModule
     DFMDataset,  # Dataset class (usually not needed directly)
-    DDFMDataset,  # DDFM Dataset class (usually not needed directly)
     KalmanFilter,  # Module class
     EMAlgorithm,  # Module class
 )
 
+# Nowcasting (from nowcast/ subpackage)
+from .nowcast import (
+    Nowcast,
+    NowcastResult,
+)
+from .nowcast.helpers import (
+    para_const,
+    NewsDecompResult,
+    BacktestResult,
+)
+
 # Model implementations
 from .models.base import BaseFactorModel
 from .models.dfm import DFM
@@ -118,16 +130,19 @@ from .models.ddfm import DDFM, DDFMModel
 
 __all__ = [
     # Core classes
-    'DFM',
+    'DFM', 'Nowcast',
     # Model base and implementations
     'BaseFactorModel',
+    # Nowcast result classes
+    'NowcastResult', 'NewsDecompResult', 'BacktestResult',
     # Constants
     'DEFAULT_BLOCK_NAME',
     # Config sources
-    'ConfigSource', 'YamlSource', 'HydraSource',
-    'make_config_source',
+    'ConfigSource', 'YamlSource', 'DictSource', 'HydraSource',
+    'MergedConfigSource', 'make_config_source',
     # Low-level API (functional interface - advanced usage)
     'BaseResult', 'DFMResult', 'DDFMResult', 'calculate_rmse', 'diagnose_series', 'print_series_diagnosis',
+    'para_const',  # Internal utility for nowcasting
 ]
 
 # DDFM high-level API (PyTorch is mandatory)
@@ -139,9 +154,7 @@ __all__.extend([
 # Lightning modules (mandatory dependency)
 __all__.extend([
     'DFMDataModule',
-    'DDFMDataModule',  # DDFM-specific DataModule
     'DFMDataset',  # Dataset class (usually not needed directly)
-    'DDFMDataset',  # DDFM Dataset class (usually not needed directly)
     'KalmanFilter',  # Module class
     'EMAlgorithm',  # Module class
 ])

dfm_python/config/adapter.py

@@ -214,7 +214,8 @@ class YamlSource:
                         frequency=series_data.get('frequency', 'm'),
                         transformation=series_data.get('transformation', 'lin'),
                         blocks=series_data.get('blocks', []),
-                        release_date=release_date
+                        release_date=release_date,
+                        scaler=series_data.get('scaler', None)  # Optional, for per-series scaling
                     ))
         
         # If no series loaded from separate files, try to get from main config

dfm_python/config/results.py

@@ -6,9 +6,8 @@ This module contains dataclasses for storing DFM estimation results and paramete
 import numpy as np
 import warnings
 from dataclasses import dataclass
-from typing import Optional, List, Dict, Any, Tuple
+from typing import Optional, List, Dict, Any
 from abc import ABC
-from datetime import datetime
 
 from .schema import DFMConfig
 
@@ -279,59 +278,6 @@ class DDFMResult(BaseResult):
     use_idiosyncratic: Optional[bool] = None  # Whether idio components were used
 
 
-@dataclass
-class NowcastResult:
-    """Result from a single nowcast calculation.
-    
-    This dataclass contains all information from a nowcast operation,
-    including the nowcast value, metadata about the data view, and
-    optional diagnostic information.
-    
-    Attributes
-    ----------
-    target_series : str
-        Target series ID that was nowcasted.
-    target_period : datetime
-        Target period for the nowcast (the period being estimated).
-    view_date : datetime
-        View date (when data is available). This determines which
-        data points are masked/unmasked in the nowcast calculation.
-    nowcast_value : float
-        The calculated nowcast value for the target series.
-    confidence_interval : Tuple[float, float], optional
-        Confidence interval (lower, upper) for the nowcast, if available.
-    factors_at_view : np.ndarray, optional
-        Factor values at the view_date (m,). These are the updated
-        factor states after applying the data view masking.
-    dfm_result : BaseResult, optional
-        Full DFM/DDFM result for this view. Can be used for further
-        analysis or diagnostics.
-    data_availability : Dict[str, int], optional
-        Dictionary with keys 'n_available' and 'n_missing' indicating
-        how many data points were available vs missing in the data view.
-    
-    Examples
-    --------
-    >>> from dfm_python import DFM
-    >>> import numpy as np
-    >>> model = DFM()
-    >>> trainer.fit(model, data_module)
-    >>> # Update state with new data, then predict
-    >>> X_std = np.random.randn(10, 5)  # Standardized data
-    >>> model.update(X_std)
-    >>> forecast = model.predict(horizon=1)
-    >>> print(f"Forecast: {forecast[0, 0]}")
-    """
-    target_series: str
-    target_period: datetime
-    view_date: datetime
-    nowcast_value: float
-    confidence_interval: Optional[Tuple[float, float]] = None  # (lower, upper)
-    factors_at_view: Optional[np.ndarray] = None  # Factor values at view_date
-    dfm_result: Optional[BaseResult] = None  # Full DFM/DDFM result for this view
-    data_availability: Optional[Dict[str, int]] = None  # n_available, n_missing
-
-
 @dataclass
 class FitParams:
     """Parameter overrides for DFM model fitting.