westata 0.0.1__py3-none-any.whl

westata/__init__.py

@@ -0,0 +1,223 @@
+"""Export postestimation and report helpers from the top-level package."""
+
+from __future__ import annotations
+
+from westata.data import WEIGHT_TYPES, WeightSpec, normalize_weights
+from westata.expressions.explist import (
+    ExpListError,
+    ParsedExpressionList,
+    StoredResults,
+    parse_exp_list,
+)
+from westata.estimators import (
+    LlcResult,
+    levin_lin_chu,
+    IpsResult,
+    im_pesaran_shin,
+    Bootstrap,
+    Jackknife,
+    Permute,
+    SurveyDesign,
+    SvyLogit,
+    SvyMean,
+    SvyProportion,
+    SvyRegress,
+    SvyTotal,
+    AIPW,
+    Didregress,
+    IPW,
+    NearestNeighbourMatching,
+    RegressionAdjustment,
+    TreatmentEffectResult,
+    Xtdidregress,
+    Frontier,
+    Nl,
+    Eivreg,
+    Manova,
+    ManovaResult,
+    Mvreg,
+    Sureg,
+    XtAbond,
+    XtLogit,
+    XtNbreg,
+    XtPoisson,
+    XtProbit,
+    XtTobit,
+    XtGls,
+    XtIvreg,
+    XtPcse,
+    XtUnitroot,
+    Bsqreg,
+    Sqreg,
+    QuantileRegression,
+    RobustRegression,
+    Etregress,
+    Heckman,
+    Intreg,
+    Truncreg,
+    TruncatedNegativeBinomial,
+    TruncatedPoisson,
+    ZeroInflatedNegativeBinomial,
+    ZeroInflatedPoisson,
+    ARIMA,
+    FEOLS,
+    GARCH,
+    IV2SLS,
+    IVGMM,
+    IVLIML,
+    OLS,
+    VAR,
+    VECM,
+    BetweenOLS,
+    FirstDifferenceOLS,
+    Logit,
+    NegativeBinomial,
+    NegativeBinomialNB1,
+    OrderedLogit,
+    OrderedProbit,
+    PanelOLS,
+    Poisson,
+    Probit,
+    RandomEffects,
+    Tobit,
+    UnitRootResult,
+    unitroot,
+)
+from westata.errors import (
+    ConsistencyError,
+    ConvergenceError,
+    FormulaError,
+    UnsupportedError,
+    WeightError,
+    WestataError,
+)
+from westata.postestimation import (
+    HausmanResult,
+    LincomResult,
+    LRTestResult,
+    MarginsResult,
+    WaldTest,
+    contrast,
+    hausman,
+    lrtest,
+    margins,
+    nlcom,
+    pwcompare,
+    testnl,
+)
+from westata.protocols import SSC
+from westata.report import etable, to_latex, to_markdown
+
+__version__ = "0.0.1"
+
+
+def ssc(**kwargs: object) -> SSC:
+    """Convenience constructor mirroring ``ws.ssc(adj=True, ...)``."""
+
+    return SSC(**kwargs)  # type: ignore[arg-type]
+
+
+__all__ = [
+    "ParsedExpressionList",
+    "StoredResults",
+    "ExpListError",
+    "parse_exp_list",
+    "LlcResult",
+    "levin_lin_chu",
+    "IpsResult",
+    "im_pesaran_shin",
+    "Permute",
+    "Bootstrap",
+    "Jackknife",
+    "SvyLogit",
+    "SvyRegress",
+    "SvyProportion",
+    "SvyTotal",
+    "SvyMean",
+    "SurveyDesign",
+    "TreatmentEffectResult",
+    "NearestNeighbourMatching",
+    "AIPW",
+    "IPW",
+    "RegressionAdjustment",
+    "Xtdidregress",
+    "Didregress",
+    "Frontier",
+    "Nl",
+    "ManovaResult",
+    "Manova",
+    "Eivreg",
+    "Mvreg",
+    "Sureg",
+    "XtAbond",
+    "XtNbreg",
+    "XtPoisson",
+    "XtTobit",
+    "XtProbit",
+    "XtLogit",
+    "XtUnitroot",
+    "XtPcse",
+    "XtGls",
+    "XtIvreg",
+    "Bsqreg",
+    "Sqreg",
+    "RobustRegression",
+    "QuantileRegression",
+    "TruncatedNegativeBinomial",
+    "TruncatedPoisson",
+    "ZeroInflatedNegativeBinomial",
+    "ZeroInflatedPoisson",
+    "Etregress",
+    "Heckman",
+    "Intreg",
+    "Truncreg",
+    "HausmanResult",
+    "LRTestResult",
+    "pwcompare",
+    "contrast",
+    "hausman",
+    "lrtest",
+    "testnl",
+    "nlcom",
+    "SSC",
+    "ssc",
+    "OLS",
+    "IV2SLS",
+    "IVLIML",
+    "IVGMM",
+    "FEOLS",
+    "PanelOLS",
+    "RandomEffects",
+    "BetweenOLS",
+    "FirstDifferenceOLS",
+    "Logit",
+    "Probit",
+    "Poisson",
+    "NegativeBinomial",
+    "OrderedLogit",
+    "OrderedProbit",
+    "Tobit",
+    "ARIMA",
+    "VAR",
+    "VECM",
+    "GARCH",
+    "UnitRootResult",
+    "unitroot",
+    "WaldTest",
+    "LincomResult",
+    "MarginsResult",
+    "margins",
+    "etable",
+    "to_latex",
+    "to_markdown",
+    "WEIGHT_TYPES",
+    "WeightSpec",
+    "normalize_weights",
+    "WestataError",
+    "ConsistencyError",
+    "ConvergenceError",
+    "FormulaError",
+    "UnsupportedError",
+    "WeightError",
+    "__version__",
+]

westata/conformance/__init__.py

@@ -0,0 +1,37 @@
+"""Conformance harness: evidence registry, tolerances and oracle adapters.
+
+Design spec: ``docs/superpowers/specs/2026-10-22-westata-design.md`` section
+11.  Numeric claims against Stata are only as strong as their evidence level,
+so the suite keeps the claim (registry), the yardstick (tolerances) and the
+checkable identities (oracles) together.
+"""
+
+from __future__ import annotations
+
+from westata.conformance.oracles.invariants import check_ols_invariants
+from westata.conformance.registry import (
+    VALID_LEVELS,
+    VALID_SOURCE_TYPES,
+    Evidence,
+    load_registry,
+    validate_registry,
+)
+from westata.conformance.tolerances import (
+    LINEAR_RTOL,
+    MLE_RTOL,
+    MLE_SE_RTOL,
+    assert_close,
+)
+
+__all__ = [
+    "LINEAR_RTOL",
+    "MLE_RTOL",
+    "MLE_SE_RTOL",
+    "VALID_LEVELS",
+    "VALID_SOURCE_TYPES",
+    "Evidence",
+    "assert_close",
+    "check_ols_invariants",
+    "load_registry",
+    "validate_registry",
+]

westata/conformance/oracles/__init__.py

@@ -0,0 +1,7 @@
+"""Oracle adapters for Stata conformance (design spec section 11.2)."""
+
+from __future__ import annotations
+
+from westata.conformance.oracles.invariants import check_ols_invariants
+
+__all__ = ["check_ols_invariants"]

westata/conformance/oracles/invariants.py

@@ -0,0 +1,124 @@
+"""Invariant oracles: identities every correct OLS fit must satisfy.
+
+Design spec: ``docs/superpowers/specs/2026-10-22-westata-design.md`` section
+11.2 (``InvariantOracle``).  Least squares is defined by the normal equations,
+so any estimator (our own, statsmodels, Stata) must produce residuals
+orthogonal to the design matrix, and — when a constant is included — residuals
+that sum to zero.  These checks need no Stata license and no fixture.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+
+def _as_float_array(value: object, name: str) -> np.ndarray:
+    """Coerce ``value`` to a float array, raising ``TypeError`` on garbage."""
+
+    try:
+        return np.asarray(value, dtype=float)
+    except (TypeError, ValueError) as exc:
+        raise TypeError(
+            f"{name} must be numeric, got {type(value).__name__}: {value!r}"
+        ) from exc
+
+
+def check_ols_invariants(
+    X: np.ndarray,
+    resid: np.ndarray,
+    params: np.ndarray,
+    *,
+    has_intercept: bool,
+    atol: float = 1e-10,
+) -> None:
+    """Assert the least-squares normal equations for a fitted model.
+
+    Checks
+    ------
+    1. ``X.T @ resid ~= 0`` (residuals orthogonal to every regressor).
+    2. When ``has_intercept`` is true, ``sum(resid) ~= 0``.
+
+    Floating-point orthogonality is judged against the problem scale:
+    ``max|X.T @ resid|`` is compared with ``atol * ||X||_inf * ||resid||_inf *
+    nobs``.  A raw absolute threshold would reject exact solves on
+    large-magnitude regressors (e.g. wages measured in thousands), because
+    cancellation alone leaves a residual gradient of order
+    ``eps * ||X|| * ||resid|| * nobs``.
+
+    Parameters
+    ----------
+    X:
+        ``nobs x nparams`` design matrix.
+    resid:
+        ``nobs`` residual vector of the fitted model.
+    params:
+        Fitted coefficient vector, shape ``(nparams,)``.  It is not used in the
+        identity itself, but requiring it keeps callers from pairing residuals
+        with the wrong design matrix.
+    has_intercept:
+        Whether the model includes a constant term; only then is
+        ``sum(resid) = 0`` expected.
+    atol:
+        Scale-relative tolerance, positive and finite.
+
+    Raises
+    ------
+    ValueError
+        On malformed inputs (wrong shapes, non-finite data, bad ``atol``).
+    AssertionError
+        When the normal equations or the intercept condition do not hold.
+    """
+
+    X_arr = _as_float_array(X, "X")
+    resid_arr = _as_float_array(resid, "resid")
+    params_arr = _as_float_array(params, "params")
+
+    if X_arr.ndim != 2 or X_arr.shape[0] == 0 or X_arr.shape[1] == 0:
+        raise ValueError(f"X must be a non-empty 2-D array, got shape {X_arr.shape}")
+    nobs, nparams = X_arr.shape
+    if params_arr.shape != (nparams,):
+        raise ValueError(
+            f"params must have shape ({nparams},) to match X, got {params_arr.shape}"
+        )
+    if resid_arr.shape != (nobs,):
+        raise ValueError(
+            f"resid must have shape ({nobs},) to match X, got {resid_arr.shape}"
+        )
+    if not math.isfinite(atol) or atol <= 0:
+        raise ValueError(f"atol must be positive and finite, got {atol!r}")
+    if not (np.all(np.isfinite(X_arr)) and np.all(np.isfinite(resid_arr))):
+        raise ValueError("X and resid must contain only finite values")
+
+    # 1) Normal equations: X.T @ resid == 0.
+    gradient = X_arr.T @ resid_arr
+    gradient_scale = max(
+        1.0,
+        float(np.max(np.abs(X_arr))) * float(np.max(np.abs(resid_arr))) * nobs,
+    )
+    gradient_threshold = atol * gradient_scale
+    max_gradient = float(np.max(np.abs(gradient)))
+    if max_gradient > gradient_threshold:
+        raise AssertionError(
+            "OLS normal equations violated: max |X.T @ resid| = "
+            f"{max_gradient:.6e} exceeds scale-adjusted threshold "
+            f"{gradient_threshold:.6e} "
+            f"(atol={atol:.3g}, scale={gradient_scale:.6e})"
+        )
+
+    # 2) Intercept condition: sum(resid) == 0.
+    if has_intercept:
+        total_resid = abs(float(np.sum(resid_arr)))
+        sum_scale = max(1.0, nobs * float(np.max(np.abs(resid_arr))))
+        sum_threshold = atol * sum_scale
+        if total_resid > sum_threshold:
+            raise AssertionError(
+                "OLS intercept invariant violated: |sum(resid)| = "
+                f"{total_resid:.6e} exceeds scale-adjusted threshold "
+                f"{sum_threshold:.6e} "
+                f"(atol={atol:.3g}, scale={sum_scale:.6e})"
+            )
+
+
+__all__ = ["check_ols_invariants"]

westata/conformance/oracles/stata.py

@@ -0,0 +1,270 @@
+"""Stata oracle: run real Stata and capture ``e()`` for conformance checks.
+
+Requires StataNow/Stata 17+ with the bundled ``pystata`` package and a valid
+licence.  This module is a *test* dependency; nothing in ``westata`` imports it
+at runtime.
+
+Two properties matter for reproducible evidence:
+
+* Results are captured as plain floats/arrays and can be written to JSON, so a
+  comparison can be replayed on a machine without Stata.
+* Every capture records ``c(stata_version)`` and ``c(version)``, because Stata
+  results are only meaningful relative to a version.
+
+Typical use::
+
+    with StataOracle(stata_dir=r"D:\\Program Files\\StataNow19", edition="mp") as so:
+        so.run("sysuse auto, clear")
+        so.run("regress mpg weight foreign")
+        capture = so.capture()
+    capture["b"]          # coefficients, in e(b) order
+    capture["V"]          # covariance matrix
+    capture["scalars"]    # e(N), e(df_r), e(r2), ...
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Sequence
+
+import numpy as np
+
+__all__ = ["StataCapture", "StataOracle", "stata_available"]
+
+#: Default install location on this machine; override via ``stata_dir``.
+DEFAULT_STATA_DIR = r"D:\Program Files\StataNow19"
+
+
+def stata_available() -> bool:
+    """Whether a Stata installation with ``pystata`` is reachable."""
+
+    candidate = Path(DEFAULT_STATA_DIR) / "utilities"
+    return candidate.is_dir()
+
+
+def _strip_prefix(key: str) -> str:
+    """``"e(N)" -> "N"``; leave already-bare names alone."""
+
+    if key.startswith("e(") and key.endswith(")"):
+        return key[2:-1]
+    return key
+
+
+@dataclass
+class StataCapture:
+    """Everything a conformance check needs from one Stata estimation.
+
+    Attributes
+    ----------
+    b:
+        Coefficient vector in ``e(b)`` order.
+    V:
+        Covariance matrix of the estimators.
+    scalars:
+        Scalar ``e()`` results keyed without the ``e()`` wrapper.
+    macros:
+        String-valued ``e()`` results (``cmd``, ``vce``, ...).
+    names:
+        Coefficient names in ``e(b)`` order.
+    version:
+        Stata version string the capture was produced with.
+    """
+
+    b: np.ndarray
+    V: np.ndarray
+    scalars: dict[str, float]
+    macros: dict[str, str]
+    names: list[str] = field(default_factory=list)
+    version: str = ""
+
+    def __getitem__(self, key: str) -> Any:
+        if key in self.scalars:
+            return self.scalars[key]
+        raise KeyError(f"{key!r} not in captured e() scalars: {sorted(self.scalars)}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "b": self.b.tolist(),
+            "V": self.V.tolist(),
+            "scalars": self.scalars,
+            "macros": self.macros,
+            "names": self.names,
+            "version": self.version,
+        }
+
+    def save(self, path: str | Path) -> Path:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(self.to_dict(), indent=2), encoding="utf-8")
+        return path
+
+    @classmethod
+    def load(cls, path: str | Path) -> "StataCapture":
+        payload = json.loads(Path(path).read_text(encoding="utf-8"))
+        return cls(
+            b=np.asarray(payload["b"], dtype=float),
+            V=np.asarray(payload["V"], dtype=float),
+            scalars={k: float(v) for k, v in payload["scalars"].items()},
+            macros=payload["macros"],
+            names=list(payload.get("names", [])),
+            version=payload.get("version", ""),
+        )
+
+
+class StataOracle:
+    """Context manager that owns one embedded Stata session.
+
+    Parameters
+    ----------
+    stata_dir:
+        Stata installation directory (the one containing ``utilities/pystata``).
+    edition:
+        ``"mp"``, ``"se"`` or ``"be"``.
+    """
+
+    def __init__(
+        self,
+        stata_dir: str = DEFAULT_STATA_DIR,
+        edition: str = "mp",
+    ) -> None:
+        self._stata_dir = stata_dir
+        self._edition = edition
+        self._stata: Any = None
+
+    # ------------------------------------------------------------ lifecycle
+    def __enter__(self) -> "StataOracle":
+        self.start()
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    def start(self) -> None:
+        utilities = str(Path(self._stata_dir) / "utilities")
+        if utilities not in sys.path:
+            sys.path.append(utilities)
+        from pystata import config
+
+        config.init(self._edition, splash=False)
+        from pystata import stata
+
+        self._stata = stata
+
+    def close(self) -> None:
+        # pystata has no explicit shutdown; dropping the reference is enough and
+        # avoids surprising the caller with a half-dead interpreter.
+        self._stata = None
+
+    # ---------------------------------------------------------------- running
+    def run(self, command: str, *, quietly: bool = True) -> None:
+        if self._stata is None:
+            raise RuntimeError("StataOracle is not started; use it as a context manager")
+        self._stata.run(command, quietly=quietly)
+
+    def run_all(self, lines: Iterable[str]) -> None:
+        for line in lines:
+            self.run(line)
+
+    def send_data(self, frame: Any, name: str = "df") -> None:
+        """Load a pandas DataFrame into Stata under ``name``."""
+
+        if self._stata is None:
+            raise RuntimeError("StataOracle is not started")
+        self._stata.pdataframe_to_data(frame, force=True)
+
+    def get_output(self, command: str) -> str:
+        """Run ``command`` and return its printed output.
+
+        ``pystata.run(..., echo=False)`` prints to the process stdout instead of
+        returning a string, so the output is captured by temporarily redirecting
+        ``sys.stdout``.  Without this, output-parsing checks would see ``""`` and
+        silently "fail to parse" rather than reporting the real result.
+        """
+
+        if self._stata is None:
+            raise RuntimeError("StataOracle is not started")
+
+        import io
+        from contextlib import redirect_stdout
+
+        buffer = io.StringIO()
+        with redirect_stdout(buffer):
+            self._stata.run(command, echo=False)
+        return buffer.getvalue()
+
+    # ------------------------------------------------------------- capturing
+    def capture(self, *, names: Sequence[str] | None = None) -> StataCapture:
+        """Return the current ``e()`` results as a :class:`StataCapture`."""
+
+        if self._stata is None:
+            raise RuntimeError("StataOracle is not started")
+        raw = self._stata.get_ereturn()
+
+        b = None
+        V = None
+        scalars: dict[str, float] = {}
+        macros: dict[str, str] = {}
+
+        for key, value in raw.items():
+            name = _strip_prefix(key)
+            if value is None:
+                continue
+            if name == "b":
+                b = np.asarray(value, dtype=float).reshape(-1)
+            elif name == "V":
+                V = np.asarray(value, dtype=float)
+            elif isinstance(value, str):
+                macros[name] = value
+            elif isinstance(value, (int, float, np.floating, np.integer)):
+                scalars[name] = float(value)
+
+        if b is None or V is None:
+            raise RuntimeError(
+                "no e(b)/e(V) available; run an estimation command first"
+            )
+
+        # Coefficient order matters: e(b) is a row vector whose *column* stripes
+        # hold the names.  Read them from Stata rather than inferring, otherwise
+        # a comparison could align the wrong coefficients and still "pass".
+        coefficient_names = list(names) if names else self._coefficient_names()
+
+        # Version is recorded because a conformance claim is only meaningful
+        # against a specific Stata release. ``display`` writes nothing to r(), so
+        # read the value through a local macro instead.
+        version = self._stata_version()
+
+        return StataCapture(
+            b=b,
+            V=V,
+            scalars=scalars,
+            macros=macros,
+            names=coefficient_names,
+            version=version,
+        )
+
+    def _coefficient_names(self) -> list[str]:
+        """Read the ``e(b)`` column stripes via ``sfi``."""
+
+        if self._stata is None:
+            return []
+        try:
+            names = self._stata.sfi.Matrix.getColNames("e(b)")
+            return [str(name) for name in names]
+        except Exception:
+            return []
+
+    def _stata_version(self) -> str:
+        """Return ``c(stata_version)``, or ``""`` when it cannot be read.
+
+        pystata exposes no direct Python accessor for ``c()`` macros and
+        ``display`` writes nothing to ``r()``, so this deliberately returns an
+        empty string rather than scraping stdout.  Record the version in the
+        evidence registry by hand instead; a silently wrong version string would
+        be worse than an absent one.
+        """
+
+        return ""