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

dfm_python/__init__.py

@@ -6,7 +6,6 @@ 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 
@@ -23,7 +22,6 @@ 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
@@ -67,7 +65,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.11"
+__version__ = "0.5.5"
 
 # ============================================================================
 # PUBLIC API DEFINITION
@@ -81,15 +79,14 @@ __version__ = "0.5.11"
 # 2. High-level API: DFM, DDFM, module-level convenience functions
 # 3. Core utilities: TimeIndex, diagnostics
 # 4. Models: BaseFactorModel, DDFM (low-level)
-# 5. Nowcasting: Nowcast, result classes, para_const
-# 6. Data & Results: DFMResult
+# 5. Data & Results: DFMResult
 # ============================================================================
 
 # Configuration (from config/ subpackage)
 from .config import (
     DEFAULT_BLOCK_NAME,
-    ConfigSource, YamlSource, DictSource, HydraSource,
-    MergedConfigSource, make_config_source,
+    ConfigSource, YamlSource, HydraSource,
+    make_config_source,
 )
 # Internal imports (for backward compatibility, but not recommended)
 from .config import DFMConfig, SeriesConfig  # Internal use only
@@ -105,56 +102,45 @@ 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
 
-# DDFM high-level API and low-level model (PyTorch is mandatory)
-from .models.ddfm import DDFM, DDFMModel
+# DDFM high-level API (PyTorch is mandatory)
+from .models.ddfm import DDFM
 
 __all__ = [
     # Core classes
-    'DFM', 'Nowcast',
+    'DFM',
     # Model base and implementations
     'BaseFactorModel',
-    # Nowcast result classes
-    'NowcastResult', 'NewsDecompResult', 'BacktestResult',
     # Constants
     'DEFAULT_BLOCK_NAME',
     # Config sources
-    'ConfigSource', 'YamlSource', 'DictSource', 'HydraSource',
-    'MergedConfigSource', 'make_config_source',
+    'ConfigSource', 'YamlSource', 'HydraSource',
+    '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)
 __all__.extend([
     'DDFM',  # High-level API class
-    'DDFMModel',  # Low-level implementation (used internally)
 ])
 
 # 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

@@ -208,14 +208,16 @@ class YamlSource:
                         except (ValueError, TypeError):
                             release_date = None
                     
+                    # Remove transformation and blocks if present (not in SeriesConfig)
+                    series_data_clean = {k: v for k, v in series_data.items() 
+                                       if k not in ['transformation', 'blocks']}
                     series_list.append(SeriesConfig(
                         series_id=series_id,
-                        series_name=series_data.get('series_name', series_id),
-                        frequency=series_data.get('frequency', 'm'),
-                        transformation=series_data.get('transformation', 'lin'),
-                        blocks=series_data.get('blocks', []),
-                        release_date=release_date,
-                        scaler=series_data.get('scaler', None)  # Optional, for per-series scaling
+                        series_name=series_data_clean.get('series_name', series_id),
+                        frequency=series_data_clean.get('frequency', 'm'),
+                        # transformation removed - handled by preprocessing pipeline
+                        # blocks removed - defined in DFMConfig
+                        release_date=series_data_clean.get('release_date', release_date)
                     ))
         
         # If no series loaded from separate files, try to get from main config
@@ -225,17 +227,23 @@ class YamlSource:
                 for series_item in series_data:
                     if isinstance(series_item, str):
                         # Series is just a string ID - create minimal config
-                        series_list.append(SeriesConfig(series_id=series_item, frequency='m', transformation='lin', blocks=[1]))
+                        series_list.append(SeriesConfig(series_id=series_item, frequency='m'))
                     elif isinstance(series_item, dict):
-                        series_list.append(SeriesConfig(**series_item))
+                        # Remove transformation and blocks if present (not in SeriesConfig)
+                        series_item_clean = {k: v for k, v in series_item.items() 
+                                           if k not in ['transformation', 'blocks']}
+                        series_list.append(SeriesConfig(**series_item_clean))
             elif isinstance(series_data, dict):
                 for series_id, series_item in series_data.items():
                     if isinstance(series_item, dict):
                         series_item['series_id'] = series_id
-                        series_list.append(SeriesConfig(**series_item))
+                        # Remove transformation and blocks if present (not in SeriesConfig)
+                        series_item_clean = {k: v for k, v in series_item.items() 
+                                           if k not in ['transformation', 'blocks']}
+                        series_list.append(SeriesConfig(**series_item_clean))
                     elif isinstance(series_item, str):
                         # Series value is just a string - create minimal config
-                        series_list.append(SeriesConfig(series_id=series_id, frequency='m', transformation='lin', blocks=[1]))
+                        series_list.append(SeriesConfig(series_id=series_id, frequency='m'))
         
         # Load block properties from model config (factors, ar_lag, clock)
         # Model config defines all blocks and their properties
@@ -251,28 +259,8 @@ class YamlSource:
         if blocks_dict_raw is not None:
             blocks_properties_from_config.update(blocks_dict_raw)
         
-        # Derive blocks from series configs (new pattern: blocks discovered from series)
-        # Collect all unique block names from series
-        block_names_from_series = set()
-        for series in series_list:
-            if hasattr(series, 'blocks') and series.blocks:
-                # Handle both list of strings and list of ints
-                if isinstance(series.blocks, list):
-                    for block in series.blocks:
-                        if isinstance(block, str):
-                            block_names_from_series.add(block)
-        
-        # If no blocks specified in series, use default single block
-        # Use first block from model config if available, otherwise create default
-        if not block_names_from_series:
-            # Check if model config defines blocks
-            if blocks_properties_from_config:
-                # Use first block from model config
-                first_block_name = list(blocks_properties_from_config.keys())[0]
-                block_names_from_series.add(first_block_name)
-            else:
-                # Create default generic block
-                block_names_from_series.add(DEFAULT_BLOCK_NAME)
+        # Note: SeriesConfig no longer contains blocks information.
+        # Blocks are defined in DFMConfig, not in SeriesConfig.
         
         # Create block dicts for each block
         # Priority: 1) Model config properties, 2) Defaults from main_settings
@@ -297,24 +285,13 @@ class YamlSource:
                     'clock': default_clock
                 }
         
-        # Then, ensure all blocks referenced by series exist
-        for block_name in block_names_from_series:
-            if block_name not in blocks_dict:
-                # Create block with defaults if not in model config
-                blocks_dict[block_name] = {
-                    'factors': 1,
-                    'ar_lag': default_ar_lag,
-                    'clock': default_clock
-                }
-        
-        # Convert block names to list for from_dict() if series use integer block indices
-        # Check if series use integer indices instead of block names
-        block_names_list = None
-        if series_list:
-            first_series_blocks = series_list[0].blocks if hasattr(series_list[0], 'blocks') else []
-            if first_series_blocks and isinstance(first_series_blocks[0], int):
-                # Series use integer indices, need block_names for from_dict()
-                block_names_list = list(blocks_dict.keys())
+        # If no blocks specified in config, use default single block
+        if not blocks_dict:
+            blocks_dict[DEFAULT_BLOCK_NAME] = {
+                'factors': 1,
+                'ar_lag': default_ar_lag,
+                'clock': default_clock
+            }
         
         # Build dictionary for from_dict() which handles type detection
         # Include all main_settings (which may contain DDFM parameters from model config)
@@ -324,10 +301,6 @@ class YamlSource:
             **main_settings
         }
         
-        # Add block_names if series use integer indices
-        if block_names_list is not None:
-            config_dict['block_names'] = block_names_list
-        
         # Use from_dict() which now correctly detects DDFM configs
         # The detection bug has been fixed in schema.py
         return DFMConfig.from_dict(config_dict)
@@ -645,12 +618,16 @@ if HYDRA_AVAILABLE and ConfigStore is not None:
             
             @schema_dataclass
             class SeriesConfigSchema:
-                """Schema for SeriesConfig validation in Hydra."""
+                """Schema for SeriesConfig validation in Hydra.
+                
+                Note: transformation is handled by preprocessing pipeline, not in SeriesConfig.
+                Note: blocks are defined in DFMConfig, not in SeriesConfig.
+                """
                 series_id: str
                 series_name: str
                 frequency: str
-                transformation: str
-                blocks: ListType[int]
+                # transformation removed - handled by preprocessing pipeline
+                # blocks removed - defined in DFMConfig
                 units: Optional[str] = None  # Optional, for display only
             
             @schema_dataclass

dfm_python/config/results.py

@@ -6,8 +6,9 @@ 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
+from typing import Optional, List, Dict, Any, Tuple
 from abc import ABC
+from datetime import datetime
 
 from .schema import DFMConfig
 
@@ -278,6 +279,59 @@ 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.