dfm-python 0.2.6__py3-none-any.whl → 0.2.7__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.6"
+__version__ = "0.2.7"
 
 from .config import DFMConfig, SeriesConfig, BlockConfig, Params, DEFAULT_GLOBAL_BLOCK_NAME
 from .config import (

dfm_python/core/em.py

@@ -809,8 +809,8 @@ def em_step(params: EMStepParams) -> Tuple[np.ndarray, np.ndarray, np.ndarray, n
                     lambda_ridge = (trace_val / size_val) * 1e-5  # Scale factor
                     EZZ_lag_sub = EZZ_lag_sub + lambda_ridge * np.eye(size_val)
                     # Recompute condition number after regularization
-                    eigenvals = np.linalg.eigvals(EZZ_lag_sub)
-                    cond_num = (np.max(eigenvals) / max(np.min(eigenvals), 1e-12)) if np.max(eigenvals) > 0 else 1.0
+                eigenvals = np.linalg.eigvals(EZZ_lag_sub)
+                cond_num = (np.max(eigenvals) / max(np.min(eigenvals), 1e-12)) if np.max(eigenvals) > 0 else 1.0
                 EZZ_lag_inv = pinv(EZZ_lag_sub, rcond=1e-8) if cond_num > 1e12 else inv(EZZ_lag_sub)
             except _NUMERICAL_EXCEPTIONS:
                 EZZ_lag_inv = pinv(EZZ_lag_sub)
@@ -949,55 +949,55 @@ def em_step(params: EMStepParams) -> Tuple[np.ndarray, np.ndarray, np.ndarray, n
         # Keep C fixed for idio components (not updated in M-step)
     else:
         # Fallback to old approach for backward compatibility
-        i_subset = slice(idio_start_idx, idio_start_idx + n_idio)
-        i_subset_slice = slice(i_subset.start, i_subset.stop)
-        Z_idio = Zsmooth[i_subset_slice, 1:] if idio_start_idx < Zsmooth.shape[1] else np.zeros((n_idio, T))
-        n_idio_actual = Z_idio.shape[0] if Z_idio.shape[0] > 0 else n_idio
-        expected_idio_current_sq = np.sum(Z_idio**2, axis=1)
-        vsmooth_idio_block = vsmooth[i_subset_slice, :, :][:, i_subset_slice, 1:]
-        vsmooth_idio_sum = np.sum(vsmooth_idio_block, axis=2)
-        if vsmooth_idio_sum.ndim == 2 and vsmooth_idio_sum.shape[0] >= n_idio_actual and vsmooth_idio_sum.shape[1] >= n_idio_actual:
-            vsmooth_idio_diag = np.diag(vsmooth_idio_sum[:n_idio_actual, :n_idio_actual])
-        else:
-            vsmooth_idio_diag = np.zeros(n_idio_actual)
-        expected_idio_current_sq = expected_idio_current_sq + vsmooth_idio_diag
-        Z_idio_lag = Zsmooth[i_subset_slice, :-1]
-        expected_idio_lag_sq = np.sum(Z_idio_lag**2, axis=1)
-        vsmooth_lag_block = vsmooth[i_subset_slice, :, :][:, i_subset_slice, :-1]
-        vsmooth_lag_sum = np.sum(vsmooth_lag_block, axis=2)
-        if vsmooth_lag_sum.ndim == 2 and vsmooth_lag_sum.shape[0] >= n_idio_actual and vsmooth_lag_sum.shape[1] >= n_idio_actual:
-            vsmooth_lag_diag = np.diag(vsmooth_lag_sum[:n_idio_actual, :n_idio_actual])
-        else:
-            vsmooth_lag_diag = np.zeros(n_idio_actual)
-        expected_idio_lag_sq = expected_idio_lag_sq + vsmooth_lag_diag
-        min_cols = min(Z_idio.shape[1], Z_idio_lag.shape[1])
-        expected_idio_cross = np.sum(Z_idio[:, :min_cols] * Z_idio_lag[:, :min_cols], axis=1)
-        vvsmooth_block = vvsmooth[i_subset_slice, :, :][:, i_subset_slice, :]
-        vvsmooth_sum = np.sum(vvsmooth_block, axis=2)
-        if vvsmooth_sum.ndim == 2 and vvsmooth_sum.shape[0] >= n_idio_actual and vvsmooth_sum.shape[1] >= n_idio_actual:
-            vvsmooth_diag = np.diag(vvsmooth_sum[:n_idio_actual, :n_idio_actual])
-        else:
-            vvsmooth_diag = np.zeros(n_idio_actual)
-        expected_idio_cross = expected_idio_cross + vvsmooth_diag
-        ar_coeffs_diag, _ = _estimate_ar_coefficient(expected_idio_cross, expected_idio_lag_sq, vsmooth_sum=vsmooth_lag_diag)
-        A_block_idio = np.diag(ar_coeffs_diag)
-        innovation_cov_diag = (np.maximum(expected_idio_current_sq, 0.0) - ar_coeffs_diag * expected_idio_cross) / T
-        innovation_cov_diag = np.maximum(innovation_cov_diag, MIN_INNOVATION_VARIANCE)
-        Q_block_idio = np.diag(innovation_cov_diag)
-        i_subset_size = i_subset.stop - i_subset.start
-        if n_idio_actual == i_subset_size:
-            A_new[i_subset, i_subset] = A_block_idio
-            Q_new[i_subset, i_subset] = Q_block_idio
-        elif n_idio_actual < i_subset_size:
-            A_new[i_subset.start:i_subset.start + n_idio_actual, i_subset.start:i_subset.start + n_idio_actual] = A_block_idio
-            Q_new[i_subset.start:i_subset.start + n_idio_actual, i_subset.start:i_subset.start + n_idio_actual] = Q_block_idio
-        else:
-            A_new[i_subset, i_subset] = A_block_idio[:i_subset_size, :i_subset_size]
-            Q_new[i_subset, i_subset] = Q_block_idio[:i_subset_size, :i_subset_size]
-        vsmooth_sub = vsmooth[i_subset_slice, :, :][:, i_subset_slice, 0]
-        vsmooth_diag = np.diag(vsmooth_sub[:n_idio_actual, :n_idio_actual]) if vsmooth_sub.ndim == 2 else np.zeros(n_idio_actual)
-        for idx in range(min(n_idio_actual, i_subset_size)):
-            V_0_new[i_subset.start + idx, i_subset.start + idx] = vsmooth_diag[idx] if idx < len(vsmooth_diag) else 0.0
+    i_subset = slice(idio_start_idx, idio_start_idx + n_idio)
+    i_subset_slice = slice(i_subset.start, i_subset.stop)
+    Z_idio = Zsmooth[i_subset_slice, 1:] if idio_start_idx < Zsmooth.shape[1] else np.zeros((n_idio, T))
+    n_idio_actual = Z_idio.shape[0] if Z_idio.shape[0] > 0 else n_idio
+    expected_idio_current_sq = np.sum(Z_idio**2, axis=1)
+    vsmooth_idio_block = vsmooth[i_subset_slice, :, :][:, i_subset_slice, 1:]
+    vsmooth_idio_sum = np.sum(vsmooth_idio_block, axis=2)
+    if vsmooth_idio_sum.ndim == 2 and vsmooth_idio_sum.shape[0] >= n_idio_actual and vsmooth_idio_sum.shape[1] >= n_idio_actual:
+        vsmooth_idio_diag = np.diag(vsmooth_idio_sum[:n_idio_actual, :n_idio_actual])
+    else:
+        vsmooth_idio_diag = np.zeros(n_idio_actual)
+    expected_idio_current_sq = expected_idio_current_sq + vsmooth_idio_diag
+    Z_idio_lag = Zsmooth[i_subset_slice, :-1]
+    expected_idio_lag_sq = np.sum(Z_idio_lag**2, axis=1)
+    vsmooth_lag_block = vsmooth[i_subset_slice, :, :][:, i_subset_slice, :-1]
+    vsmooth_lag_sum = np.sum(vsmooth_lag_block, axis=2)
+    if vsmooth_lag_sum.ndim == 2 and vsmooth_lag_sum.shape[0] >= n_idio_actual and vsmooth_lag_sum.shape[1] >= n_idio_actual:
+        vsmooth_lag_diag = np.diag(vsmooth_lag_sum[:n_idio_actual, :n_idio_actual])
+    else:
+        vsmooth_lag_diag = np.zeros(n_idio_actual)
+    expected_idio_lag_sq = expected_idio_lag_sq + vsmooth_lag_diag
+    min_cols = min(Z_idio.shape[1], Z_idio_lag.shape[1])
+    expected_idio_cross = np.sum(Z_idio[:, :min_cols] * Z_idio_lag[:, :min_cols], axis=1)
+    vvsmooth_block = vvsmooth[i_subset_slice, :, :][:, i_subset_slice, :]
+    vvsmooth_sum = np.sum(vvsmooth_block, axis=2)
+    if vvsmooth_sum.ndim == 2 and vvsmooth_sum.shape[0] >= n_idio_actual and vvsmooth_sum.shape[1] >= n_idio_actual:
+        vvsmooth_diag = np.diag(vvsmooth_sum[:n_idio_actual, :n_idio_actual])
+    else:
+        vvsmooth_diag = np.zeros(n_idio_actual)
+    expected_idio_cross = expected_idio_cross + vvsmooth_diag
+    ar_coeffs_diag, _ = _estimate_ar_coefficient(expected_idio_cross, expected_idio_lag_sq, vsmooth_sum=vsmooth_lag_diag)
+    A_block_idio = np.diag(ar_coeffs_diag)
+    innovation_cov_diag = (np.maximum(expected_idio_current_sq, 0.0) - ar_coeffs_diag * expected_idio_cross) / T
+    innovation_cov_diag = np.maximum(innovation_cov_diag, MIN_INNOVATION_VARIANCE)
+    Q_block_idio = np.diag(innovation_cov_diag)
+    i_subset_size = i_subset.stop - i_subset.start
+    if n_idio_actual == i_subset_size:
+        A_new[i_subset, i_subset] = A_block_idio
+        Q_new[i_subset, i_subset] = Q_block_idio
+    elif n_idio_actual < i_subset_size:
+        A_new[i_subset.start:i_subset.start + n_idio_actual, i_subset.start:i_subset.start + n_idio_actual] = A_block_idio
+        Q_new[i_subset.start:i_subset.start + n_idio_actual, i_subset.start:i_subset.start + n_idio_actual] = Q_block_idio
+    else:
+        A_new[i_subset, i_subset] = A_block_idio[:i_subset_size, :i_subset_size]
+        Q_new[i_subset, i_subset] = Q_block_idio[:i_subset_size, :i_subset_size]
+    vsmooth_sub = vsmooth[i_subset_slice, :, :][:, i_subset_slice, 0]
+    vsmooth_diag = np.diag(vsmooth_sub[:n_idio_actual, :n_idio_actual]) if vsmooth_sub.ndim == 2 else np.zeros(n_idio_actual)
+    for idx in range(min(n_idio_actual, i_subset_size)):
+        V_0_new[i_subset.start + idx, i_subset.start + idx] = vsmooth_diag[idx] if idx < len(vsmooth_diag) else 0.0
 
     Z_0 = Zsmooth[0, :].copy()
     nanY = np.isnan(y)
@@ -1247,33 +1247,39 @@ def em_step(params: EMStepParams) -> Tuple[np.ndarray, np.ndarray, np.ndarray, n
     # 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)
+    # Normalize C for clock-frequency factors to prevent scale issues
+    # Only normalize if C norm is in reasonable range (not too small, not too large)
+    # This prevents Q from becoming too small (when C norm is small) or too large (when C norm is large)
     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:
-                # 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, 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_clipped
-                        Q_new[k, j] = Q_new[k, j] * norm_clipped
+        # Check if there are slower-frequency series (tent weight constraints)
+        has_slower_freq = (frequencies is not None and 
+                          any(freq != clock for freq in frequencies if freq is not None))
+        
+        # Only normalize if no slower-frequency series (to avoid violating tent weight constraints)
+        if not has_slower_freq:
+            for j in range(num_clock_factors):
+                norm = np.linalg.norm(C_new[:, j])
+                if norm > 1e-8:
+                    # Only normalize if norm is in reasonable range
+                    # Too small norm (< 0.1) would make Q too small
+                    # Too large norm (> 10) would make Q too large
+                    C_norm_min = 0.1  # Minimum norm to normalize
+                    C_norm_cap = safe_get_attr(config, "max_loading_norm", 10.0) if config is not None else 10.0
+                    
+                    if C_norm_min <= norm <= C_norm_cap:
+                        # Normalize C column
+                        C_new[:, j] = C_new[:, j] / norm
+                        
+                        # Adjust Q to preserve variance: Q[j,j] *= norm^2
+                        Q_adjustment = norm ** 2
+                        Q_new[j, j] = Q_new[j, j] * Q_adjustment
+                        
+                        # Off-diagonal: Q[j,k] and Q[k,j] *= norm (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
+                    # If norm is too small or too large, skip normalization to preserve stability
         
         # 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)

dfm_python/core/numeric.py

@@ -605,14 +605,14 @@ def _safe_determinant(M: np.ndarray, use_logdet: bool = True) -> float:
                     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)
+                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)
+                if np.isfinite(det):
+                    return float(det)
                 except Exception:
                     pass
         except (np.linalg.LinAlgError, ValueError, OverflowError, RuntimeWarning):

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfm-python
-Version: 0.2.6
+Version: 0.2.7
 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,20 @@ Demonstrates:
 
 ## Project Status
 
-**Version**: 0.2.6  
+**Version**: 0.2.7  
 **Status**: Stable and production-ready  
 **Python**: 3.10+  
 **PyPI**: https://pypi.org/project/dfm-python/
 
-### Recent Improvements (v0.2.6)
+### Recent Improvements (v0.2.7)
+
+- ✅ **Fixed C normalization issue**: C normalization now only applies when C norm is in reasonable range (0.1 ~ 10)
+  - Prevents Q from becoming too small when C norm is very small
+  - Prevents factor values from becoming extreme
+- ✅ **Improved stability**: Conditional C normalization prevents pathological factor paths
+- ✅ **Better diagnostics**: Added variance guard binding checks in tutorial
+
+### Previous 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
@@ -758,7 +766,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.6}
+  version = {0.2.7}
 }
 ```
 

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

@@ -1,4 +1,4 @@
-dfm_python/__init__.py,sha256=arYgbDHYx9jgEjCZ1JMKZO4cZewBc1j-iXi_g6SDu4o,5589
+dfm_python/__init__.py,sha256=YYhRgV773DAFbaTrfF6LVF45rmbR8SpsH6LOYtDAHnU,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=nNLL179l_SYSowxtnZBHFpEDR_54FOU_tNyn8XaVwnU,72357
+dfm_python/core/em.py,sha256=ltMVW1izAVmMwwYKf3GIFLAP-nLAgGy9zdOenuK-SiU,72509
 dfm_python/core/helpers.py,sha256=XJvWWEZlUqozBfFNcENKgbOOFkwlm-tGwO-u0LnAf-E,31541
-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,,
+dfm_python/core/numeric.py,sha256=__uwDgRj3TV4S0vXhNc_93kk8U6ewtW8smk0OBZLbdg,26403
+dfm_python-0.2.7.dist-info/METADATA,sha256=ZeeKWsk4BkRbihDNjkLkOq-DofODB9RhwG7dxMRIbQI,28599
+dfm_python-0.2.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dfm_python-0.2.7.dist-info/licenses/LICENSE,sha256=6e87br6LCDHjy2hdIR1-sdBQy351qdmSEbOg6jQ7ZXY,1063
+dfm_python-0.2.7.dist-info/RECORD,,