open-econs 0.3.0__py3-none-any.whl

open_econs/__init__.py

@@ -0,0 +1,8 @@
+from ._version import __version__
+from .models.linear.ols import ols
+from .models.decomposition.oaxaca import oaxaca
+from .core.context import Context
+
+reg = ols
+
+__all__ = ["ols", "reg", "oaxaca", "Context", "__version__"]

open_econs/_internal/errors.py

@@ -0,0 +1,47 @@
+from collections.abc import Sequence
+
+
+def missing_column_error(name: str, available: Sequence[str]) -> ValueError:
+    available_str = ", ".join(sorted(available))
+    return ValueError(
+        f"Column '{name}' not found in DataFrame. "
+        f"Available columns: [{available_str}]"
+    )
+
+
+def cluster_column_error(name: str, available: Sequence[str]) -> ValueError:
+    available_str = ", ".join(sorted(available))
+    return ValueError(
+        f"Cluster column '{name}' not found in DataFrame. "
+        f"Available columns: [{available_str}]"
+    )
+
+
+def non_binary_error(name: str, values: Sequence) -> ValueError:
+    found = ", ".join(repr(v) for v in values)
+    return ValueError(
+        f"Column '{name}' must be binary (exactly 2 unique non-null values). "
+        f"Found {len(values)} unique values: [{found}]"
+    )
+
+
+def empty_data_error(original_n: int, dropped: int = 0, cols: list[str] | None = None) -> ValueError:
+    msg = f"DataFrame has 0 rows after dropping missing values. Started with {original_n} rows"
+    if dropped:
+        cols_str = ", ".join(cols or ["unknown"])
+        msg += f", {dropped} had missing values in: [{cols_str}]"
+    msg += "."
+    return ValueError(msg)
+
+
+def singular_matrix_error() -> RuntimeError:
+    return RuntimeError(
+        "Singular design matrix — check for collinear or duplicated variables in your formula."
+    )
+
+
+def rows_dropped_warning(dropped: int, total: int, cols: list[str]) -> str:
+    cols_str = ", ".join(sorted(cols))
+    return (
+        f"Dropped {dropped} of {total} rows due to missing values in: [{cols_str}]"
+    )

open_econs/_internal/formula.py

@@ -0,0 +1,47 @@
+import warnings
+
+import pandas as pd
+from formulaic import Formula
+
+from open_econs._internal.errors import (
+    empty_data_error,
+    missing_column_error,
+    rows_dropped_warning,
+)
+
+
+def parse_formula(
+    formula: str,
+    data: pd.DataFrame,
+) -> tuple[pd.DataFrame, pd.DataFrame]:
+    _validate_columns_in_data(formula, data)
+
+    original_n = len(data)
+    result = Formula(formula).get_model_matrix(data, na_action="drop")
+    yy: pd.DataFrame = result.lhs
+    XX: pd.DataFrame = result.rhs
+
+    dropped = original_n - len(yy)
+    if dropped > 0:
+        cols = _find_missing_cols(formula, data)
+        warnings.warn(rows_dropped_warning(dropped, original_n, cols))
+
+    if len(yy) == 0:
+        cols = _find_missing_cols(formula, data)
+        raise empty_data_error(original_n, dropped, cols)
+
+    return yy, XX
+
+
+def _validate_columns_in_data(formula: str, data: pd.DataFrame) -> None:
+    f = Formula(formula)
+    vars_needed: set[str] = {str(v) for v in f.required_variables}
+    missing = sorted(v for v in vars_needed if v not in data.columns)
+    if missing:
+        raise missing_column_error(missing[0], data.columns.tolist())
+
+
+def _find_missing_cols(formula: str, data: pd.DataFrame) -> list[str]:
+    f = Formula(formula)
+    vars_needed: set[str] = {str(v) for v in f.required_variables}
+    return sorted(v for v in vars_needed if data[v].isna().any())

open_econs/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

open_econs/core/base.py

@@ -0,0 +1,83 @@
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any
+
+import pandas as pd
+class BaseModel(ABC):
+    formula: str = ""
+    data_shape: tuple[int, int] = (0, 0)
+    cov_type: str = ""
+    call: dict[str, Any] = {}
+    timestamp: datetime = datetime.fromtimestamp(0)
+    package_version: str = ""
+
+    _frozen: bool = False
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if getattr(self, "_frozen", False):
+            raise AttributeError(
+                f"{type(self).__name__} results are immutable after fit(). "
+                f"Cannot set '{name}'. Create a new estimate instead."
+            )
+        super().__setattr__(name, value)
+
+    def _freeze(self) -> None:
+        object.__setattr__(self, "_frozen", True)
+
+    # ── abstract interface ──────────────────────────────────────────
+
+    @abstractmethod
+    def tidy(self) -> pd.DataFrame:
+        """Coefficient or effect table, one row per term (R-broom style)."""
+
+    @abstractmethod
+    def summary(self) -> str:
+        """Pretty-printed terminal string."""
+
+    # ── optional stubs (loud) ───────────────────────────────────────
+
+    def predict(self, newdata: pd.DataFrame | None = None) -> pd.Series:
+        raise NotImplementedError(
+            f"{type(self).__name__} does not support predict(). "
+            "predict() is only defined for LinearModel-family results."
+        )
+
+    def plot(self) -> None:
+        raise NotImplementedError(
+            "plot() is not implemented in this version of open-econs. "
+            "Planned for a future release; matplotlib will be an optional "
+            "extra, not a hard dependency. In the meantime, call .tidy() "
+            "and plot the DataFrame yourself."
+        )
+
+    def export(self, path: str) -> None:
+        import json
+
+        if path.endswith(".json"):
+            data = self.to_dict()
+            with open(path, "w") as fh:
+                json.dump(data, fh, indent=2, default=str)
+        elif path.endswith(".csv"):
+            self.tidy().to_csv(path, index=False)
+        else:
+            raise NotImplementedError(
+                f"export() to '{path.rsplit('.', 1)[-1]}' is not supported in "
+                "this version. Only .json and .csv export are available. "
+                "Export with a '.json' or '.csv' extension, or call .tidy() "
+                "and save the DataFrame yourself."
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        d = self.tidy().to_dict(orient="records")
+        return {
+            "formula": self.formula,
+            "nobs": self.data_shape[0],
+            "cov_type": self.cov_type,
+            "call": {k: (str(v) if not isinstance(v, (str, int, float, bool, type(None))) else v) for k, v in self.call.items()},
+            "timestamp": str(self.timestamp),
+            "package_version": self.package_version,
+            "results": d,
+        }
+
+    def __repr__(self) -> str:
+        return self.summary()

open_econs/core/context.py

@@ -0,0 +1,54 @@
+from typing import Any
+
+import pandas as pd
+
+
+class Context:
+    """A context that remembers a dataset for repeated estimation.
+
+    Once created, every estimator method forwards to the top-level
+    function with ``data=self.data`` injected automatically.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        The working dataset.
+
+    Examples
+    --------
+    >>> import open_econs as oe
+    >>> ctx = oe.Context(df)
+    >>> r1 = ctx.ols("income ~ education + age")
+    >>> r2 = ctx.oaxaca("income ~ education + age + female", by="female")
+    """
+
+    def __init__(self, data: pd.DataFrame) -> None:
+        self._data = data
+
+    def ols(
+        self,
+        formula: str,
+        cluster: str | None = None,
+        cov_type: str = "HC1",
+    ) -> Any:
+        from open_econs.models.linear.ols import ols as _ols
+
+        return _ols(formula=formula, data=self._data, cluster=cluster, cov_type=cov_type)
+
+    def oaxaca(
+        self,
+        formula: str,
+        by: str,
+        decomposition_type: str = "two-fold",
+    ) -> Any:
+        from open_econs.models.decomposition.oaxaca import oaxaca as _oaxaca
+
+        return _oaxaca(
+            formula=formula,
+            data=self._data,
+            by=by,
+            decomposition_type=decomposition_type,
+        )
+
+    def __repr__(self) -> str:
+        return f"Context(data: {self._data.shape[0]} rows, {self._data.shape[1]} cols)"

open_econs/core/results.py

@@ -0,0 +1,341 @@
+from datetime import datetime
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from scipy import stats as _stats
+from statsmodels.stats.diagnostic import het_breuschpagan as _het_breuschpagan
+from statsmodels.stats.stattools import durbin_watson as _durbin_watson
+
+from open_econs._version import __version__
+from open_econs.core.base import BaseModel
+
+
+def _ramsey_reset(
+    fitted: np.ndarray, resid: np.ndarray, power: int = 3,
+) -> tuple[float, float]:
+    n = len(resid)
+    y_hat_sq = np.column_stack([fitted ** p for p in range(2, power + 1)])
+    X_aug = np.column_stack([np.ones(n), fitted, y_hat_sq])
+    beta = np.linalg.lstsq(X_aug, fitted + resid, rcond=None)[0]
+    pred_aug = X_aug @ beta
+    resid_aug = (fitted + resid) - pred_aug
+    ssr_r = np.sum(resid ** 2)
+    ssr_u = np.sum(resid_aug ** 2)
+    k = 1
+    m = power - 1
+    df_num = m
+    df_den = n - k - m - 1
+    if df_den <= 0 or ssr_u <= 0:
+        return (float("nan"), float("nan"))
+    f_stat = ((ssr_r - ssr_u) / m) / (ssr_u / df_den)
+    p_val = 1.0 - _stats.f.cdf(f_stat, df_num, df_den)
+    return (float(f_stat), float(p_val))
+
+
+class OLSResult(BaseModel):
+    def __init__(
+        self,
+        *,
+        formula: str,
+        rhs_formula: str,
+        nobs: int,
+        df_resid: int,
+        df_model: int,
+        cov_type: str,
+        coefficients: pd.Series,
+        std_errors: pd.Series,
+        t_stats: pd.Series,
+        p_values: pd.Series,
+        conf_int: pd.DataFrame,
+        r_squared: float,
+        adj_r_squared: float,
+        f_statistic: float,
+        f_p_value: float,
+        rsd: float,
+        llf: float,
+        aic: float,
+        bic: float,
+        fitted: pd.Series,
+        residuals: pd.Series,
+        call: dict[str, Any],
+        model_spec: Any = None,
+        condition_number: float = 0.0,
+        _X: pd.DataFrame | None = None,
+        _sm_fit: Any = None,
+    ) -> None:
+        self.formula = formula
+        self.rhs_formula = rhs_formula
+        self.data_shape = (nobs, coefficients.shape[0])
+        self.cov_type = cov_type
+        self.call = call
+        self.timestamp = datetime.now()
+        self.package_version = __version__
+
+        self.nobs = nobs
+        self.df_resid = df_resid
+        self.df_model = df_model
+        self.coefficients = coefficients
+        self.std_errors = std_errors
+        self.t_stats = t_stats
+        self.p_values = p_values
+        self.conf_int = conf_int
+        self.r_squared = r_squared
+        self.adj_r_squared = adj_r_squared
+        self.f_statistic = f_statistic
+        self.f_p_value = f_p_value
+        self.rsd = rsd
+        self.llf = llf
+        self.aic = aic
+        self.bic = bic
+        self.fitted_values = fitted if fitted is not None else pd.Series(dtype=float)
+        self.residuals = residuals
+        self._model_spec = model_spec
+        self.condition_number = condition_number
+        self._X = _X
+        self._sm_fit = _sm_fit
+
+        self._freeze()
+
+    def tidy(self) -> pd.DataFrame:
+        df = pd.DataFrame({
+            "Variable": self.coefficients.index,
+            "Coef": self.coefficients.values,
+            "Std Err": self.std_errors.values,
+            "t": self.t_stats.values,
+            "P>|t|": self.p_values.values,
+            "0.025": self.conf_int["lower"].values,
+            "0.975": self.conf_int["upper"].values,
+        })
+        df.index.name = None
+        return df
+
+    def summary(self) -> str:
+        llf_str = f"{self.llf:.3f}" if self.llf is not None and not self._isnan(self.llf) else "N/A"
+        aic_str = f"{self.aic:.2f}" if self.aic is not None and not self._isnan(self.aic) else "N/A"
+        bic_str = f"{self.bic:.2f}" if self.bic is not None and not self._isnan(self.bic) else "N/A"
+        header = (
+            f"                            OLS Regression Results                            \n"
+            f"======================================================================\n"
+            f"Dep. Variable:               {self.formula.split('~')[0].strip()}\n"
+            f"No. Observations:            {self.nobs}\n"
+            f"Df Residuals:                {self.df_resid}\n"
+            f"Df Model:                    {self.df_model}\n"
+            f"Covariance Type:             {self.cov_type}\n"
+            f"R-squared:                   {self.r_squared:.6f}\n"
+            f"Adj. R-squared:           {self.adj_r_squared:.6f}\n"
+            f"Condition No.:               {self._fmt(self.condition_number, '.2e')}\n"
+            f"F-statistic:                 {self._fmt(self.f_statistic, '.4f')}\n"
+            f"Prob (F-statistic):          {self._fmt(self.f_p_value, '.6e')}\n"
+            f"Log-Likelihood:              {llf_str}\n"
+            f"AIC:                         {aic_str}\n"
+            f"BIC:                         {bic_str}\n"
+            f"======================================================================\n"
+        )
+        tbl = self.tidy().to_string(index=False)
+        diag = self.diagnostics()
+        diag_lines = []
+        try:
+            jb_s, jb_p = diag.get("jarque_bera", (float("nan"), float("nan")))
+            diag_lines.append(f"Jarque-Bera (chi2={jb_s:.3f}, p={jb_p:.4f})")
+        except Exception:
+            diag_lines.append("Jarque-Bera: N/A")
+        try:
+            bp_s, bp_p = diag.get("breusch_pagan", (float("nan"), float("nan")))
+            diag_lines.append(f"Breusch-Pagan (LM={bp_s:.3f}, p={bp_p:.4f})")
+        except Exception:
+            diag_lines.append("Breusch-Pagan: N/A")
+        try:
+            dw = diag.get("durbin_watson", (float("nan"),))[0]
+            diag_lines.append(f"Durbin-Watson:                  {dw:.4f}")
+        except Exception:
+            diag_lines.append("Durbin-Watson: N/A")
+        try:
+            rs_s, rs_p = diag.get("ramsey_reset", (float("nan"), float("nan")))
+            diag_lines.append(f"Ramsey RESET (F={rs_s:.3f}, p={rs_p:.4f})")
+        except Exception:
+            diag_lines.append("Ramsey RESET: N/A")
+        diag_str = "\n".join(diag_lines)
+        return (
+            header + tbl +
+            "\n======================================================================\n"
+            f"Diagnostics:\n{diag_str}\n"
+            "======================================================================\n"
+        )
+
+    def _isnan(self, v: float) -> bool:
+        try:
+            return np.isnan(v)
+        except (TypeError, ValueError):
+            return True
+
+    def _fmt(self, v: float, spec: str) -> str:
+        if self._isnan(v):
+            return "N/A"
+        return f"{v:{spec}}"
+
+    def diagnostics(self) -> dict[str, tuple[float, float]]:
+        res = self.residuals.values.ravel()
+        fitted = self.fitted_values.values.ravel()
+        results: dict[str, tuple[float, float]] = {}
+        from scipy.stats import jarque_bera as _jb
+        jb_stat, jb_p = _jb(res)
+        results["jarque_bera"] = (float(jb_stat), float(jb_p))
+        dw = _durbin_watson(res)
+        results["durbin_watson"] = (float(dw), float("nan"))
+        if self._X is not None and len(self._X) == len(res):
+            X_vals = self._X.values.astype(float)
+            bp_stat, bp_p, _, _ = _het_breuschpagan(res, X_vals)
+            results["breusch_pagan"] = (float(bp_stat), float(bp_p))
+        reset_stat, reset_p = _ramsey_reset(fitted, res, power=3)
+        results["ramsey_reset"] = (float(reset_stat), float(reset_p))
+        return results
+
+    def wald_test(self, r_matrix: Any) -> Any:
+        if self._sm_fit is None:
+            raise RuntimeError(
+                "No fitted statsmodels result stored. "
+                "wald_test() is only available when ols() is used directly."
+            )
+        return self._sm_fit.wald_test(r_matrix)
+
+    def f_test(self, r_matrix: Any) -> Any:
+        if self._sm_fit is None:
+            raise RuntimeError(
+                "No fitted statsmodels result stored. "
+                "f_test() is only available when ols() is used directly."
+            )
+        return self._sm_fit.f_test(r_matrix)
+
+    def predict(self, newdata: pd.DataFrame | None = None) -> pd.Series:
+        if newdata is None:
+            return self.fitted_values
+        try:
+            if self._model_spec is not None:
+                matrices = self._model_spec.get_model_matrix(newdata, na_action="drop")
+                if hasattr(matrices, "rhs"):
+                    XX = matrices.rhs
+                else:
+                    XX = matrices
+            else:
+                from formulaic import Formula
+                matrices = Formula(self.rhs_formula).get_model_matrix(newdata, na_action="drop")
+                XX = matrices.rhs if hasattr(matrices, "rhs") else matrices
+        except Exception as e:
+            msg = str(e)
+            if "not present in the dataset" in msg or "is not present" in msg:
+                import re as _re
+                m = _re.search(r"`(\w+)`", msg)
+                bad_col = m.group(1) if m else self.rhs_formula
+                from open_econs._internal.errors import missing_column_error
+                raise missing_column_error(bad_col, newdata.columns.tolist()) from e
+            raise
+        pred = pd.Series(
+            np.dot(XX.values, self.coefficients.values),
+            index=XX.index,
+            name="predicted",
+        )
+        return pred
+
+    def plot(self) -> None:
+        try:
+            import matplotlib.pyplot as plt
+        except ImportError:
+            raise ImportError(
+                "plot() requires matplotlib. Install it with: "
+                "pip install open-econs[plot]  or  pip install matplotlib"
+            )
+        res = self.residuals.values.ravel()
+        fitted = self.fitted_values.values.ravel()
+        fig, axes = plt.subplots(2, 2, figsize=(10, 8))
+        ax1, ax2, ax3, ax4 = axes[0, 0], axes[0, 1], axes[1, 0], axes[1, 1]
+        ax1.scatter(fitted, res, alpha=0.5, s=20)
+        ax1.axhline(0, color="red", linestyle="--", linewidth=1)
+        ax1.set_xlabel("Fitted values")
+        ax1.set_ylabel("Residuals")
+        ax1.set_title("Residuals vs Fitted")
+        from scipy.stats import probplot
+        probplot(res, dist="norm", plot=ax2)
+        ax2.get_lines()[0].set_marker("o")
+        ax2.get_lines()[0].set_markersize(3)
+        ax2.get_lines()[0].set_alpha(0.5)
+        ax2.set_title("Normal Q-Q")
+        sqrt_abs_res = np.sqrt(np.abs(res))
+        ax3.scatter(fitted, sqrt_abs_res, alpha=0.5, s=20)
+        ax3.set_xlabel("Fitted values")
+        ax3.set_ylabel("Sqrt(|Residuals|)")
+        ax3.set_title("Scale-Location")
+        ax4.text(0.5, 0.5, "Leverage plot: planned for v0.4", ha="center", va="center", transform=ax4.transAxes)
+        ax4.set_title("Residuals vs Leverage")
+        fig.tight_layout()
+        plt.show()
+
+
+class OaxacaResult(BaseModel):
+    def __init__(
+        self,
+        *,
+        formula: str,
+        nobs: int,
+        n_params: int,
+        cov_type: str,
+        explained: float,
+        unexplained: float,
+        interaction: float | None,
+        total_gap: float,
+        decomposition_type: str,
+        by_groups: tuple[str, str],
+        std: pd.Series | None,
+        call: dict[str, Any],
+        variable_detail: pd.DataFrame | None = None,
+    ) -> None:
+        self.formula = formula
+        self.data_shape = (nobs, n_params)
+        self.cov_type = cov_type
+        self.call = call
+        self.timestamp = datetime.now()
+        self.package_version = __version__
+
+        self.nobs = nobs
+        self.explained = explained
+        self.unexplained = unexplained
+        self.interaction = interaction if interaction is not None else 0.0
+        self.total_gap = total_gap
+        self.type = decomposition_type
+        self.by_groups = by_groups
+        self.std = std
+        self.variable_detail = variable_detail if variable_detail is not None else pd.DataFrame()
+
+        self._freeze()
+
+    def tidy(self, detail: bool = False) -> pd.DataFrame:
+        if detail and not self.variable_detail.empty:
+            return self.variable_detail
+        if self.type == "two-fold":
+            data = {
+                "Component": ["Explained", "Unexplained", "Total Gap"],
+                "Effect": [self.explained, self.unexplained, self.total_gap],
+            }
+        else:
+            data = {
+                "Component": ["Endowment", "Coefficients", "Interaction", "Total Gap"],
+                "Effect": [self.explained, self.unexplained, self.interaction, self.total_gap],
+            }
+        df = pd.DataFrame(data)
+        if self.std is not None:
+            std_vals = list(self.std) + [float("nan")]
+            df["Std Err"] = std_vals[: len(df)]
+        return df
+
+    def summary(self) -> str:
+        header = (
+            f"                     Oaxaca-Blinder Decomposition                        \n"
+            f"======================================================================\n"
+            f"Formula:                    {self.formula}\n"
+            f"No. Observations:           {self.nobs}\n"
+            f"Groups:                     {self.by_groups[0]} vs {self.by_groups[1]}\n"
+            f"Type:                       {self.type}\n"
+            f"======================================================================\n"
+        )
+        tbl = self.tidy().to_string(index=False)
+        return header + tbl + "\n======================================================================\n"

open_econs/models/decomposition/oaxaca.py

@@ -0,0 +1,205 @@
+from datetime import datetime
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from statsmodels.stats.oaxaca import OaxacaBlinder
+
+from open_econs._version import __version__
+from open_econs._internal import errors
+from open_econs._internal.formula import parse_formula
+from open_econs.core.results import OaxacaResult
+
+
+def oaxaca(
+    formula: str,
+    data: pd.DataFrame,
+    by: str,
+    decomposition_type: str = "two-fold",
+    std: bool = False,
+    bootstrap_n: int = 1000,
+    conf_level: float = 0.95,
+    seed: int | None = None,
+    swap: bool = True,
+) -> OaxacaResult:
+    """Perform an Oaxaca-Blinder decomposition.
+
+    Parameters
+    ----------
+    formula : str
+        Two-sided formula string, e.g. ``"income ~ education + age + female"``.
+        ``by`` must appear on the RHS of the formula.
+    data : pd.DataFrame
+        Data containing all variables referenced in *formula*.
+    by : str
+        Column name of the binary group indicator.  Must appear in the RHS
+        of *formula*.
+    decomposition_type : str, default "two-fold"
+        Either ``"two-fold"`` or ``"three-fold"``.
+    std : bool, default False
+        If True, compute bootstrapped standard errors.  Bootstrap is
+        computationally expensive; 500 iterations is a reasonable minimum
+        for exploration, 1000+ for publication.
+    bootstrap_n : int, default 1000
+        Number of bootstrap replications (only used when ``std=True``).
+        Statsmodels' own default is 5000; 1000 is a reasonable trade-off
+        for exploration, 5000+ for publication-grade estimates.
+    conf_level : float, default 0.95
+        Confidence level for trimming extreme bootstrap draws.
+    seed : int, optional
+        Random seed for reproducible bootstrap standard errors.
+    swap : bool, default True
+        If True, the decomposition is computed as group 1 minus group 0
+        (group 1 is the higher value of the binary ``by`` column). Setting
+        ``swap=False`` reverses this.
+
+    Returns
+    -------
+    OaxacaResult
+        Immutable result object with ``.explained``, ``.unexplained``,
+        ``.total_gap``, and ``.tidy()``.
+
+    Examples
+    --------
+    >>> import open_econs as oe
+    >>> result = oe.oaxaca("income ~ education + age + female", data=df, by="female")
+    >>> result.tidy()
+    """
+    if by not in data.columns:
+        raise errors.missing_column_error(by, data.columns.tolist())
+
+    unique_vals = data[by].dropna().unique()
+    if len(unique_vals) != 2:
+        raise errors.non_binary_error(by, unique_vals)
+
+    call = _capture_call(
+        formula=formula, by=by, decomposition_type=decomposition_type,
+        std=std, bootstrap_n=bootstrap_n, conf_level=conf_level, seed=seed,
+        swap=swap,
+    )
+
+    yy, XX = parse_formula(formula, data)
+    y_arr = yy.values.ravel()
+
+    if by in XX.columns:
+        bifurcate_idx = list(XX.columns).index(by)
+    else:
+        patterns = [f"C({by})[", f"{by}["]
+        encoded_cols = [
+            c for c in XX.columns
+            if any(c.startswith(p) for p in patterns)
+        ]
+        if encoded_cols:
+            from pandas import get_dummies
+            dummies = get_dummies(data.loc[XX.index, by], prefix=by, drop_first=True)
+            if len(dummies.columns) == 1:
+                XX = XX.copy()
+                for c in encoded_cols:
+                    XX.drop(columns=[c], inplace=True)
+                cname = str(by)
+                XX.insert(XX.shape[1], cname, dummies.iloc[:, 0].values.astype(float))
+                bifurcate_idx = list(XX.columns).index(cname)
+            else:
+                raise ValueError(
+                    f"The 'by' column '{by}' has {len(dummies.columns) + 1} unique "
+                    f"values (must be exactly 2 for Oaxaca decomposition)."
+                )
+        else:
+            raise ValueError(
+                f"Column '{by}' not found in the design matrix. Ensure '{by}' "
+                f"appears on the RHS of the formula (e.g. '{formula}'). "
+                f"Available columns in design matrix: {list(XX.columns)}"
+            )
+    hasconst = any("Intercept" in c for c in XX.columns)
+
+    if seed is not None:
+        np.random.seed(seed)
+
+    model = OaxacaBlinder(
+        y_arr,
+        XX.values,
+        bifurcate=bifurcate_idx,
+        hasconst=hasconst,
+        swap=swap,
+    )
+
+    if decomposition_type == "two-fold":
+        stats_result = model.two_fold(std=std, n=bootstrap_n, conf=conf_level)
+        explained = float(stats_result.params[1])
+        unexplained = float(stats_result.params[0])
+        gap_val = float(stats_result.params[2])
+        interaction = None
+    elif decomposition_type == "three-fold":
+        stats_result = model.three_fold(std=std, n=bootstrap_n, conf=conf_level)
+        endowment = float(stats_result.params[0])
+        coefficients = float(stats_result.params[1])
+        interaction = float(stats_result.params[2])
+        gap_val = float(stats_result.params[3])
+        explained = endowment
+        unexplained = coefficients
+    else:
+        raise ValueError(
+            f"Unknown decomposition_type '{decomposition_type}'. "
+            f"Use 'two-fold' or 'three-fold'."
+        )
+
+    var_names = [c for c in XX.columns if c != by]
+    f_params = model._f_model.params
+    s_params = model._s_model.params
+    f_mean = model.exog_f_mean
+    s_mean = model.exog_s_mean
+
+    if decomposition_type == "two-fold":
+        ref_params = model.t_params
+        endow_vec = (f_mean - s_mean) * ref_params
+        unexpl_vec = f_mean * (f_params - ref_params) + s_mean * (ref_params - s_params)
+        var_detail = pd.DataFrame({
+            "Variable": var_names,
+            "Explained": endow_vec[:len(var_names)],
+            "Unexplained": unexpl_vec[:len(var_names)],
+        })
+    else:
+        endow_vec = (f_mean - s_mean) * s_params
+        coeff_vec = s_mean * (f_params - s_params)
+        inter_vec = (f_mean - s_mean) * (f_params - s_params)
+        var_detail = pd.DataFrame({
+            "Variable": var_names,
+            "Endowment": endow_vec[:len(var_names)],
+            "Coefficients": coeff_vec[:len(var_names)],
+            "Interaction": inter_vec[:len(var_names)],
+        })
+
+    unique_vals_sorted = sorted(data[by].dropna().unique(), key=str)
+    idx_map = {float(i): str(v) for i, v in enumerate(unique_vals_sorted)}
+    group_labels = (idx_map.get(model.bi[0], str(model.bi[0])),
+                    idx_map.get(model.bi[1], str(model.bi[1])))
+
+    std_series: pd.Series | None = None
+    if std and stats_result.std:
+        if decomposition_type == "two-fold":
+            labels = ["Unexplained", "Explained"]
+        else:
+            labels = ["Endowment", "Coefficients", "Interaction"]
+        std_series = pd.Series(stats_result.std, index=labels, name="std_err")
+
+    return OaxacaResult(
+        formula=formula,
+        nobs=int(len(yy)),
+        n_params=XX.shape[1],
+        cov_type="nonrobust",
+        explained=explained,
+        unexplained=unexplained,
+        interaction=interaction,
+        total_gap=gap_val,
+        decomposition_type=decomposition_type,
+        by_groups=group_labels,
+        std=std_series,
+        call=call,
+        variable_detail=var_detail,
+    )
+
+
+def _capture_call(**kwargs: Any) -> dict[str, Any]:
+    kwargs["timestamp"] = str(datetime.now())
+    kwargs["package_version"] = __version__
+    return kwargs

open_econs/models/linear/ols.py

@@ -0,0 +1,238 @@
+from datetime import datetime
+from typing import Any
+
+import numpy as np
+import pandas as pd
+import statsmodels.api as sm
+
+from open_econs._version import __version__
+from open_econs._internal import errors
+from open_econs.core.results import OLSResult
+
+
+def ols(
+    formula: str,
+    data: pd.DataFrame,
+    cluster: str | None = None,
+    cov_type: str = "HC2",
+    weights: str | np.ndarray | pd.Series | None = None,
+) -> OLSResult:
+    """Estimate an ordinary least-squares or weighted least-squares regression.
+
+    Parameters
+    ----------
+    formula : str
+        Two-sided formula string, e.g. ``"income ~ education + age"``.
+    data : pd.DataFrame
+        Data containing all variables referenced in *formula*.
+    cluster : str, optional
+        Column name for cluster-robust standard errors.
+    cov_type : str, default "HC2"
+        Covariance estimator type. Common choices: ``"HC2"`` (default,
+        matches modern Stata ``reg, robust``; changed from HC1 in v0.2.0),
+        ``"HC1`` (classic White SE), ``"HC0"``, ``"HC3"``, ``"nonrobust"``.
+        Ignored when *cluster* is provided (cluster-robust is used instead).
+    weights : str or array-like, optional
+        Frequency/analytic weights for weighted least squares. If a string,
+        interpreted as a column name in *data*. If an array, must match the
+        number of rows in *data*.
+
+    Returns
+    -------
+    OLSResult
+        Immutable result object with named coefficient arrays.
+
+    Examples
+    --------
+    >>> import open_econs as oe
+    >>> result = oe.ols("income ~ education + age", data=df)
+    >>> result.tidy()
+    >>> result.coefficients["education"]
+    """
+    call = _capture_call(formula=formula, cluster=cluster, cov_type=cov_type, weights=weights)
+    rhs_formula = formula.split("~", 1)[1].strip()
+
+    from formulaic import Formula
+    try:
+        formula_obj = Formula(formula)
+        model_spec = formula_obj.get_model_matrix(data, na_action="drop")
+    except Exception as e:
+        msg = str(e)
+        if "not present in the dataset" in msg or "is not present" in msg:
+            import re as _re
+            m = _re.search(r"`(\w+)`", msg)
+            bad_col = m.group(1) if m else formula.split("~", 1)[1].strip()
+            raise errors.missing_column_error(bad_col, data.columns.tolist()) from e
+        raise
+    if hasattr(model_spec, "rhs"):
+        XX = model_spec.rhs
+        yy = model_spec.lhs
+    else:
+        from open_econs._internal.formula import parse_formula as _parse
+        yy, XX = _parse(formula, data)
+        model_spec = None
+
+    original_n = len(data)
+    dropped = original_n - len(yy)
+    vars_needed = {str(v) for v in formula_obj.required_variables}
+    cols_with_nas = sorted(v for v in vars_needed if v in data.columns and data[v].isna().any())
+    if dropped > 0:
+        from open_econs._internal.errors import rows_dropped_warning
+        import warnings as _w
+        _w.warn(rows_dropped_warning(dropped, original_n, cols_with_nas), RuntimeWarning, stacklevel=3)
+
+    if len(yy) == 0:
+        from open_econs._internal.errors import empty_data_error
+        raise empty_data_error(original_n, dropped, cols_with_nas)
+
+    y_arr = yy.values.ravel()
+
+    if model_spec is not None:
+        stored_spec = model_spec.model_spec.rhs
+    else:
+        stored_spec = None
+
+    condition_number = _check_collinearity(XX)
+
+    if weights is not None:
+        if isinstance(weights, str):
+            if weights not in data.columns:
+                raise errors.missing_column_error(weights, data.columns.tolist())
+            w_arr = data.loc[XX.index, weights].values.astype(float)
+        else:
+            w_arr = np.asarray(weights, dtype=float)
+            if len(w_arr) != original_n:
+                raise ValueError(
+                    f"weights array length ({len(w_arr)}) does not match data rows ({original_n})"
+                )
+            w_arr = w_arr[XX.index]
+        if np.any(w_arr < 0):
+            raise ValueError("Weights must be non-negative.")
+        fitted = sm.WLS(y_arr, XX.values, weights=w_arr).fit(
+            cov_type="cluster" if cluster else cov_type,
+            cov_kwds={"groups": data.loc[XX.index, cluster]} if cluster else {},
+        )
+        cov_label = f"cluster({cluster})" if cluster else cov_type
+    else:
+        if cluster is not None:
+            if cluster not in data.columns:
+                raise errors.cluster_column_error(cluster, data.columns.tolist())
+            aligned_groups = data.loc[XX.index, cluster]
+            fitted = sm.OLS(y_arr, XX.values).fit(
+                cov_type="cluster",
+                cov_kwds={"groups": aligned_groups},
+            )
+            cov_label = f"cluster({cluster})"
+        else:
+            fitted = sm.OLS(y_arr, XX.values).fit(cov_type=cov_type)
+            cov_label = cov_type
+
+    coef_arr = fitted.params
+    se_arr = fitted.bse
+    t_arr = fitted.tvalues
+    p_arr = fitted.pvalues
+    conf_arr = fitted.conf_int()
+
+    conf_int = pd.DataFrame(
+        {"lower": conf_arr[:, 0], "upper": conf_arr[:, 1]},
+        index=XX.columns,
+    )
+
+    fitted_values = pd.Series(fitted.fittedvalues, index=XX.index, name="fitted")
+    residuals = pd.Series(fitted.resid, index=XX.index, name="residuals")
+
+    f_stat = _safe_fvalue(fitted)
+    f_pval = _safe_f_pvalue(fitted)
+
+    return OLSResult(
+        formula=formula,
+        rhs_formula=rhs_formula,
+        nobs=int(fitted.nobs),
+        df_resid=int(fitted.df_resid),
+        df_model=int(fitted.df_model),
+        cov_type=cov_label,
+        coefficients=pd.Series(coef_arr, index=XX.columns),
+        std_errors=pd.Series(se_arr, index=XX.columns),
+        t_stats=pd.Series(t_arr, index=XX.columns),
+        p_values=pd.Series(p_arr, index=XX.columns),
+        conf_int=conf_int,
+        r_squared=float(fitted.rsquared),
+        adj_r_squared=float(fitted.rsquared_adj),
+        f_statistic=f_stat,
+        f_p_value=f_pval,
+        rsd=float(np.sqrt(fitted.mse_resid)),
+        llf=_safe_llf(fitted),
+        aic=_safe_aic(fitted),
+        bic=_safe_bic(fitted),
+        fitted=fitted_values,
+        residuals=residuals,
+        call=call,
+        model_spec=stored_spec,
+        condition_number=condition_number,
+        _X=XX,
+        _sm_fit=fitted,
+    )
+
+
+reg = ols
+
+
+def _capture_call(**kwargs: Any) -> dict[str, Any]:
+    kwargs["timestamp"] = str(datetime.now())
+    kwargs["package_version"] = __version__
+    return kwargs
+
+
+def _safe_fvalue(fitted: Any) -> float:
+    try:
+        return float(fitted.fvalue)
+    except (ValueError, AttributeError):
+        return float("nan")
+
+
+def _safe_f_pvalue(fitted: Any) -> float:
+    try:
+        return float(fitted.f_pvalue)
+    except (ValueError, AttributeError):
+        return float("nan")
+
+
+def _safe_llf(fitted: Any) -> float:
+    try:
+        return float(fitted.llf)
+    except (ValueError, AttributeError):
+        return float("nan")
+
+
+def _safe_aic(fitted: Any) -> float:
+    try:
+        return float(fitted.aic)
+    except (ValueError, AttributeError):
+        return float("nan")
+
+
+def _safe_bic(fitted: Any) -> float:
+    try:
+        return float(fitted.bic)
+    except (ValueError, AttributeError):
+        return float("nan")
+
+
+def _check_collinearity(XX: pd.DataFrame) -> float:
+    from numpy.linalg import cond, matrix_rank
+    X_vals = XX.values
+    n_params = X_vals.shape[1]
+    rank = matrix_rank(X_vals)
+    if rank < n_params:
+        raise errors.singular_matrix_error()
+    cn = float(cond(X_vals))
+    if cn > 30:
+        import warnings as _w
+        _w.warn(
+            f"Design matrix is near-singular (condition number = {cn:.2e}). "
+            "Belsley, Kuh & Welsch (1980) recommend caution above 30. "
+            "Consider removing collinear predictors.",
+            RuntimeWarning,
+            stacklevel=3,
+        )
+    return cn

open_econs-0.3.0.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: open-econs
+Version: 0.3.0
+Summary: The scikit-learn of empirical economics.
+Project-URL: Homepage, https://github.com/anomalyco/open-econs
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: formulaic>=1.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: scipy>=1.11
+Requires-Dist: statsmodels>=0.14
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: mypy>=1.8; extra == 'lint'
+Requires-Dist: ruff>=0.3; extra == 'lint'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == 'plot'

open_econs-0.3.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+open_econs/__init__.py,sha256=7RtocgpChkCnZS3yRtD7Ny2YfHTTQXmBr5iEvA-BN7g,223
+open_econs/_version.py,sha256=5mDtfU2t04ATmg92S5B-scUcdjCy1ZBq620y3GmpdtQ,21
+open_econs/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+open_econs/_internal/errors.py,sha256=zMV2x_t_tBav_L9cqYv08hIFSjqa27Ww0Te846sJCO8,1606
+open_econs/_internal/formula.py,sha256=U8hxWczkJLZHBtTSjTtkE7NJE_BxXsBj4EO3Fi80tO0,1378
+open_econs/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+open_econs/core/base.py,sha256=AmTGlEoyZ5lzNQlo6GuE_GslnX95mo_hRXucPy9xGI4,3144
+open_econs/core/context.py,sha256=6-PycFukd8hGjwK8_g3Mle9d14mVLKta4HK69qONxJ8,1411
+open_econs/core/results.py,sha256=BLzIYTU6Mpcrc-ipNfqIa64a43VD67FzT_hPoAuuorE,13478
+open_econs/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+open_econs/models/decomposition/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+open_econs/models/decomposition/oaxaca.py,sha256=9QEVoKdsw2Lbbv6QswPJUfEuo6oe27FEGmHZ6GF8rS8,7411
+open_econs/models/linear/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+open_econs/models/linear/ols.py,sha256=Jgjs3u0TlFpBnKaAavLKXB_wTdGQOpmt8gubDs0cLbQ,7851
+open_econs-0.3.0.dist-info/METADATA,sha256=d6lJf-n8d3pQtSPa4pHa5L_vJxPsBDjo9IINfg8EOus,683
+open_econs-0.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+open_econs-0.3.0.dist-info/licenses/LICENSE,sha256=G29KdzB-lU2HHhxZdhrNvJR_R1yW-NjteextQhiTefU,1065
+open_econs-0.3.0.dist-info/RECORD,,

open_econs-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

open_econs-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.