dfm-python 0.2.5__py3-none-any.whl → 0.2.6__py3-none-any.whl

dfm_python/__init__.py

@@ -50,7 +50,7 @@ Example (Low-level API - For advanced usage):
 For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.2.5"
+__version__ = "0.2.6"
 
 from .config import DFMConfig, SeriesConfig, BlockConfig, Params, DEFAULT_GLOBAL_BLOCK_NAME
 from .config import (

dfm_python/core/em.py

@@ -368,7 +368,20 @@ def init_conditions(x, r, p, blocks, opt_nan, Rcon, q, nQ, i_idio, clock='m', te
                                         # Store loadings (only up to available columns in C_block)
                                         n_loadings = min(pC_freq * r_i, C_block.shape[1])
                                         if n_loadings > 0:
-                                            C_block[j, :n_loadings] = loadings[:n_loadings]
+                                            # Clip initial loadings to prevent extreme values
+                                            # This helps prevent Q explosion during C normalization
+                                            max_loading_norm = safe_get_attr(config, "max_loading_norm", 10.0) if config is not None else 10.0
+                                            # Clip loadings: if norm is too large, scale down
+                                            loadings_to_store = loadings[:n_loadings]
+                                            if loadings_to_store.ndim == 1:
+                                                # Vector case: clip by norm
+                                                loading_norm = np.linalg.norm(loadings_to_store)
+                                                if loading_norm > max_loading_norm:
+                                                    loadings_to_store = loadings_to_store * (max_loading_norm / loading_norm)
+                                            else:
+                                                # Multi-dimensional: clip each element
+                                                loadings_to_store = np.clip(loadings_to_store, -max_loading_norm, max_loading_norm)
+                                            C_block[j, :n_loadings] = loadings_to_store
                                     except Exception:
                                         # If constrained LS fails, use unconstrained (fallback)
                                         try:
@@ -377,7 +390,19 @@ def init_conditions(x, r, p, blocks, opt_nan, Rcon, q, nQ, i_idio, clock='m', te
                                             loadings = gram_inv @ factor_projection_clean.T @ series_data_clean
                                             n_loadings = min(pC_freq * r_i, C_block.shape[1])
                                             if n_loadings > 0:
-                                                C_block[j, :n_loadings] = loadings[:n_loadings]
+                                                # Clip initial loadings to prevent extreme values
+                                                max_loading_norm = safe_get_attr(config, "max_loading_norm", 10.0) if config is not None else 10.0
+                                                # Clip loadings: if norm is too large, scale down
+                                                loadings_to_store = loadings[:n_loadings]
+                                                if loadings_to_store.ndim == 1:
+                                                    # Vector case: clip by norm
+                                                    loading_norm = np.linalg.norm(loadings_to_store)
+                                                    if loading_norm > max_loading_norm:
+                                                        loadings_to_store = loadings_to_store * (max_loading_norm / loading_norm)
+                                                else:
+                                                    # Multi-dimensional: clip each element
+                                                    loadings_to_store = np.clip(loadings_to_store, -max_loading_norm, max_loading_norm)
+                                                C_block[j, :n_loadings] = loadings_to_store
                                         except Exception:
                                             pass  # Leave as zeros
                         except Exception:
@@ -1180,6 +1205,12 @@ def em_step(params: EMStepParams) -> Tuple[np.ndarray, np.ndarray, np.ndarray, n
     # Hard floor: enforce min diagonal on R (≥ 1e-8)
     idio_min_var = getattr(config, 'idio_min_var', 1e-8) if config is not None else 1e-8
     R_diag = np.maximum(R_diag, idio_min_var)
+    
+    # R cap to prevent explosion: maximum allowed observation error variance
+    # For standardized data, R should typically be < 10
+    R_cap = safe_get_attr(config, "max_observation_variance", 10.0) if config is not None else 10.0
+    R_diag = np.minimum(R_diag, R_cap)
+    
     R_new = np.diag(R_diag)
     
     # Final stability operations
@@ -1212,22 +1243,55 @@ def em_step(params: EMStepParams) -> Tuple[np.ndarray, np.ndarray, np.ndarray, n
     has_slower_freq = (frequencies is not None and 
                       any(freq != clock for freq in frequencies if freq is not None))
     num_clock_factors = int(np.sum(r))  # Only clock-frequency factors (ppC=1 part)
-    if num_clock_factors > 0 and not has_slower_freq:
+    
+    # Q cap to prevent explosion: maximum allowed innovation variance for factors
+    Q_cap_factor = safe_get_attr(config, "max_innovation_variance", 1.0) if config is not None else 1.0
+    
+    # Always normalize C for clock-frequency factors to prevent scale issues
+    # Even if there are slower-frequency series, we can still normalize clock-frequency factors
+    # (tent weight constraints only apply to slower-frequency parts, not clock-frequency parts)
+    if num_clock_factors > 0:
         # Only normalize if there are no slower-frequency series
         # (to avoid violating tent weight constraints)
         for j in range(num_clock_factors):
             norm = np.linalg.norm(C_new[:, j])
             if norm > 1e-8:
-                # Normalize C column
+                # Improved normalization: clip C norm before normalization to prevent Q explosion
+                # If C norm is too large, we cap it to prevent Q from becoming extreme
+                C_norm_cap = safe_get_attr(config, "max_loading_norm", 10.0) if config is not None else 10.0
+                norm_clipped = min(norm, C_norm_cap)
+                
+                # Normalize C column (using clipped norm to prevent extreme Q)
                 C_new[:, j] = C_new[:, j] / norm
-                # Adjust Q to preserve variance
-                # Diagonal: Q[j,j] *= norm^2
-                Q_new[j, j] = Q_new[j, j] * (norm ** 2)
-                # Off-diagonal: Q[j,k] and Q[k,j] *= norm (for k != j)
+                
+                # Adjust Q to preserve variance, but use clipped norm to prevent explosion
+                # This is a compromise: we normalize C fully but limit Q adjustment
+                Q_adjustment = norm_clipped ** 2
+                Q_new[j, j] = Q_new[j, j] * Q_adjustment
+                
+                # Off-diagonal: Q[j,k] and Q[k,j] *= norm_clipped (for k != j)
                 for k in range(Q_new.shape[0]):
                     if k != j:
-                        Q_new[j, k] = Q_new[j, k] * norm
-                        Q_new[k, j] = Q_new[k, j] * norm
+                        Q_new[j, k] = Q_new[j, k] * norm_clipped
+                        Q_new[k, j] = Q_new[k, j] * norm_clipped
+        
+        # Re-apply Q floor and cap after C normalization to prevent extreme values
+        # C normalization can make Q very large (if C norm was large) or very small (if C norm was small)
+        Q_diag_after_norm = np.diag(Q_new).copy()
+        if num_factors > 0:
+            # Apply both floor and cap to factors after normalization
+            Q_diag_after_norm[:num_factors] = np.clip(
+                Q_diag_after_norm[:num_factors],
+                Q_min_factor,  # Floor: 0.01
+                Q_cap_factor   # Cap: 1.0 (configurable)
+            )
+            # Preserve idio components (only floor, no cap needed)
+            if num_factors < len(Q_diag_after_norm):
+                Q_diag_after_norm[num_factors:] = np.maximum(Q_diag_after_norm[num_factors:], idio_min_var)
+        else:
+            Q_diag_after_norm = np.maximum(Q_diag_after_norm, idio_min_var)
+        # Update Q with re-applied floor and cap
+        Q_new = np.diag(Q_diag_after_norm) + (Q_new - np.diag(np.diag(Q_new)))  # Preserve off-diagonal
     
     # Spectral radius cap on A (< 0.99) with minimal shrinkage
     eigenvals_A = np.linalg.eigvals(A_new)

dfm_python/core/numeric.py

@@ -598,20 +598,23 @@ def _safe_determinant(M: np.ndarray, use_logdet: bool = True) -> float:
                 if np.isfinite(det) and det > 0:
                     return float(det)
             except np.linalg.LinAlgError:
-                # Not PSD, use LU decomposition
-                P, L, U = np.linalg.lu(M)
-                log_det = np.sum(np.log(np.abs(np.diag(U))))
-                # Check if log_det is too large to avoid overflow in exp
-                if log_det > 700:
-                    _logger.debug("_safe_determinant: log_det too large, returning 0.0")
-                    return 0.0
-                # Account for permutation sign
-                sign = np.linalg.det(P) if P.shape[0] <= 10 else 1.0
-                with warnings.catch_warnings():
-                    warnings.filterwarnings('ignore', category=RuntimeWarning)
-                    det = sign * np.exp(log_det)
-                if np.isfinite(det):
-                    return float(det)
+                # Not PSD: fall back to slogdet for general matrices
+                try:
+                    sign, log_det = np.linalg.slogdet(M)
+                    # If determinant is non-positive or invalid, return 0.0
+                    if not np.isfinite(log_det) or sign <= 0:
+                        return 0.0
+                    # Avoid overflow in exp
+                    if log_det > 700:
+                        _logger.debug("_safe_determinant: log_det too large, returning 0.0")
+                        return 0.0
+                    with warnings.catch_warnings():
+                        warnings.filterwarnings('ignore', category=RuntimeWarning)
+                        det = np.exp(log_det)
+                    if np.isfinite(det):
+                        return float(det)
+                except Exception:
+                    pass
         except (np.linalg.LinAlgError, ValueError, OverflowError, RuntimeWarning):
             pass
     

{dfm_python-0.2.5.dist-info → dfm_python-0.2.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfm-python
-Version: 0.2.5
+Version: 0.2.6
 Summary: Dynamic Factor Model (DFM) estimation and nowcasting in Python
 Project-URL: Homepage, https://github.com/yourusername/dfm-python
 Project-URL: Documentation, https://github.com/yourusername/dfm-python#readme
@@ -709,12 +709,21 @@ Demonstrates:
 
 ## Project Status
 
-**Version**: 0.2.5  
+**Version**: 0.2.6  
 **Status**: Stable and production-ready  
 **Python**: 3.10+  
 **PyPI**: https://pypi.org/project/dfm-python/
 
-### Recent Improvements (v0.2.5)
+### Recent Improvements (v0.2.6)
+
+- ✅ **Q matrix cap**: Factor innovation variances bounded above by 1.0 to prevent explosion
+- ✅ **R matrix cap**: Observation error variances bounded above by 10.0 for standardized data
+- ✅ **Improved C normalization**: C norm clipping prevents Q explosion during normalization
+- ✅ **Enhanced initial values**: PCA loadings clipped to prevent extreme initial values
+- ✅ **Bug fix**: Fixed `np.linalg.lu` error by using `np.linalg.slogdet` for determinant computation
+- ✅ **Better stability**: Q and R caps ensure model convergence even with challenging data
+
+### Previous Improvements (v0.2.5)
 
 - ✅ **Q matrix floor**: Factor innovation variances bounded below by 0.01 to prevent scale issues
 - ✅ **C matrix normalization**: Clock-frequency factor loadings normalized (||C[:,j]|| = 1) for scale stability
@@ -749,7 +758,7 @@ If you use `dfm-python` in your research, please cite:
   author = {DFM Python Contributors},
   year = {2025},
   url = {https://pypi.org/project/dfm-python/},
-  version = {0.2.5}
+  version = {0.2.6}
 }
 ```
 

{dfm_python-0.2.5.dist-info → dfm_python-0.2.6.dist-info}/RECORD

@@ -1,4 +1,4 @@
-dfm_python/__init__.py,sha256=8_xxzeEMbtdKxcjH48IytqGh3uSaGJnl8Q8JnCFFLhs,5589
+dfm_python/__init__.py,sha256=arYgbDHYx9jgEjCZ1JMKZO4cZewBc1j-iXi_g6SDu4o,5589
 dfm_python/api.py,sha256=-mmV7aaXOAqVW9HPhTEut7T6wN1EyW0rS3J0y-z-MRs,16221
 dfm_python/config.py,sha256=bBiKfoETohNVJ3brRbY1330C1nQROybCR3co9iagIKs,46978
 dfm_python/config_sources.py,sha256=6LTK7k5WJpnayMmtxtYwZ9SQi_hGXoz-Vg4sRGTabI0,21798
@@ -9,10 +9,10 @@ dfm_python/news.py,sha256=iXbJnsvH5FgKToPzKnqIpTosrZu-QHXBNHjsqwMYrHo,32583
 dfm_python/utils.py,sha256=qOAJm2KG71yP2a29iJVDGOC-ZUS_HPL5oAo16EgNXA4,15709
 dfm_python/core/__init__.py,sha256=oDrhAoc1W_ODohgufQ-gN0uri8-vZI0EXsF0dysth_A,331
 dfm_python/core/diagnostics.py,sha256=2Cm8XIN5jE9jL3FssEUmZNQy12FPuKvYs1k3bYKAySw,20224
-dfm_python/core/em.py,sha256=Y1kICJfdNyAWsWYxxJANp4TAiQ__iVR5wwhNw6h0qC0,67571
+dfm_python/core/em.py,sha256=nNLL179l_SYSowxtnZBHFpEDR_54FOU_tNyn8XaVwnU,72357
 dfm_python/core/helpers.py,sha256=XJvWWEZlUqozBfFNcENKgbOOFkwlm-tGwO-u0LnAf-E,31541
-dfm_python/core/numeric.py,sha256=CsufWu5feWdRjjrhGL7pKxwq5CFkaBn-1l3t1v35YQI,26323
-dfm_python-0.2.5.dist-info/METADATA,sha256=rmEAZQ0C4RPO7h4G3JJhu6Kq1itjD4dif_aH_2O121w,27552
-dfm_python-0.2.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dfm_python-0.2.5.dist-info/licenses/LICENSE,sha256=6e87br6LCDHjy2hdIR1-sdBQy351qdmSEbOg6jQ7ZXY,1063
-dfm_python-0.2.5.dist-info/RECORD,,
+dfm_python/core/numeric.py,sha256=IcIwcKtMhIoJ5-7Mz6UNYwTUtEa5W_ZMnQtF87v0SSc,26431
+dfm_python-0.2.6.dist-info/METADATA,sha256=DnwocbXu0WC8ruBF1GSU2PQINCNSYjxMlGrQlRXVWs0,28159
+dfm_python-0.2.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dfm_python-0.2.6.dist-info/licenses/LICENSE,sha256=6e87br6LCDHjy2hdIR1-sdBQy351qdmSEbOg6jQ7ZXY,1063
+dfm_python-0.2.6.dist-info/RECORD,,