dfm-python 0.4.9__py3-none-any.whl → 0.5.0__py3-none-any.whl

dfm_python/__init__.py

@@ -65,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.4.9"
+__version__ = "0.5.0"
 
 # ============================================================================
 # PUBLIC API DEFINITION
@@ -107,8 +107,6 @@ from .lightning import (
     EMAlgorithm,  # Module class
 )
 
-# Nowcasting removed - use src.nowcast instead
-
 # Model implementations
 from .models.base import BaseFactorModel
 from .models.dfm import DFM

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,57 @@ 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
+    >>> model = DFM()
+    >>> trainer.fit(model, data_module)
+    >>> # Get nowcast with full result
+    >>> result = model.nowcast('gdp', view_date='2024-01-15', return_result=True)
+    >>> print(f"Nowcast: {result.nowcast_value}")
+    >>> print(f"Available data: {result.data_availability['n_available']}")
+    """
+    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.

dfm_python/data/__init__.py

@@ -4,6 +4,7 @@ This module provides:
 - Dataset classes: DFMDataset (linear DFM), DDFMDataset (deep DDFM)
 - DataLoader factories: create_dfm_dataloader, create_ddfm_dataloader
 - Data reading: read_data, load_data
+- Nowcast data classes moved to src.nowcasting in main project
 
 Note: Transformation functions are application-specific and should be provided
 by users in their preprocessing pipelines. The package does not include
@@ -13,6 +14,7 @@ transformation utilities to remain generic.
 from .dataset import DFMDataset, DDFMDataset
 from .dataloader import create_dfm_dataloader, create_ddfm_dataloader
 from .utils import read_data, load_data
+# Nowcast data classes moved to src.nowcasting in main project
 
 __all__ = [
     # Datasets

dfm_python/data/utils.py

@@ -17,7 +17,6 @@ from ..config import DFMConfig
 from ..config.utils import FREQUENCY_HIERARCHY
 from ..utils.time import TimeIndex, parse_timestamp
 from ..utils.helpers import (
-    safe_get_attr,
     get_frequencies,
     get_series_ids,
 )
@@ -267,7 +266,7 @@ def load_data(
     _logger.info(f"Loaded data: {X.shape[0]} time periods, {X.shape[1]} series (raw, not transformed)")
     
     # Validate data quality
-    clock = safe_get_attr(config, 'clock', 'm')
+    clock = getattr(config, 'clock', 'm')
     clock_hierarchy = FREQUENCY_HIERARCHY.get(clock, 3)
     
     frequencies = get_frequencies(config)

dfm_python/lightning/data_module.py

@@ -182,34 +182,76 @@ def _get_scale(scaler: Any, data: np.ndarray) -> Optional[np.ndarray]:
 def _normalize_wx(wx: np.ndarray) -> np.ndarray:
     """Normalize Wx to avoid division by zero.
     
+    This function replaces zero or NaN values in Wx with 1.0 to prevent
+    division by zero during standardization/unstandardization.
+    
     Parameters
     ----------
     wx : np.ndarray
-        Scale values (N,)
+        Scale values (N,), may contain zeros or NaN
         
     Returns
     -------
     np.ndarray
-        Normalized scale values with zeros replaced by 1.0
+        Normalized scale values with zeros and NaN replaced by 1.0
     """
-    return np.where(wx == 0, 1.0, wx)
+    # Replace both zero and NaN with 1.0
+    return np.where((wx == 0) | np.isnan(wx), 1.0, wx)
 
 
 def _compute_mx_wx(data: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
     """Compute Mx and Wx from data as fallback.
     
+    This function computes mean (Mx) and standard deviation (Wx) from data,
+    handling missing values (NaN) by using nan-aware functions. If NaN values
+    are detected, a warning is issued recommending imputation.
+    
     Parameters
     ----------
     data : np.ndarray
-        Processed data array (T x N)
+        Processed data array (T x N), may contain NaN values
         
     Returns
     -------
     Tuple[np.ndarray, np.ndarray]
-        (Mx, Wx) tuple where Mx is mean and Wx is normalized std
+        (Mx, Wx) tuple where Mx is mean and Wx is normalized std.
+        NaN values are handled using nanmean and nanstd.
+        
+    Notes
+    -----
+    If data contains NaN values, this function will:
+    1. Use np.nanmean() and np.nanstd() to compute statistics ignoring NaN
+    2. Issue a warning recommending data imputation for better results
+    3. Continue processing with available data
     """
-    mx = np.mean(data, axis=0)
-    wx = np.std(data, axis=0)
+    # Check for NaN values
+    has_nan = np.any(np.isnan(data))
+    if has_nan:
+        nan_count = np.sum(np.isnan(data))
+        nan_pct = 100.0 * nan_count / data.size
+        _logger.warning(
+            f"Data contains {nan_count} NaN values ({nan_pct:.1f}%). "
+            f"Using nanmean/nanstd to compute standardization parameters. "
+            f"For better results, consider imputing missing values before creating DataModule. "
+            f"Suggested approaches: forward-fill, backward-fill, or interpolation."
+        )
+    
+    # Use nan-aware functions to handle missing values
+    mx = np.nanmean(data, axis=0)
+    wx = np.nanstd(data, axis=0)
+    
+    # Check if any series have all NaN values (would result in NaN std)
+    nan_std_mask = np.isnan(wx)
+    if np.any(nan_std_mask):
+        n_nan_std = np.sum(nan_std_mask)
+        _logger.warning(
+            f"{n_nan_std} series have all NaN values, resulting in NaN standard deviation. "
+            f"These will be normalized to 1.0 to avoid division by zero. "
+            f"Consider imputing or removing these series."
+        )
+        # Replace NaN std with 1.0 (will be normalized by _normalize_wx anyway)
+        wx = np.where(nan_std_mask, 1.0, wx)
+    
     wx = _normalize_wx(wx)
     return mx, wx