systemgmmkit 0.5.4__tar.gz → 0.5.6__tar.gz

{systemgmmkit-0.5.4/src/systemgmmkit.egg-info → systemgmmkit-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: systemgmmkit
-Version: 0.5.4
+Version: 0.5.6
 Summary: Generic panel-data econometrics workflow helpers for FE, RE, IV/2SLS, and Difference/System GMM in Python.
 Author: Oluwajuwon Mayomi Akanbi
 License-Expression: MIT
@@ -780,30 +780,25 @@ For dynamic-panel GMM, users should record at minimum:
 
 ## Validation roadmap
 
-Before claiming broader production certification across panel designs, the package should continue to be tested on:
+## Validation roadmap
 
-* balanced panels;
-* unbalanced panels;
-* short-`T` panels;
-* longer-`T` panels;
-* high-`N`, low-`T` panels;
-* panels with missing observations;
-* different lag windows;
-* models with no controls;
-* models with many controls;
-* interaction-heavy specifications;
-* decomposition specifications;
-* alternative instrument classifications;
-* Stata `xtabond2` replication benchmarks.
-
-High-priority remaining validation items:
-
-* broader System GMM parity across additional empirical specifications;
-* broader Windmeijer-corrected standard-error parity across additional empirical specifications;
-* broader robustness of Sargan, Hansen, and AR diagnostics across additional panel structures;
-* documentation of exact Stata-compatible options and known non-equivalence cases.
-
-This roadmap protects the package from overclaiming and supports academically defensible validation.
+The current validation suite establishes benchmark-specific certification for the maintained native Difference GMM and native System GMM paths.
+
+Native System GMM is certified against Stata `xtabond2` for the maintained collapsed two-step benchmark suite, including the baseline, no-controls, three-way interaction, and decomposition specifications. Certified quantities include sample size, group count, instrument count, coefficient estimates, Hansen diagnostics, Windmeijer-corrected two-step standard errors, and signed Arellano-Bond AR(1)/AR(2) diagnostics with p-values.
+
+This should be interpreted as a strong benchmark-specific validation result, not as a universal claim of bit-for-bit equivalence across every possible Stata configuration, missing-data pattern, lag window, instrument classification, covariance assumption, or finite-sample correction.
+
+Future validation-extension priorities include:
+
+* testing additional unbalanced-panel and missing-data designs beyond the maintained benchmark suite;
+* expanding documented examples for short-`T`, longer-`T`, and high-`N`, low-`T` panels;
+* validating additional lag-window choices and alternative instrument classifications;
+* documenting exact Stata-compatible option combinations and known non-equivalence cases;
+* maintaining clear separation between certified `xtabond2` parity paths and experimental or implementation-dependent paths;
+* further investigating FOD-specific validation, especially FOD Windmeijer covariance and FOD AR diagnostic parity against `xtdpdgmm`;
+* extending reviewer-facing artifacts as new benchmark specifications are added.
+
+This roadmap protects the package from overclaiming while making clear that the core native System GMM parity milestone has already been reached for the maintained benchmark suite.
 
 ---
 

{systemgmmkit-0.5.4 → systemgmmkit-0.5.6}/README.md

@@ -738,30 +738,25 @@ For dynamic-panel GMM, users should record at minimum:
 
 ## Validation roadmap
 
-Before claiming broader production certification across panel designs, the package should continue to be tested on:
+## Validation roadmap
 
-* balanced panels;
-* unbalanced panels;
-* short-`T` panels;
-* longer-`T` panels;
-* high-`N`, low-`T` panels;
-* panels with missing observations;
-* different lag windows;
-* models with no controls;
-* models with many controls;
-* interaction-heavy specifications;
-* decomposition specifications;
-* alternative instrument classifications;
-* Stata `xtabond2` replication benchmarks.
-
-High-priority remaining validation items:
-
-* broader System GMM parity across additional empirical specifications;
-* broader Windmeijer-corrected standard-error parity across additional empirical specifications;
-* broader robustness of Sargan, Hansen, and AR diagnostics across additional panel structures;
-* documentation of exact Stata-compatible options and known non-equivalence cases.
-
-This roadmap protects the package from overclaiming and supports academically defensible validation.
+The current validation suite establishes benchmark-specific certification for the maintained native Difference GMM and native System GMM paths.
+
+Native System GMM is certified against Stata `xtabond2` for the maintained collapsed two-step benchmark suite, including the baseline, no-controls, three-way interaction, and decomposition specifications. Certified quantities include sample size, group count, instrument count, coefficient estimates, Hansen diagnostics, Windmeijer-corrected two-step standard errors, and signed Arellano-Bond AR(1)/AR(2) diagnostics with p-values.
+
+This should be interpreted as a strong benchmark-specific validation result, not as a universal claim of bit-for-bit equivalence across every possible Stata configuration, missing-data pattern, lag window, instrument classification, covariance assumption, or finite-sample correction.
+
+Future validation-extension priorities include:
+
+* testing additional unbalanced-panel and missing-data designs beyond the maintained benchmark suite;
+* expanding documented examples for short-`T`, longer-`T`, and high-`N`, low-`T` panels;
+* validating additional lag-window choices and alternative instrument classifications;
+* documenting exact Stata-compatible option combinations and known non-equivalence cases;
+* maintaining clear separation between certified `xtabond2` parity paths and experimental or implementation-dependent paths;
+* further investigating FOD-specific validation, especially FOD Windmeijer covariance and FOD AR diagnostic parity against `xtdpdgmm`;
+* extending reviewer-facing artifacts as new benchmark specifications are added.
+
+This roadmap protects the package from overclaiming while making clear that the core native System GMM parity milestone has already been reached for the maintained benchmark suite.
 
 ---
 

{systemgmmkit-0.5.4 → systemgmmkit-0.5.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "systemgmmkit"
-version = "0.5.4"
+version = "0.5.6"
 description = "Generic panel-data econometrics workflow helpers for FE, RE, IV/2SLS, and Difference/System GMM in Python."
 readme = "README.md"
 requires-python = ">=3.9"

{systemgmmkit-0.5.4 → systemgmmkit-0.5.6}/src/systemgmmkit/estimators/first_difference.py

@@ -11,9 +11,9 @@ systemgmmkit reporting helpers:
 
 from __future__ import annotations
 
+from collections.abc import Iterable
 from dataclasses import dataclass, field
 from math import erf, sqrt
-from typing import Iterable
 
 import numpy as np
 import pandas as pd
@@ -164,7 +164,7 @@ def first_difference(
     rss = float(resid @ resid)
 
     if nobs > 0:
-        tss = float(((y_vec - y_vec.mean()) @ (y_vec - y_vec.mean())))
+        tss = float((y_vec - y_vec.mean()) @ (y_vec - y_vec.mean()))
         r2 = float(1.0 - rss / tss) if tss > 0 else float("nan")
     else:
         r2 = float("nan")
@@ -189,10 +189,7 @@ def first_difference(
         coef = params[name]
         se = std_errors[name]
 
-        if np.isfinite(se) and se > 0:
-            stat = float(coef / se)
-        else:
-            stat = float("nan")
+        stat = float(coef / se) if np.isfinite(se) and se > 0 else float("nan")
 
         t_stats[name] = stat
         p_values[name] = _normal_two_sided_pvalue(stat)

{systemgmmkit-0.5.4 → systemgmmkit-0.5.6}/src/systemgmmkit/native_gmm.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import contextlib
-import os
 from dataclasses import dataclass
 
 import numpy as np
@@ -45,6 +44,10 @@ class NativeGMMResult:
     j_stat: float | None = None
     ztu_norm: float | None = None
     w_norm: float | None = None
+    hansen_j_stat: float | None = None
+    sargan_j_stat: float | None = None
+    overid_df: int | None = None
+    hansen_j_error: str | None = None
 
     def summary_frame(self) -> pd.DataFrame:
         return pd.DataFrame(
@@ -1360,7 +1363,6 @@ def _native_fod_difference_windmeijer_covariance(
         idx = np.asarray(indices, dtype=int)
 
         Zi = Z[idx, :]
-        Xi = X[idx, :]
         ui1 = u1[idx, :]
         ui2 = u2[idx, :]
 
@@ -1461,10 +1463,10 @@ def run_native_dynamic_panel_gmm(
     # and second-step weighting matrices.
 
     # SYSTEMGMMKIT_FILE_INSTRUMENT_DEBUG
-    import os
+    import os as _native_debug_os
     from pathlib import Path as _NativeDebugPath
 
-    debug_file = os.getenv("SYSTEMGMMKIT_DEBUG_INSTRUMENTS_FILE")
+    debug_file = _native_debug_os.getenv("SYSTEMGMMKIT_DEBUG_INSTRUMENTS_FILE")
     if debug_file:
         debug_path = _NativeDebugPath(debug_file)
         debug_path.parent.mkdir(parents=True, exist_ok=True)
@@ -1711,6 +1713,28 @@ def run_native_dynamic_panel_gmm(
     )
     _sargan_stat = float(_j_stat_raw * _sargan_small_scale)
 
+    _hansen_j_stat = None
+    _hansen_p_candidate = None
+    _hansen_j_error = None
+
+    try:
+        _s_group_diag = _native_group_moment_sum(
+            Z=Z,
+            residuals=residual_vec,
+            group_indices=group_indices_for_cov,
+        )
+        _hansen_weight = np.linalg.pinv(_s_group_diag)
+        _hansen_j_candidate = float((_ztu.T @ _hansen_weight @ _ztu).squeeze())
+
+        if np.isfinite(_hansen_j_candidate) and _hansen_j_candidate >= 0:
+            _hansen_j_stat = _hansen_j_candidate
+            if _overid_df > 0:
+                _hansen_p_candidate = float(stats.chi2.sf(_hansen_j_candidate, _overid_df))
+    except Exception as exc:
+        _hansen_j_stat = None
+        _hansen_p_candidate = None
+        _hansen_j_error = f"{type(exc).__name__}: {exc}"
+
     # Store a one-step Sargan-style J statistic only for one-step estimation.
     # In two-step / Windmeijer mode, W is the two-step weighting matrix, so the
     # same quadratic form is not comparable to xtabond2's one-step Sargan.
@@ -1829,6 +1853,9 @@ def run_native_dynamic_panel_gmm(
                     "W_rows": int(W.shape[0]),
                     "W_cols": int(W.shape[1]),
                     "native_j_stat": _j_stat,
+                    "native_hansen_j_stat": _hansen_j_stat,
+                    "native_sargan_j_stat": _sargan_stat,
+                    "native_overid_df": _overid_df,
                     "native_ztu_norm": _ztu_norm,
                     "native_w_norm": _w_norm,
                 }
@@ -1883,6 +1910,10 @@ def run_native_dynamic_panel_gmm(
         j_stat=_j_stat,
         ztu_norm=_ztu_norm,
         w_norm=_w_norm,
+        hansen_j_stat=_hansen_j_stat,
+        sargan_j_stat=_sargan_stat,
+        overid_df=_overid_df,
+        hansen_j_error=_hansen_j_error,
     )
 
 

{systemgmmkit-0.5.4 → systemgmmkit-0.5.6/src/systemgmmkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: systemgmmkit
-Version: 0.5.4
+Version: 0.5.6
 Summary: Generic panel-data econometrics workflow helpers for FE, RE, IV/2SLS, and Difference/System GMM in Python.
 Author: Oluwajuwon Mayomi Akanbi
 License-Expression: MIT
@@ -780,30 +780,25 @@ For dynamic-panel GMM, users should record at minimum:
 
 ## Validation roadmap
 
-Before claiming broader production certification across panel designs, the package should continue to be tested on:
+## Validation roadmap
 
-* balanced panels;
-* unbalanced panels;
-* short-`T` panels;
-* longer-`T` panels;
-* high-`N`, low-`T` panels;
-* panels with missing observations;
-* different lag windows;
-* models with no controls;
-* models with many controls;
-* interaction-heavy specifications;
-* decomposition specifications;
-* alternative instrument classifications;
-* Stata `xtabond2` replication benchmarks.
-
-High-priority remaining validation items:
-
-* broader System GMM parity across additional empirical specifications;
-* broader Windmeijer-corrected standard-error parity across additional empirical specifications;
-* broader robustness of Sargan, Hansen, and AR diagnostics across additional panel structures;
-* documentation of exact Stata-compatible options and known non-equivalence cases.
-
-This roadmap protects the package from overclaiming and supports academically defensible validation.
+The current validation suite establishes benchmark-specific certification for the maintained native Difference GMM and native System GMM paths.
+
+Native System GMM is certified against Stata `xtabond2` for the maintained collapsed two-step benchmark suite, including the baseline, no-controls, three-way interaction, and decomposition specifications. Certified quantities include sample size, group count, instrument count, coefficient estimates, Hansen diagnostics, Windmeijer-corrected two-step standard errors, and signed Arellano-Bond AR(1)/AR(2) diagnostics with p-values.
+
+This should be interpreted as a strong benchmark-specific validation result, not as a universal claim of bit-for-bit equivalence across every possible Stata configuration, missing-data pattern, lag window, instrument classification, covariance assumption, or finite-sample correction.
+
+Future validation-extension priorities include:
+
+* testing additional unbalanced-panel and missing-data designs beyond the maintained benchmark suite;
+* expanding documented examples for short-`T`, longer-`T`, and high-`N`, low-`T` panels;
+* validating additional lag-window choices and alternative instrument classifications;
+* documenting exact Stata-compatible option combinations and known non-equivalence cases;
+* maintaining clear separation between certified `xtabond2` parity paths and experimental or implementation-dependent paths;
+* further investigating FOD-specific validation, especially FOD Windmeijer covariance and FOD AR diagnostic parity against `xtdpdgmm`;
+* extending reviewer-facing artifacts as new benchmark specifications are added.
+
+This roadmap protects the package from overclaiming while making clear that the core native System GMM parity milestone has already been reached for the maintained benchmark suite.
 
 ---
 

{systemgmmkit-0.5.4 → systemgmmkit-0.5.6}/tests/test_xtabond2_system_gmm_parity.py

@@ -112,11 +112,3 @@ def test_native_system_gmm_matches_xtabond2_moments_a2_and_hansen() -> None:
     assert native_a2.shape == stata_a2.shape
     assert np.isfinite(native_a2).all()
     assert np.isfinite(stata_a2).all()
-
-    return
-
-    j_from_native_scaled_a2 = float(
-        (stata_ze.T @ native_a2_scaled @ stata_ze).squeeze()
-    )
-
-    assert abs(j_from_native_scaled_a2 - XTABOND2_HANSEN) < 1e-5