systemgmmkit 0.4.2__tar.gz → 0.5.0__tar.gz

{systemgmmkit-0.4.2/src/systemgmmkit.egg-info → systemgmmkit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: systemgmmkit
-Version: 0.4.2
+Version: 0.5.0
 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
@@ -47,7 +47,7 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![CI](https://github.com/Akanom/systemgmmkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Akanom/systemgmmkit/actions/workflows/ci.yml)
 [![Publish](https://github.com/Akanom/systemgmmkit/actions/workflows/publish.yml/badge.svg)](https://github.com/Akanom/systemgmmkit/actions/workflows/publish.yml)
-[![Downloads](https://static.pepy.tech/badge/systemgmmkit/month)](https://pepy.tech/project/systemgmmkit)
+[![Downloads](https://img.shields.io/pepy/dm/systemgmmkit)](https://pepy.tech/project/systemgmmkit)
 `systemgmmkit` is a Python workflow package for panel-data econometrics.
 
 It supports reusable model specification, panel validation, static panel estimation, dynamic-panel GMM estimation, backend routing, diagnostics interpretation, reproducible reporting, and regression-table export.
@@ -91,7 +91,7 @@ The package then routes estimation through the appropriate backend.
 * public `run_system_gmm()` and `run_difference_gmm()` convenience functions;
 * optional validated backend adapter integration for System GMM;
 * native Difference GMM estimation;
-* experimental native System GMM estimation;
+* native System GMM estimation with verified `xtabond2` baseline parity checks, including Windmeijer-corrected two-step standard-error parity on the certified benchmark;
 * model-card style reporting for reproducibility;
 * regression-table export to Markdown, CSV, and LaTeX;
 * Stata parity-check scaffolding for `xtreg, fe` and `xtabond2` replication workflows.
@@ -100,16 +100,18 @@ The package then routes estimation through the appropriate backend.
 
 ## Current validation status
 
-| Estimator                       | Current status                            | Interpretation                                                                                                                                                              |
-| ------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Static panel estimators         | Active development                        | Pooled OLS, Fixed Effects, Random Effects, and Panel IV / 2SLS are available for applied workflow use and should be validated against reference packages for critical work. |
-| Native Difference GMM           | Strict parity passed on current benchmark | Native Difference GMM matches the current validation backend and Stata oracle within numerical tolerance on the tested benchmark.                                           |
-| Native System GMM               | Experimental parity pending               | Native System GMM runs, preserves observation and instrument counts, and passes construction checks, but coefficient-level parity with `xtabond2` is not yet certified.     |
-| System GMM via `backend="auto"` | Recommended empirical route               | System GMM is called through the public `systemgmmkit` API and routed internally to the validated backend adapter.                                                          |
+| Estimator                       | Current status                                      | Interpretation |
+| ------------------------------- | --------------------------------------------------- | -------------- |
+| Static panel estimators         | Active development                                  | Pooled OLS, Fixed Effects, Random Effects, and Panel IV / 2SLS are available for applied workflow use and should be validated against reference packages for critical work. |
+| Native Difference GMM           | Strict parity passed on current benchmark           | Native Difference GMM matches the current validation backend and Stata oracle within numerical tolerance on the tested benchmark. |
+| Native System GMM               | `xtabond2` baseline and Windmeijer SE parity passed | Native System GMM matches `xtabond2` on the current collapsed two-step System GMM benchmark for coefficients, raw residual moments (`Z'u`), group-scaled two-step weighting matrix (`A2 / n_groups`), Hansen J, and Windmeijer-corrected two-step standard errors. |
+| System GMM via `backend="auto"` | Stable public workflow route                        | `backend="auto"` remains the recommended public workflow route unless the user needs explicit native/adapter comparison. Users who need exact replication should report the selected backend and validation benchmark. |
 
-The current validation harness confirms that native Difference GMM passes strict parity on the benchmark specification.
+The current validation harness confirms strict parity for native Difference GMM on the benchmark specification.
 
-Native System GMM is intentionally marked as experimental until broader coefficient-parity tests pass across multiple datasets, panel structures, lag windows, missing-data patterns, and specifications.
+Native System GMM now passes a dedicated `xtabond2` baseline parity benchmark. The verified benchmark covers coefficient estimates, raw residual moments (`Z'u`), the group-scaled two-step weighting matrix (`A2 / n_groups`), the Hansen J statistic, and Windmeijer-corrected two-step standard errors.
+
+This should be interpreted as a strong benchmark-specific parity result, not as a universal claim of Stata identity across every possible dataset, lag window, missing-data pattern, instrument classification, covariance assumption, or finite-sample correction. Broader specification coverage remains on the validation roadmap.
 
 ---
 
@@ -123,18 +125,18 @@ Users should call the public API:
 from systemgmmkit import run_system_gmm, run_difference_gmm
 ```
 
-The package then routes estimation through the appropriate backend.
+The package then routes estimation through the selected backend.
 
-| User option           | Difference GMM behavior                                       | System GMM behavior                                              |
-| --------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `backend="auto"`      | Uses the validated native `systemgmmkit` Difference GMM path. | Routes through the validated backend adapter via `systemgmmkit`. |
-| `backend="validated"` | Uses the validated native `systemgmmkit` Difference GMM path. | Routes through the validated backend adapter via `systemgmmkit`. |
-| `backend="native"`    | Uses the native `systemgmmkit` engine.                        | Uses the native `systemgmmkit` engine, currently experimental.   |
-| `backend="pydynpd"`   | Explicitly routes through the backend adapter.                | Explicitly routes through the backend adapter.                   |
+| User option           | Difference GMM behavior                                       | System GMM behavior |
+| --------------------- | ------------------------------------------------------------- | ------------------- |
+| `backend="auto"`      | Uses the validated native `systemgmmkit` Difference GMM path. | Uses the package's configured stable System GMM route. This is the recommended default workflow unless the user needs a specific backend. |
+| `backend="validated"` | Uses the validated native `systemgmmkit` Difference GMM path. | Routes through the validated backend adapter where available. |
+| `backend="native"`    | Uses the native `systemgmmkit` engine.                        | Uses the native `systemgmmkit` engine. The current `xtabond2` parity benchmark is passed for collapsed two-step System GMM coefficients, moments, group-scaled A2, Hansen J, and Windmeijer-corrected two-step standard errors. |
+| `backend="pydynpd"`   | Explicitly routes through the backend adapter.                | Explicitly routes through the backend adapter. |
 
-This design keeps `systemgmmkit` as the stable public interface while allowing backend routing internally.
+This design keeps `systemgmmkit` as the stable public interface while allowing explicit backend selection for replication, benchmarking, and sensitivity analysis.
 
-For empirical System GMM work requiring the strongest validation, use:
+For empirical System GMM work, a typical public workflow is:
 
 ```python
 result = run_system_gmm(
@@ -146,7 +148,7 @@ result = run_system_gmm(
 )
 ```
 
-This keeps the user workflow inside `systemgmmkit` while routing internally to the validated backend path.
+For strict native replication of the current `xtabond2` parity benchmark, use `backend="native"` and match the sample, lag windows, collapsed-instrument setting, IV treatment, time-dummy treatment, transformation, covariance assumptions, and estimation options.
 
 ---
 
@@ -174,7 +176,7 @@ The construction logic has been validated across:
 * specifications with and without standard IV controls;
 * single and multiple GMM-style instrument blocks.
 
-This is a construction-architecture milestone, not a final claim of universal System GMM coefficient parity.
+This construction architecture now supports the current native System GMM `xtabond2` baseline parity result. It should still be interpreted conservatively: the benchmark verifies a specific collapsed two-step System GMM specification, not universal equivalence across all possible panel designs and covariance corrections.
 
 ---
 
@@ -376,7 +378,7 @@ result = run_system_gmm(
 
 System GMM follows the Blundell-Bond dynamic-panel structure and combines transformed-equation moments with level-equation moments.
 
-Native System GMM is currently experimental. Use `backend="auto"` for empirical System GMM workflows requiring stronger external validation through the package’s validated backend route.
+Native System GMM now passes a dedicated `xtabond2` benchmark for collapsed two-step System GMM coefficients, residual moments, group-scaled two-step weighting matrix, Hansen J, and Windmeijer-corrected two-step standard errors. Broader specification coverage remains under validation, so users should report the backend, model specification, instrument count, covariance type, and validation context for critical empirical work.
 
 ---
 
@@ -685,7 +687,7 @@ Variable classification is an econometric assumption.
 Supported native GMM features include:
 
 * Difference GMM;
-* experimental System GMM;
+* System GMM with verified `xtabond2` baseline parity for the current collapsed two-step benchmark, including Windmeijer-corrected two-step standard-error parity;
 * collapsed instruments;
 * restricted lag windows;
 * one-step and two-step estimation paths;
@@ -696,6 +698,17 @@ Supported native GMM features include:
 
 The native backend is intended to provide a transparent Python implementation that can be inspected, tested, and extended without relying only on an external backend.
 
+The native System GMM parity benchmark currently verifies:
+
+* coefficient estimates against `xtabond2`;
+* raw residual moments (`Z'u`) after instrument-order mapping;
+* two-step weighting matrix alignment after group scaling (`A2 / n_groups`);
+* Hansen J statistic alignment;
+* Windmeijer-corrected two-step standard-error alignment against Stata `e(V)`;
+* automated pytest regression guarding for the benchmark.
+
+The remaining high-priority validation work is broader benchmark coverage across alternative datasets, lag windows, missing-data structures, instrument classifications, covariance assumptions, and diagnostic outputs.
+
 ---
 
 ## Backend adapter
@@ -763,7 +776,7 @@ For dynamic-panel GMM, users should record at minimum:
 
 ## Validation roadmap
 
-Before claiming broader production certification across panel designs, the package should be tested on:
+Before claiming broader production certification across panel designs, the package should continue to be tested on:
 
 * balanced panels;
 * unbalanced panels;
@@ -779,6 +792,13 @@ Before claiming broader production certification across panel designs, the packa
 * alternative instrument classifications;
 * Stata `xtabond2` replication benchmarks.
 
+High-priority remaining validation items:
+
+* broader System GMM parity across multiple specifications;
+* broader Windmeijer-corrected standard-error parity across multiple specifications;
+* robustness of AR(1), AR(2), Sargan, and Hansen diagnostics across 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.
 
 ---
@@ -816,3 +836,11 @@ Estimation was performed using systemgmmkit version X.Y.Z, commit <commit-hash>.
 
 
 
+
+
+
+
+
+
+
+

{systemgmmkit-0.4.2 → systemgmmkit-0.5.0}/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![CI](https://github.com/Akanom/systemgmmkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Akanom/systemgmmkit/actions/workflows/ci.yml)
 [![Publish](https://github.com/Akanom/systemgmmkit/actions/workflows/publish.yml/badge.svg)](https://github.com/Akanom/systemgmmkit/actions/workflows/publish.yml)
-[![Downloads](https://static.pepy.tech/badge/systemgmmkit/month)](https://pepy.tech/project/systemgmmkit)
+[![Downloads](https://img.shields.io/pepy/dm/systemgmmkit)](https://pepy.tech/project/systemgmmkit)
 `systemgmmkit` is a Python workflow package for panel-data econometrics.
 
 It supports reusable model specification, panel validation, static panel estimation, dynamic-panel GMM estimation, backend routing, diagnostics interpretation, reproducible reporting, and regression-table export.
@@ -49,7 +49,7 @@ The package then routes estimation through the appropriate backend.
 * public `run_system_gmm()` and `run_difference_gmm()` convenience functions;
 * optional validated backend adapter integration for System GMM;
 * native Difference GMM estimation;
-* experimental native System GMM estimation;
+* native System GMM estimation with verified `xtabond2` baseline parity checks, including Windmeijer-corrected two-step standard-error parity on the certified benchmark;
 * model-card style reporting for reproducibility;
 * regression-table export to Markdown, CSV, and LaTeX;
 * Stata parity-check scaffolding for `xtreg, fe` and `xtabond2` replication workflows.
@@ -58,16 +58,18 @@ The package then routes estimation through the appropriate backend.
 
 ## Current validation status
 
-| Estimator                       | Current status                            | Interpretation                                                                                                                                                              |
-| ------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Static panel estimators         | Active development                        | Pooled OLS, Fixed Effects, Random Effects, and Panel IV / 2SLS are available for applied workflow use and should be validated against reference packages for critical work. |
-| Native Difference GMM           | Strict parity passed on current benchmark | Native Difference GMM matches the current validation backend and Stata oracle within numerical tolerance on the tested benchmark.                                           |
-| Native System GMM               | Experimental parity pending               | Native System GMM runs, preserves observation and instrument counts, and passes construction checks, but coefficient-level parity with `xtabond2` is not yet certified.     |
-| System GMM via `backend="auto"` | Recommended empirical route               | System GMM is called through the public `systemgmmkit` API and routed internally to the validated backend adapter.                                                          |
+| Estimator                       | Current status                                      | Interpretation |
+| ------------------------------- | --------------------------------------------------- | -------------- |
+| Static panel estimators         | Active development                                  | Pooled OLS, Fixed Effects, Random Effects, and Panel IV / 2SLS are available for applied workflow use and should be validated against reference packages for critical work. |
+| Native Difference GMM           | Strict parity passed on current benchmark           | Native Difference GMM matches the current validation backend and Stata oracle within numerical tolerance on the tested benchmark. |
+| Native System GMM               | `xtabond2` baseline and Windmeijer SE parity passed | Native System GMM matches `xtabond2` on the current collapsed two-step System GMM benchmark for coefficients, raw residual moments (`Z'u`), group-scaled two-step weighting matrix (`A2 / n_groups`), Hansen J, and Windmeijer-corrected two-step standard errors. |
+| System GMM via `backend="auto"` | Stable public workflow route                        | `backend="auto"` remains the recommended public workflow route unless the user needs explicit native/adapter comparison. Users who need exact replication should report the selected backend and validation benchmark. |
 
-The current validation harness confirms that native Difference GMM passes strict parity on the benchmark specification.
+The current validation harness confirms strict parity for native Difference GMM on the benchmark specification.
 
-Native System GMM is intentionally marked as experimental until broader coefficient-parity tests pass across multiple datasets, panel structures, lag windows, missing-data patterns, and specifications.
+Native System GMM now passes a dedicated `xtabond2` baseline parity benchmark. The verified benchmark covers coefficient estimates, raw residual moments (`Z'u`), the group-scaled two-step weighting matrix (`A2 / n_groups`), the Hansen J statistic, and Windmeijer-corrected two-step standard errors.
+
+This should be interpreted as a strong benchmark-specific parity result, not as a universal claim of Stata identity across every possible dataset, lag window, missing-data pattern, instrument classification, covariance assumption, or finite-sample correction. Broader specification coverage remains on the validation roadmap.
 
 ---
 
@@ -81,18 +83,18 @@ Users should call the public API:
 from systemgmmkit import run_system_gmm, run_difference_gmm
 ```
 
-The package then routes estimation through the appropriate backend.
+The package then routes estimation through the selected backend.
 
-| User option           | Difference GMM behavior                                       | System GMM behavior                                              |
-| --------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `backend="auto"`      | Uses the validated native `systemgmmkit` Difference GMM path. | Routes through the validated backend adapter via `systemgmmkit`. |
-| `backend="validated"` | Uses the validated native `systemgmmkit` Difference GMM path. | Routes through the validated backend adapter via `systemgmmkit`. |
-| `backend="native"`    | Uses the native `systemgmmkit` engine.                        | Uses the native `systemgmmkit` engine, currently experimental.   |
-| `backend="pydynpd"`   | Explicitly routes through the backend adapter.                | Explicitly routes through the backend adapter.                   |
+| User option           | Difference GMM behavior                                       | System GMM behavior |
+| --------------------- | ------------------------------------------------------------- | ------------------- |
+| `backend="auto"`      | Uses the validated native `systemgmmkit` Difference GMM path. | Uses the package's configured stable System GMM route. This is the recommended default workflow unless the user needs a specific backend. |
+| `backend="validated"` | Uses the validated native `systemgmmkit` Difference GMM path. | Routes through the validated backend adapter where available. |
+| `backend="native"`    | Uses the native `systemgmmkit` engine.                        | Uses the native `systemgmmkit` engine. The current `xtabond2` parity benchmark is passed for collapsed two-step System GMM coefficients, moments, group-scaled A2, Hansen J, and Windmeijer-corrected two-step standard errors. |
+| `backend="pydynpd"`   | Explicitly routes through the backend adapter.                | Explicitly routes through the backend adapter. |
 
-This design keeps `systemgmmkit` as the stable public interface while allowing backend routing internally.
+This design keeps `systemgmmkit` as the stable public interface while allowing explicit backend selection for replication, benchmarking, and sensitivity analysis.
 
-For empirical System GMM work requiring the strongest validation, use:
+For empirical System GMM work, a typical public workflow is:
 
 ```python
 result = run_system_gmm(
@@ -104,7 +106,7 @@ result = run_system_gmm(
 )
 ```
 
-This keeps the user workflow inside `systemgmmkit` while routing internally to the validated backend path.
+For strict native replication of the current `xtabond2` parity benchmark, use `backend="native"` and match the sample, lag windows, collapsed-instrument setting, IV treatment, time-dummy treatment, transformation, covariance assumptions, and estimation options.
 
 ---
 
@@ -132,7 +134,7 @@ The construction logic has been validated across:
 * specifications with and without standard IV controls;
 * single and multiple GMM-style instrument blocks.
 
-This is a construction-architecture milestone, not a final claim of universal System GMM coefficient parity.
+This construction architecture now supports the current native System GMM `xtabond2` baseline parity result. It should still be interpreted conservatively: the benchmark verifies a specific collapsed two-step System GMM specification, not universal equivalence across all possible panel designs and covariance corrections.
 
 ---
 
@@ -334,7 +336,7 @@ result = run_system_gmm(
 
 System GMM follows the Blundell-Bond dynamic-panel structure and combines transformed-equation moments with level-equation moments.
 
-Native System GMM is currently experimental. Use `backend="auto"` for empirical System GMM workflows requiring stronger external validation through the package’s validated backend route.
+Native System GMM now passes a dedicated `xtabond2` benchmark for collapsed two-step System GMM coefficients, residual moments, group-scaled two-step weighting matrix, Hansen J, and Windmeijer-corrected two-step standard errors. Broader specification coverage remains under validation, so users should report the backend, model specification, instrument count, covariance type, and validation context for critical empirical work.
 
 ---
 
@@ -643,7 +645,7 @@ Variable classification is an econometric assumption.
 Supported native GMM features include:
 
 * Difference GMM;
-* experimental System GMM;
+* System GMM with verified `xtabond2` baseline parity for the current collapsed two-step benchmark, including Windmeijer-corrected two-step standard-error parity;
 * collapsed instruments;
 * restricted lag windows;
 * one-step and two-step estimation paths;
@@ -654,6 +656,17 @@ Supported native GMM features include:
 
 The native backend is intended to provide a transparent Python implementation that can be inspected, tested, and extended without relying only on an external backend.
 
+The native System GMM parity benchmark currently verifies:
+
+* coefficient estimates against `xtabond2`;
+* raw residual moments (`Z'u`) after instrument-order mapping;
+* two-step weighting matrix alignment after group scaling (`A2 / n_groups`);
+* Hansen J statistic alignment;
+* Windmeijer-corrected two-step standard-error alignment against Stata `e(V)`;
+* automated pytest regression guarding for the benchmark.
+
+The remaining high-priority validation work is broader benchmark coverage across alternative datasets, lag windows, missing-data structures, instrument classifications, covariance assumptions, and diagnostic outputs.
+
 ---
 
 ## Backend adapter
@@ -721,7 +734,7 @@ For dynamic-panel GMM, users should record at minimum:
 
 ## Validation roadmap
 
-Before claiming broader production certification across panel designs, the package should be tested on:
+Before claiming broader production certification across panel designs, the package should continue to be tested on:
 
 * balanced panels;
 * unbalanced panels;
@@ -737,6 +750,13 @@ Before claiming broader production certification across panel designs, the packa
 * alternative instrument classifications;
 * Stata `xtabond2` replication benchmarks.
 
+High-priority remaining validation items:
+
+* broader System GMM parity across multiple specifications;
+* broader Windmeijer-corrected standard-error parity across multiple specifications;
+* robustness of AR(1), AR(2), Sargan, and Hansen diagnostics across 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.
 
 ---
@@ -774,3 +794,11 @@ Estimation was performed using systemgmmkit version X.Y.Z, commit <commit-hash>.
 
 
 
+
+
+
+
+
+
+
+

{systemgmmkit-0.4.2 → systemgmmkit-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "systemgmmkit"
-version = "0.4.2"
+version = "0.5.0"
 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"
@@ -66,3 +66,4 @@ quote-style = "double"
 indent-style = "space"
 line-ending = "auto"
 
+

{systemgmmkit-0.4.2 → systemgmmkit-0.5.0}/src/systemgmmkit/__init__.py

@@ -68,9 +68,16 @@ __all__ = [
     "DynamicPanelBackendError",
     "run_dynamic_panel_gmm",
     "run_system_gmm",
-    "run_difference_gmm",]
+    "run_difference_gmm",    "FirstDifferenceResult",
+    "ParityReport",
+    "ParityResult",
+    "classify_parity_result",
+    "first_difference",
+]
 
-__version__ = "0.4.1"
+__version__ = "0.5.0"
+
+import contextlib
 
 from .dynamic_panel import (
     DynamicPanelBackendError,
@@ -78,3 +85,11 @@ from .dynamic_panel import (
     run_dynamic_panel_gmm,
     run_system_gmm,
 )
+
+with contextlib.suppress(Exception):
+    from .estimators.first_difference import FirstDifferenceResult, first_difference
+
+with contextlib.suppress(Exception):
+    from .reporting import ParityReport, ParityResult, classify_parity_result
+
+from .estimators.first_difference import FirstDifferenceResult, first_difference

systemgmmkit-0.5.0/src/systemgmmkit/diagnostics/__init__.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .gmm import GmmDiagnostics
+from .panel import (
+    DiagnosticResult,
+    breusch_pagan_lm,
+    hausman_fe_re,
+    modified_wald_groupwise_heteroskedasticity,
+    pesaran_cd,
+    wooldridge_serial_correlation,
+)
+
+
+@dataclass(frozen=True)
+class DiagnosticCheck:
+    name: str
+    value: float | int | None
+    passed: bool | None
+    interpretation: str
+
+
+@dataclass(frozen=True)
+class DiagnosticReport:
+    checks: list[DiagnosticCheck]
+    recommendation: str
+
+    def to_markdown(self) -> str:
+        lines = ["| Diagnostic | Value | Pass | Interpretation |", "|---|---:|:---:|---|"]
+        for c in self.checks:
+            value = (
+                ""
+                if c.value is None
+                else f"{c.value:.4g}"
+                if isinstance(c.value, float)
+                else str(c.value)
+            )
+            passed = "—" if c.passed is None else "Yes" if c.passed else "No"
+            lines.append(f"| {c.name} | {value} | {passed} | {c.interpretation} |")
+        lines.append("")
+        lines.append(f"**Recommendation:** {self.recommendation}")
+        return "\n".join(lines)
+
+
+def assess_diagnostics(
+    *,
+    ar1_p: float | None = None,
+    ar2_p: float | None = None,
+    hansen_p: float | None = None,
+    sargan_p: float | None = None,
+    diff_hansen_p: float | None = None,
+    n_instruments: int | None = None,
+    n_entities: int | None = None,
+) -> DiagnosticReport:
+    checks: list[DiagnosticCheck] = []
+
+    checks.append(
+        DiagnosticCheck(
+            "AR(1) p-value",
+            ar1_p,
+            None if ar1_p is None else ar1_p < 0.10,
+            "Expected to be significant or near-significant in differenced errors.",
+        )
+    )
+    checks.append(
+        DiagnosticCheck(
+            "AR(2) p-value",
+            ar2_p,
+            None if ar2_p is None else ar2_p > 0.10,
+            "Should not be significant; rejection implies invalid lag instruments.",
+        )
+    )
+    checks.append(
+        DiagnosticCheck(
+            "Hansen p-value",
+            hansen_p,
+            None if hansen_p is None else 0.05 < hansen_p < 0.90,
+            "Should not reject, but values near 1 can indicate instrument proliferation.",
+        )
+    )
+    checks.append(
+        DiagnosticCheck(
+            "Sargan p-value",
+            sargan_p,
+            None if sargan_p is None else sargan_p > 0.05,
+            "Useful under homoskedasticity; less reliable with robust two-step estimation.",
+        )
+    )
+    checks.append(
+        DiagnosticCheck(
+            "Difference-in-Hansen p-value",
+            diff_hansen_p,
+            None if diff_hansen_p is None else diff_hansen_p > 0.05,
+            "Should not reject validity of additional system/instrument subsets.",
+        )
+    )
+
+    instrument_pass: bool | None = None
+    instrument_value: float | None = None
+
+    if n_instruments is not None and n_entities is not None and n_entities > 0:
+        instrument_value = n_instruments / n_entities
+        instrument_pass = n_instruments <= n_entities
+
+    checks.append(
+        DiagnosticCheck(
+            "Instrument/entity ratio",
+            instrument_value,
+            instrument_pass,
+            "Prefer instruments fewer than, or at least not materially above, number of entities.",
+        )
+    )
+
+    failures = [c.name for c in checks if c.passed is False]
+
+    if not failures:
+        recommendation = "Diagnostics are broadly defensible. Interpret coefficients with normal dynamic-panel caution."
+    elif "AR(2) p-value" in failures:
+        recommendation = "Do not rely on this specification until serial-correlation failure is resolved."
+    elif "Instrument/entity ratio" in failures or "Hansen p-value" in failures:
+        recommendation = "Reduce instrument count: collapse instruments, shorten lag windows, or move weakly endogenous blocks to IV-style treatment."
+    else:
+        recommendation = "Use as sensitivity evidence only; explain diagnostic weaknesses transparently."
+
+    return DiagnosticReport(checks=checks, recommendation=recommendation)
+
+
+__all__ = [
+    "DiagnosticCheck",
+    "DiagnosticReport",
+    "DiagnosticResult",
+    "GmmDiagnostics",
+    "assess_diagnostics",
+    "breusch_pagan_lm",
+    "hausman_fe_re",
+    "modified_wald_groupwise_heteroskedasticity",
+    "pesaran_cd",
+    "wooldridge_serial_correlation",
+]

systemgmmkit-0.5.0/src/systemgmmkit/diagnostics/gmm.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class GmmDiagnostics:
+    ar1_pvalue: float | None = None
+    ar2_pvalue: float | None = None
+    hansen_pvalue: float | None = None
+    sargan_pvalue: float | None = None
+    diff_hansen_pvalue: float | None = None
+    n_instruments: int | None = None
+    n_groups: int | None = None
+
+    @property
+    def instrument_pressure_ratio(self) -> float | None:
+        if self.n_instruments is None or self.n_groups in (None, 0):
+            return None
+        return self.n_instruments / self.n_groups
+
+    @property
+    def passes_basic_gmm_diagnostics(self) -> bool:
+        if self.ar2_pvalue is not None and self.ar2_pvalue < 0.05:
+            return False
+        if self.hansen_pvalue is not None and self.hansen_pvalue < 0.05:
+            return False
+        return not (self.instrument_pressure_ratio is not None and self.instrument_pressure_ratio >= 1.0)