systemgmmkit 0.4.1__py3-none-any.whl

systemgmmkit/__init__.py

@@ -0,0 +1,80 @@
+"""Generic panel-data workflow helpers for FE, RE, IV/2SLS, and Difference/System GMM."""
+
+from .diagnostics import DiagnosticCheck, DiagnosticReport, assess_diagnostics
+from .fixed_effects import (
+    FixedEffectsResult,
+    FixedEffectsSpec,
+    run_fixed_effects,
+    run_fixed_effects_native,
+)
+from .native_gmm import NativeGMMResult, run_native_dynamic_panel_gmm
+from .panel_iv import PanelIVResult, PanelIVSpec, run_panel_2sls
+from .parity import stata_xtabond2_command, stata_xtreg_fe_command, write_stata_parity_do_file
+from .presets import (
+    build_difference_gmm_spec,
+    build_dynamic_panel_gmm_spec,
+    build_fixed_effects_spec,
+    build_panel_model_suite,
+    build_system_gmm_spec,
+)
+from .pydynpd_backend import PydynpdGMMResult, build_pydynpd_command, run_pydynpd
+from .random_effects import RandomEffectsResult, RandomEffectsSpec, run_random_effects
+from .reporting import model_card_markdown
+from .spec import DynamicPanelSpec, GMMStyle, IVStyle
+from .suite import PanelModelSuite, PanelModelSuiteResult, run_panel_model_suite
+from .tables import combine_result_frames, export_regression_table, result_to_frame
+from .validation import PanelValidationReport, validate_panel
+
+__all__ = [
+    "DiagnosticCheck",
+    "DiagnosticReport",
+    "DynamicPanelSpec",
+    "FixedEffectsResult",
+    "FixedEffectsSpec",
+    "GMMStyle",
+    "IVStyle",
+    "NativeGMMResult",
+    "PanelIVResult",
+    "PanelIVSpec",
+    "PanelModelSuite",
+    "PanelModelSuiteResult",
+    "PanelValidationReport",
+    "PydynpdGMMResult",
+    "RandomEffectsResult",
+    "RandomEffectsSpec",
+    "assess_diagnostics",
+    "build_difference_gmm_spec",
+    "build_dynamic_panel_gmm_spec",
+    "build_fixed_effects_spec",
+    "build_panel_model_suite",
+    "build_pydynpd_command",
+    "build_system_gmm_spec",
+    "combine_result_frames",
+    "export_regression_table",
+    "model_card_markdown",
+    "result_to_frame",
+    "run_fixed_effects",
+    "run_fixed_effects_native",
+    "run_native_dynamic_panel_gmm",
+    "run_panel_2sls",
+    "run_panel_model_suite",
+    "run_pydynpd",
+    "run_random_effects",
+    "stata_xtabond2_command",
+    "stata_xtreg_fe_command",
+    "validate_panel",
+    "write_stata_parity_do_file",
+
+    "DynamicPanelBackendError",
+    "run_dynamic_panel_gmm",
+    "run_system_gmm",
+    "run_difference_gmm",]
+
+__version__ = "0.4.1"
+
+from .dynamic_panel import (
+    DynamicPanelBackendError,
+    run_difference_gmm,
+    run_dynamic_panel_gmm,
+    run_system_gmm,
+)

systemgmmkit/cli.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+from .presets import aid_growth_ta_decomposition_spec, aid_growth_techshare_spec
+from .reporting import model_card_markdown
+from .validation import validate_panel
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="systemgmmkit", description="Dynamic-panel System GMM workflow helper"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    validate = sub.add_parser("validate", help="Validate a panel dataset")
+    validate.add_argument("csv", type=Path)
+    validate.add_argument("--entity", required=True)
+    validate.add_argument("--time", required=True)
+    validate.add_argument("--vars", nargs="*", default=[])
+    validate.add_argument("--json", action="store_true")
+
+    preset = sub.add_parser("preset", help="Print a preset model card")
+    preset.add_argument("name", choices=["techshare", "ta-decomp"])
+    preset.add_argument("--no-controls", action="store_true")
+    preset.add_argument("--no-three-way", action="store_true")
+    preset.add_argument(
+        "--difference", action="store_true", help="Use Difference GMM instead of System GMM"
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "validate":
+        df = pd.read_csv(args.csv)
+        report = validate_panel(df, entity=args.entity, time=args.time, variables=args.vars)
+        if args.json:
+            print(json.dumps(report.to_dict(), indent=2))
+        else:
+            print(json.dumps(report.to_dict(), indent=2))
+        return 0
+
+    if args.command == "preset":
+        kwargs = {
+            "include_controls": not args.no_controls,
+            "include_three_way": not args.no_three_way,
+            "system": not args.difference,
+        }
+        spec = (
+            aid_growth_techshare_spec(**kwargs)
+            if args.name == "techshare"
+            else aid_growth_ta_decomposition_spec(**kwargs)
+        )
+        print(model_card_markdown(spec))
+        return 0
+
+    parser.print_help(sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

systemgmmkit/diagnostics.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@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:
+    """Create a conservative interpretation of System GMM diagnostics."""
+
+    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)

systemgmmkit/dynamic_panel.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import inspect
+import warnings
+from contextlib import suppress
+from typing import Any, Literal
+
+import pandas as pd
+
+from .pydynpd_output_parser import enrich_result_with_parsed_standard_errors
+
+DynamicGMMBackend = Literal["auto", "validated", "native", "pydynpd"]
+
+
+class DynamicPanelBackendError(RuntimeError):
+    """Raised when dynamic-panel backend routing fails."""
+
+
+def _is_system_gmm(spec: Any) -> bool:
+    return bool(getattr(spec, "system", False))
+
+
+def _append_result_note(result: Any, note: str) -> Any:
+    """Best-effort note attachment without assuming a mutable result class."""
+    with suppress(Exception):
+        notes = getattr(result, "notes", None)
+
+        if notes is None:
+            result.notes = [note]
+        elif isinstance(notes, list):
+            if note not in notes:
+                notes.append(note)
+        elif isinstance(notes, tuple) and note not in notes:
+            result.notes = [*notes, note]
+        elif not isinstance(notes, (list, tuple)):
+            result.notes = [str(notes), note]
+
+    return result
+
+
+def _set_result_attr(result: Any, name: str, value: Any) -> Any:
+    """Best-effort result metadata attachment."""
+    with suppress(Exception):
+        setattr(result, name, value)
+
+    return result
+
+
+def _call_pydynpd_backend(
+    spec: Any,
+    data: pd.DataFrame,
+    *,
+    entity: str,
+    time: str,
+) -> Any:
+    """Call the systemgmmkit pydynpd adapter across known signatures."""
+
+    try:
+        from systemgmmkit.pydynpd_backend import run_pydynpd
+    except Exception as exc:
+        raise DynamicPanelBackendError(
+            "The pydynpd backend could not be imported. Install optional backend "
+            "dependencies or use backend='native'."
+        ) from exc
+
+    signature = inspect.signature(run_pydynpd)
+    params = signature.parameters
+
+    if "panel_ids" in params:
+        return run_pydynpd(spec, data, panel_ids=(entity, time))
+
+    attempts = [
+        ("panel_ids_tuple_positional", lambda: run_pydynpd(spec, data, (entity, time))),
+        ("panel_ids_list_positional", lambda: run_pydynpd(spec, data, [entity, time])),
+        ("keywords_entity_time", lambda: run_pydynpd(spec, data, entity=entity, time=time)),
+        (
+            "keywords_entity_col_time_col",
+            lambda: run_pydynpd(spec, data, entity_col=entity, time_col=time),
+        ),
+        (
+            "keywords_id_col_time_col",
+            lambda: run_pydynpd(spec, data, id_col=entity, time_col=time),
+        ),
+        ("positional_entity_time", lambda: run_pydynpd(spec, data, entity, time)),
+        ("spec_data_only", lambda: run_pydynpd(spec, data)),
+    ]
+
+    errors: list[str] = []
+
+    for label, func in attempts:
+        try:
+            return func()
+        except TypeError as exc:
+            errors.append(f"{label}: {exc}")
+
+    raise DynamicPanelBackendError(
+        "Could not call the pydynpd backend with any supported adapter signature. "
+        "Attempted signatures:\n" + "\n".join(errors)
+    )
+
+
+def _call_native_backend(
+    spec: Any,
+    data: pd.DataFrame,
+    *,
+    entity: str,
+    time: str,
+) -> Any:
+    try:
+        from systemgmmkit.native_gmm import run_native_dynamic_panel_gmm
+    except Exception as exc:
+        raise DynamicPanelBackendError(
+            "The native GMM backend could not be imported."
+        ) from exc
+
+    return run_native_dynamic_panel_gmm(
+        spec,
+        data,
+        entity=entity,
+        time=time,
+    )
+
+
+def run_dynamic_panel_gmm(
+    spec: Any,
+    data: pd.DataFrame,
+    *,
+    entity: str,
+    time: str,
+    backend: DynamicGMMBackend = "auto",
+) -> Any:
+    """Run Difference or System GMM through the systemgmmkit public API.
+
+    Backend policy
+    --------------
+    backend="auto"
+        Difference GMM -> native validated backend.
+        System GMM     -> validated pydynpd adapter through systemgmmkit.
+
+    backend="validated"
+        Same as "auto", but explicit.
+
+    backend="native"
+        Uses the native systemgmmkit backend. Native System GMM remains
+        experimental until coefficient-level parity is certified.
+
+    backend="pydynpd"
+        Explicitly routes through the pydynpd adapter.
+
+    This keeps systemgmmkit as the user-facing package while allowing a validated
+    third-party backend internally where appropriate.
+    """
+
+    if backend not in {"auto", "validated", "native", "pydynpd"}:
+        raise ValueError(
+            "backend must be one of: 'auto', 'validated', 'native', 'pydynpd'."
+        )
+
+    is_system = _is_system_gmm(spec)
+
+    if backend in {"auto", "validated"}:
+        if is_system:
+            result = _call_pydynpd_backend(spec, data, entity=entity, time=time)
+            result = enrich_result_with_parsed_standard_errors(result)
+            _set_result_attr(result, "backend", "pydynpd-via-systemgmmkit")
+            _set_result_attr(result, "systemgmmkit_backend_policy", backend)
+            _append_result_note(
+                result,
+                "System GMM routed through the validated pydynpd adapter by systemgmmkit.",
+            )
+            return result
+
+        result = _call_native_backend(spec, data, entity=entity, time=time)
+        _set_result_attr(result, "backend", "native-validated-via-systemgmmkit")
+        _set_result_attr(result, "systemgmmkit_backend_policy", backend)
+        _append_result_note(
+            result,
+            "Difference GMM routed through the validated native systemgmmkit backend.",
+        )
+        return result
+
+    if backend == "pydynpd":
+        result = _call_pydynpd_backend(spec, data, entity=entity, time=time)
+        result = enrich_result_with_parsed_standard_errors(result)
+        _set_result_attr(result, "backend", "pydynpd-via-systemgmmkit")
+        _set_result_attr(result, "systemgmmkit_backend_policy", backend)
+        return result
+
+    result = _call_native_backend(spec, data, entity=entity, time=time)
+    _set_result_attr(result, "backend", "native-via-systemgmmkit")
+    _set_result_attr(result, "systemgmmkit_backend_policy", backend)
+
+    if is_system:
+        warnings.warn(
+            "Native System GMM is experimental and not yet xtabond2-certified. "
+            "Use backend='auto' or backend='validated' for empirical System GMM.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        _append_result_note(
+            result,
+            "Native System GMM is experimental and not yet xtabond2-certified.",
+        )
+
+    return result
+
+
+def run_system_gmm(
+    spec: Any,
+    data: pd.DataFrame,
+    *,
+    entity: str,
+    time: str,
+    backend: DynamicGMMBackend = "auto",
+) -> Any:
+    """Run a System GMM specification through systemgmmkit."""
+
+    if not _is_system_gmm(spec):
+        raise ValueError(
+            "run_system_gmm() expects a System GMM spec with spec.system=True."
+        )
+
+    return run_dynamic_panel_gmm(
+        spec,
+        data,
+        entity=entity,
+        time=time,
+        backend=backend,
+    )
+
+
+def run_difference_gmm(
+    spec: Any,
+    data: pd.DataFrame,
+    *,
+    entity: str,
+    time: str,
+    backend: DynamicGMMBackend = "auto",
+) -> Any:
+    """Run a Difference GMM specification through systemgmmkit."""
+
+    if _is_system_gmm(spec):
+        raise ValueError(
+            "run_difference_gmm() expects a Difference GMM spec with spec.system=False."
+        )
+
+    return run_dynamic_panel_gmm(
+        spec,
+        data,
+        entity=entity,
+        time=time,
+        backend=backend,
+    )