panelbox 0.2.0__py3-none-any.whl

panelbox/validation/specification/chow.py

@@ -0,0 +1,273 @@
+"""
+Chow test for structural break in panel data models.
+
+References
+----------
+Chow, G. C. (1960). Tests of Equality Between Sets of Coefficients in
+Two Linear Regressions. Econometrica, 28(3), 591-605.
+
+Baltagi, B. H. (2013). Econometric Analysis of Panel Data (5th ed.).
+Wiley, Chapter 4.
+"""
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from panelbox.validation.base import ValidationTest, ValidationTestResult
+
+
+class ChowTest(ValidationTest):
+    """
+    Chow test for structural break in panel models.
+
+    Tests the null hypothesis of parameter stability (no structural break)
+    against the alternative that parameters differ across subperiods.
+
+    H0: beta_1 = beta_2 (parameters are stable)
+    H1: beta_1 ≠ beta_2 (structural break exists)
+
+    The test compares the fit of:
+    - Unrestricted model: separate parameters for each subperiod
+    - Restricted model: same parameters for all periods
+
+    Notes
+    -----
+    The test statistic is:
+    F = [(SSR_r - SSR_u) / k] / [SSR_u / (N - 2k)]
+
+    where:
+    - SSR_r = residual sum of squares (restricted model)
+    - SSR_u = residual sum of squares (unrestricted model)
+    - k = number of parameters
+    - N = total number of observations
+
+    For panel data, we use pooled estimation with cluster-robust inference.
+
+    Examples
+    --------
+    >>> from panelbox.models.static.pooled_ols import PooledOLS
+    >>> model = PooledOLS("y ~ x1 + x2", data, "entity", "time")
+    >>> results = model.fit()
+    >>>
+    >>> from panelbox.validation.specification.chow import ChowTest
+    >>> test = ChowTest(results)
+    >>> # Test for break at time period 5
+    >>> result = test.run(break_point=5)
+    >>> print(result)
+    """
+
+    def __init__(self, results: 'PanelResults'):
+        """
+        Initialize Chow test.
+
+        Parameters
+        ----------
+        results : PanelResults
+            Results from panel model estimation
+        """
+        super().__init__(results)
+
+    def run(self, break_point=None, alpha: float = 0.05) -> ValidationTestResult:
+        """
+        Run Chow test for structural break.
+
+        Parameters
+        ----------
+        break_point : int or float, optional
+            Time period at which to test for structural break.
+            If None, uses the median time period.
+            Can be specified as:
+            - Integer: exact time period
+            - Float between 0 and 1: fraction of sample (e.g., 0.5 for midpoint)
+        alpha : float, default=0.05
+            Significance level
+
+        Returns
+        -------
+        ValidationTestResult
+            Test results
+
+        Raises
+        ------
+        ValueError
+            If break_point is invalid or data is not available
+
+        Notes
+        -----
+        The test requires at least 2*k observations in each subperiod,
+        where k is the number of parameters.
+        """
+        # Get data
+        data, formula, entity_col, time_col, var_names = self._get_data_full()
+
+        if data is None or formula is None:
+            raise ValueError(
+                "Data and formula required for Chow test. "
+                "Ensure the model was estimated with a formula."
+            )
+
+        # Get unique time periods (sorted)
+        time_periods = sorted(data[time_col].unique())
+        n_periods = len(time_periods)
+
+        # Determine break point
+        if break_point is None:
+            # Use median
+            break_idx = n_periods // 2
+            break_time = time_periods[break_idx]
+        elif isinstance(break_point, float) and 0 < break_point < 1:
+            # Fraction of sample
+            break_idx = int(n_periods * break_point)
+            break_time = time_periods[break_idx]
+        elif isinstance(break_point, (int, np.integer)):
+            # Exact time period
+            if break_point not in time_periods:
+                raise ValueError(
+                    f"Break point {break_point} not found in time periods. "
+                    f"Available: {time_periods}"
+                )
+            break_time = break_point
+            break_idx = time_periods.index(break_time)
+        else:
+            raise ValueError(
+                "break_point must be None, int (time period), "
+                "or float between 0 and 1 (fraction)"
+            )
+
+        # Create subperiod indicator
+        data_aug = data.copy()
+        data_aug['period_1'] = (data_aug[time_col] < break_time).astype(int)
+        data_aug['period_2'] = (data_aug[time_col] >= break_time).astype(int)
+
+        # Check sample sizes
+        n1 = data_aug['period_1'].sum()
+        n2 = data_aug['period_2'].sum()
+        k = len(var_names) + 1  # +1 for intercept
+
+        if n1 < 2 * k or n2 < 2 * k:
+            raise ValueError(
+                f"Insufficient observations in subperiods. "
+                f"Need at least {2*k} in each, got n1={n1}, n2={n2}"
+            )
+
+        # Estimate restricted model (pooled)
+        try:
+            from panelbox.models.static.pooled_ols import PooledOLS
+
+            model_restricted = PooledOLS(formula, data_aug, entity_col, time_col)
+            results_restricted = model_restricted.fit()
+            ssr_restricted = np.sum(results_restricted.resid ** 2)
+
+        except Exception as e:
+            raise ValueError(f"Failed to estimate restricted model: {e}")
+
+        # Estimate unrestricted model (separate for each subperiod)
+        # Model 1: period < break_time
+        data_period1 = data_aug[data_aug['period_1'] == 1].copy()
+        model_1 = PooledOLS(formula, data_period1, entity_col, time_col)
+        results_1 = model_1.fit()
+        ssr_1 = np.sum(results_1.resid ** 2)
+
+        # Model 2: period >= break_time
+        data_period2 = data_aug[data_aug['period_2'] == 1].copy()
+        model_2 = PooledOLS(formula, data_period2, entity_col, time_col)
+        results_2 = model_2.fit()
+        ssr_2 = np.sum(results_2.resid ** 2)
+
+        # Unrestricted SSR (sum of both periods)
+        ssr_unrestricted = ssr_1 + ssr_2
+
+        # Chow F-statistic
+        # F = [(SSR_r - SSR_u) / k] / [SSR_u / (N - 2k)]
+        N = len(data_aug)
+        numerator = (ssr_restricted - ssr_unrestricted) / k
+        denominator = ssr_unrestricted / (N - 2 * k)
+
+        if denominator == 0:
+            raise ValueError("Denominator is zero. Perfect fit in subperiods.")
+
+        f_stat = numerator / denominator
+
+        # Degrees of freedom
+        df_num = k
+        df_denom = N - 2 * k
+
+        # P-value
+        pvalue = 1 - stats.f.cdf(f_stat, df_num, df_denom)
+
+        # Metadata
+        metadata = {
+            'break_point': break_time,
+            'break_index': break_idx,
+            'n_periods_total': n_periods,
+            'n_obs_period1': n1,
+            'n_obs_period2': n2,
+            'n_obs_total': N,
+            'ssr_restricted': float(ssr_restricted),
+            'ssr_unrestricted': float(ssr_unrestricted),
+            'ssr_period1': float(ssr_1),
+            'ssr_period2': float(ssr_2),
+            'k_parameters': k,
+            'coefficients_period1': results_1.params.to_dict(),
+            'coefficients_period2': results_2.params.to_dict()
+        }
+
+        result = ValidationTestResult(
+            test_name="Chow Test for Structural Break",
+            statistic=f_stat,
+            pvalue=pvalue,
+            null_hypothesis="No structural break (parameters stable)",
+            alternative_hypothesis=f"Structural break at t={break_time}",
+            alpha=alpha,
+            df=(df_num, df_denom),
+            metadata=metadata
+        )
+
+        return result
+
+    def _get_data_full(self):
+        """
+        Get full data including DataFrame, formula, and variable names.
+
+        Returns
+        -------
+        tuple
+            (data, formula, entity_col, time_col, var_names) or
+            (None, None, None, None, None) if not available
+        """
+        if not hasattr(self.results, '_model'):
+            return None, None, None, None, None
+
+        model = self.results._model
+
+        if not (hasattr(model, 'formula_parser') and hasattr(model, 'data')):
+            return None, None, None, None, None
+
+        try:
+            data = model.data.data.copy()
+            entity_col = model.data.entity_col
+            time_col = model.data.time_col
+
+            if hasattr(model, 'formula'):
+                formula = model.formula
+            else:
+                return None, None, None, None, None
+
+            if hasattr(model.formula_parser, 'rhs_terms'):
+                var_names = [
+                    term for term in model.formula_parser.rhs_terms
+                    if term.lower() not in ['intercept', '1']
+                ]
+            else:
+                rhs = formula.split('~')[1].strip()
+                terms = [t.strip() for t in rhs.split('+')]
+                var_names = [
+                    t for t in terms
+                    if t.lower() not in ['1', 'intercept', '']
+                ]
+
+            return data, formula, entity_col, time_col, var_names
+
+        except Exception:
+            return None, None, None, None, None

panelbox/validation/specification/hausman.py

@@ -0,0 +1,264 @@
+"""
+Hausman specification test for panel data.
+
+This module provides the Hausman test for choosing between Fixed Effects
+and Random Effects models.
+"""
+
+from typing import Optional
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from panelbox.core.results import PanelResults
+
+
+class HausmanTestResult:
+    """
+    Container for Hausman test results.
+
+    Attributes
+    ----------
+    statistic : float
+        Chi-squared test statistic
+    pvalue : float
+        P-value
+    df : int
+        Degrees of freedom
+    conclusion : str
+        Interpretation of test result
+    fe_params : pd.Series
+        Fixed effects coefficients
+    re_params : pd.Series
+        Random effects coefficients
+    diff : pd.Series
+        Difference in coefficients (FE - RE)
+    """
+
+    def __init__(
+        self,
+        statistic: float,
+        pvalue: float,
+        df: int,
+        fe_params: pd.Series,
+        re_params: pd.Series,
+        diff: pd.Series,
+        alpha: float = 0.05
+    ):
+        self.statistic = statistic
+        self.pvalue = pvalue
+        self.df = df
+        self.fe_params = fe_params
+        self.re_params = re_params
+        self.diff = diff
+        self.alpha = alpha
+
+        # Determine conclusion
+        if pvalue < alpha:
+            self.conclusion = (
+                f"Reject H0 at {alpha*100:.0f}% level. "
+                "Use Fixed Effects (RE is inconsistent)."
+            )
+            self.recommendation = "Fixed Effects"
+        else:
+            self.conclusion = (
+                f"Fail to reject H0 at {alpha*100:.0f}% level. "
+                "Random Effects is consistent and efficient."
+            )
+            self.recommendation = "Random Effects"
+
+    def __str__(self) -> str:
+        """String representation."""
+        return self.summary()
+
+    def __repr__(self) -> str:
+        """Repr."""
+        return f"HausmanTestResult(statistic={self.statistic:.3f}, pvalue={self.pvalue:.4f}, df={self.df})"
+
+    def summary(self) -> str:
+        """
+        Generate formatted summary.
+
+        Returns
+        -------
+        str
+            Formatted test results
+        """
+        lines = []
+        lines.append("=" * 70)
+        lines.append("HAUSMAN SPECIFICATION TEST")
+        lines.append("=" * 70)
+        lines.append("")
+        lines.append("H0: Random Effects is consistent (and efficient)")
+        lines.append("H1: Random Effects is inconsistent (use Fixed Effects)")
+        lines.append("")
+        lines.append("-" * 70)
+        lines.append(f"{'Test Statistic (Chi2)':<30} {self.statistic:>15.4f}")
+        lines.append(f"{'P-value':<30} {self.pvalue:>15.4f}")
+        lines.append(f"{'Degrees of Freedom':<30} {self.df:>15}")
+        lines.append("-" * 70)
+        lines.append("")
+        lines.append(f"Conclusion: {self.conclusion}")
+        lines.append(f"Recommendation: {self.recommendation}")
+        lines.append("")
+
+        # Coefficient comparison table
+        lines.append("=" * 70)
+        lines.append("COEFFICIENT COMPARISON")
+        lines.append("=" * 70)
+        lines.append(f"{'Variable':<15} {'Fixed Effects':<15} {'Random Effects':<15} {'Difference':<15}")
+        lines.append("-" * 70)
+
+        for var in self.fe_params.index:
+            fe_coef = self.fe_params[var]
+            re_coef = self.re_params[var]
+            diff_coef = self.diff[var]
+
+            lines.append(
+                f"{var:<15} {fe_coef:>14.4f} {re_coef:>14.4f} {diff_coef:>14.4f}"
+            )
+
+        lines.append("=" * 70)
+        lines.append("")
+
+        return "\n".join(lines)
+
+
+class HausmanTest:
+    """
+    Hausman specification test for panel data.
+
+    Tests the null hypothesis that the Random Effects estimator is consistent
+    (and efficient) against the alternative that it is inconsistent.
+
+    The test compares Fixed Effects (always consistent under standard assumptions)
+    with Random Effects (consistent only if E[u_i | X_it] = 0).
+
+    Parameters
+    ----------
+    fe_results : PanelResults
+        Results from Fixed Effects estimation
+    re_results : PanelResults
+        Results from Random Effects estimation
+
+    Examples
+    --------
+    >>> import panelbox as pb
+    >>>
+    >>> # Estimate both models
+    >>> fe = pb.FixedEffects("y ~ x1 + x2", data, "firm", "year")
+    >>> fe_results = fe.fit()
+    >>>
+    >>> re = pb.RandomEffects("y ~ x1 + x2", data, "firm", "year")
+    >>> re_results = re.fit()
+    >>>
+    >>> # Run Hausman test
+    >>> hausman = pb.HausmanTest(fe_results, re_results)
+    >>> result = hausman.run()
+    >>> print(result)
+    >>>
+    >>> # Use result
+    >>> if result.recommendation == "Fixed Effects":
+    ...     final_results = fe_results
+    >>> else:
+    ...     final_results = re_results
+    """
+
+    def __init__(
+        self,
+        fe_results: PanelResults,
+        re_results: PanelResults
+    ):
+        if fe_results.model_type not in ['Fixed Effects', 'Fixed Effects (Two-Way)', 'Fixed Effects (Time)']:
+            raise ValueError("First argument must be Fixed Effects results")
+
+        if re_results.model_type not in ['Random Effects (GLS)', 'Random Effects']:
+            raise ValueError("Second argument must be Random Effects results")
+
+        self.fe_results = fe_results
+        self.re_results = re_results
+
+        # Find common coefficients (exclude Intercept for FE, keep for RE)
+        # FE doesn't have intercept, RE does
+        fe_vars = set(fe_results.params.index)
+        re_vars = set(re_results.params.index) - {'Intercept'}  # Exclude intercept from comparison
+
+        self.common_vars = sorted(fe_vars & re_vars)
+
+        if len(self.common_vars) == 0:
+            raise ValueError("No common variables found between FE and RE models")
+
+    def run(self, alpha: float = 0.05) -> HausmanTestResult:
+        """
+        Run the Hausman test.
+
+        Parameters
+        ----------
+        alpha : float, default=0.05
+            Significance level for test
+
+        Returns
+        -------
+        HausmanTestResult
+            Test results
+
+        Notes
+        -----
+        The Hausman test statistic is:
+
+            H = (b_FE - b_RE)' [Var(b_FE) - Var(b_RE)]^{-1} (b_FE - b_RE)
+
+        which follows a chi-squared distribution with K degrees of freedom,
+        where K is the number of coefficients being tested.
+
+        Examples
+        --------
+        >>> result = hausman.run(alpha=0.05)
+        >>> print(f"Chi2 statistic: {result.statistic:.3f}")
+        >>> print(f"P-value: {result.pvalue:.4f}")
+        >>> print(f"Recommendation: {result.recommendation}")
+        """
+        # Extract coefficients for common variables
+        beta_fe = self.fe_results.params[self.common_vars].values
+        beta_re = self.re_results.params[self.common_vars].values
+
+        # Difference in coefficients
+        diff = beta_fe - beta_re
+
+        # Extract covariance matrices
+        vcov_fe = self.fe_results.cov_params.loc[self.common_vars, self.common_vars].values
+        vcov_re = self.re_results.cov_params.loc[self.common_vars, self.common_vars].values
+
+        # Variance of difference: Var(b_FE - b_RE) = Var(b_FE) - Var(b_RE)
+        # Under H0, RE is efficient, so this is the correct variance
+        var_diff = vcov_fe - vcov_re
+
+        # Check if var_diff is positive definite
+        # If not, use the generalized inverse
+        try:
+            var_diff_inv = np.linalg.inv(var_diff)
+        except np.linalg.LinAlgError:
+            # Matrix is singular, use pseudo-inverse
+            var_diff_inv = np.linalg.pinv(var_diff)
+
+        # Hausman statistic: (b_FE - b_RE)' [Var(diff)]^{-1} (b_FE - b_RE)
+        statistic = float(diff.T @ var_diff_inv @ diff)
+
+        # Degrees of freedom
+        df = len(self.common_vars)
+
+        # P-value from chi-squared distribution
+        pvalue = 1 - stats.chi2.cdf(statistic, df)
+
+        # Create result object
+        result = HausmanTestResult(
+            statistic=statistic,
+            pvalue=pvalue,
+            df=df,
+            fe_params=self.fe_results.params[self.common_vars],
+            re_params=self.re_results.params[self.common_vars],
+            diff=pd.Series(diff, index=self.common_vars),
+            alpha=alpha
+        )
+
+        return result