panelbox 0.2.0__py3-none-any.whl

panelbox/validation/heteroskedasticity/__init__.py

@@ -0,0 +1,13 @@
+"""
+Heteroskedasticity tests for panel models.
+"""
+
+from panelbox.validation.heteroskedasticity.modified_wald import ModifiedWaldTest
+from panelbox.validation.heteroskedasticity.breusch_pagan import BreuschPaganTest
+from panelbox.validation.heteroskedasticity.white import WhiteTest
+
+__all__ = [
+    'ModifiedWaldTest',
+    'BreuschPaganTest',
+    'WhiteTest',
+]

panelbox/validation/heteroskedasticity/breusch_pagan.py

@@ -0,0 +1,222 @@
+"""
+Breusch-Pagan LM test for heteroskedasticity in panel data.
+
+References
+----------
+Breusch, T. S., & Pagan, A. R. (1979). A simple test for heteroscedasticity
+and random coefficient variation. Econometrica, 47(5), 1287-1294.
+
+Greene, W. H. (2018). Econometric Analysis (8th ed.). Pearson.
+"""
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from panelbox.validation.base import ValidationTest, ValidationTestResult
+
+
+class BreuschPaganTest(ValidationTest):
+    """
+    Breusch-Pagan LM test for heteroskedasticity.
+    
+    Tests the null hypothesis that the error variance is constant
+    (homoskedasticity) against the alternative that the variance
+    is a function of the regressors.
+    
+    H0: sigma²_i = sigma² (homoskedasticity)
+    H1: sigma²_i = h(X_i) (heteroskedasticity)
+    
+    The test regresses squared residuals on the original regressors
+    and tests if the coefficients are jointly zero using an LM statistic.
+    
+    Notes
+    -----
+    The test statistic is n*R² from the auxiliary regression, which
+    follows a chi-squared distribution with k degrees of freedom
+    under the null hypothesis, where k is the number of regressors
+    (excluding the constant).
+    
+    Examples
+    --------
+    >>> from panelbox.models.static.pooled_ols import PooledOLS
+    >>> model = PooledOLS("y ~ x1 + x2", data, "entity", "time")
+    >>> results = model.fit()
+    >>> 
+    >>> from panelbox.validation.heteroskedasticity.breusch_pagan import BreuschPaganTest
+    >>> test = BreuschPaganTest(results)
+    >>> result = test.run()
+    >>> print(result)
+    """
+    
+    def __init__(self, results: 'PanelResults'):
+        """
+        Initialize Breusch-Pagan test.
+        
+        Parameters
+        ----------
+        results : PanelResults
+            Results from panel model estimation
+        """
+        super().__init__(results)
+        
+        # Store original design matrix if available
+        # We'll need the original X matrix for the auxiliary regression
+        self._X = None
+        if hasattr(results, '_model'):
+            if hasattr(results._model, '_X_orig'):
+                self._X = results._model._X_orig
+    
+    def run(self, alpha: float = 0.05) -> ValidationTestResult:
+        """
+        Run Breusch-Pagan LM test for heteroskedasticity.
+        
+        Parameters
+        ----------
+        alpha : float, default=0.05
+            Significance level
+        
+        Returns
+        -------
+        ValidationTestResult
+            Test results
+        
+        Raises
+        ------
+        ValueError
+            If design matrix is not available
+        
+        Notes
+        -----
+        The test procedure:
+        1. Estimate the original model and obtain residuals e
+        2. Compute squared residuals e²
+        3. Regress e² on the original regressors X
+        4. Compute LM statistic = n*R² from this auxiliary regression
+        5. Compare to chi-squared(k) distribution
+        """
+        # Get squared residuals
+        resid_sq = self.resid ** 2
+        
+        # We need the design matrix X
+        # Try to get it from the model or reconstruct it
+        X = self._get_design_matrix()
+        
+        if X is None:
+            raise ValueError(
+                "Design matrix not available. "
+                "Breusch-Pagan test requires access to the original regressors."
+            )
+        
+        n = len(resid_sq)
+        
+        # Auxiliary regression: resid² on X
+        # OLS: beta_aux = (X'X)^{-1} X'resid²
+        try:
+            XtX = X.T @ X
+            Xty = X.T @ resid_sq
+            beta_aux = np.linalg.solve(XtX, Xty)
+        except np.linalg.LinAlgError:
+            # Singular matrix, use pseudo-inverse
+            beta_aux = np.linalg.lstsq(X, resid_sq, rcond=None)[0]
+
+        # Fitted values from auxiliary regression
+        fitted_aux = X @ beta_aux
+
+        # R² from auxiliary regression using explained sum of squares
+        # This is more numerically stable than 1 - SSR/SST
+        mean_resid_sq = np.mean(resid_sq)
+        SST = np.sum((resid_sq - mean_resid_sq) ** 2)
+        SSE = np.sum((fitted_aux - mean_resid_sq) ** 2)
+
+        # R² = SSE/SST (explained variation / total variation)
+        if SST > 0:
+            R2_aux = SSE / SST
+        else:
+            R2_aux = 0.0
+
+        # Ensure R² is in [0, 1]
+        # Due to numerical errors, R² might be slightly negative or > 1
+        R2_aux = np.clip(R2_aux, 0.0, 1.0)
+
+        # LM statistic = n * R²
+        # This must be non-negative
+        lm_stat = n * R2_aux
+
+        # Sanity check: LM statistic must be >= 0
+        if lm_stat < 0:
+            # This should never happen, but if it does, set to 0
+            lm_stat = 0.0
+
+        # Degrees of freedom = number of regressors (excluding constant)
+        k = X.shape[1]
+
+        # Check if X has a constant column (all 1s or all same value)
+        # Check first and last columns as constant might be anywhere
+        has_constant = False
+        for col_idx in range(k):
+            col = X[:, col_idx]
+            if np.allclose(col, col[0]):
+                has_constant = True
+                break
+
+        if has_constant:
+            df = k - 1
+        else:
+            df = k
+
+        if df <= 0:
+            df = 1  # At least 1 df
+        
+        # P-value from chi-squared distribution
+        pvalue = 1 - stats.chi2.cdf(lm_stat, df)
+        
+        # Metadata
+        metadata = {
+            'R2_auxiliary': R2_aux,
+            'n_obs': n,
+            'n_regressors': k
+        }
+        
+        result = ValidationTestResult(
+            test_name="Breusch-Pagan LM Test for Heteroskedasticity",
+            statistic=lm_stat,
+            pvalue=pvalue,
+            null_hypothesis="Homoskedasticity (constant error variance)",
+            alternative_hypothesis="Heteroskedasticity (variance depends on regressors)",
+            alpha=alpha,
+            df=df,
+            metadata=metadata
+        )
+        
+        return result
+    
+    def _get_design_matrix(self) -> np.ndarray:
+        """
+        Get the design matrix X.
+        
+        Returns
+        -------
+        np.ndarray or None
+            Design matrix, or None if not available
+        """
+        # Try to get from stored _X
+        if self._X is not None:
+            return self._X
+        
+        # Try to get from model through results
+        if hasattr(self.results, '_model'):
+            model = self.results._model
+            
+            # Try to rebuild design matrices
+            if hasattr(model, 'formula_parser') and hasattr(model, 'data'):
+                try:
+                    _, X = model.formula_parser.build_design_matrices(
+                        model.data.data,
+                        return_type='array'
+                    )
+                    return X
+                except Exception:
+                    pass
+        
+        return None

panelbox/validation/heteroskedasticity/modified_wald.py

@@ -0,0 +1,172 @@
+"""
+Modified Wald test for groupwise heteroskedasticity in fixed effects models.
+
+References
+----------
+Greene, W. H. (2000). Econometric Analysis (4th ed.). Prentice Hall.
+
+Baum, C. F. (2001). Residual diagnostics for cross-section time series
+regression models. The Stata Journal, 1(1), 101-104.
+
+Stata command: xttest3
+"""
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from panelbox.validation.base import ValidationTest, ValidationTestResult
+
+
+class ModifiedWaldTest(ValidationTest):
+    """
+    Modified Wald test for groupwise heteroskedasticity.
+    
+    Tests the null hypothesis that the error variance is the same across
+    all cross-sectional units (entities) against the alternative that
+    variances differ across groups.
+    
+    H0: sigma²_1 = sigma²_2 = ... = sigma²_N
+    H1: sigma²_i ≠ sigma²_j for some i ≠ j
+    
+    This test is specifically designed for fixed effects panel models and
+    is robust to serial correlation.
+    
+    Notes
+    -----
+    The test statistic follows a chi-squared distribution with N degrees
+    of freedom under the null hypothesis, where N is the number of entities.
+    
+    This test requires that each entity has the same number of time periods
+    (balanced panel) or can be adapted for unbalanced panels.
+    
+    Examples
+    --------
+    >>> from panelbox.models.static.fixed_effects import FixedEffects
+    >>> fe = FixedEffects("y ~ x1 + x2", data, "entity", "time")
+    >>> results = fe.fit()
+    >>> 
+    >>> from panelbox.validation.heteroskedasticity.modified_wald import ModifiedWaldTest
+    >>> test = ModifiedWaldTest(results)
+    >>> result = test.run()
+    >>> print(result)
+    """
+    
+    def __init__(self, results: 'PanelResults'):
+        """
+        Initialize Modified Wald test.
+        
+        Parameters
+        ----------
+        results : PanelResults
+            Results from panel model estimation (preferably Fixed Effects)
+        """
+        super().__init__(results)
+        
+        # Check if model is suitable
+        if 'Fixed Effects' not in self.model_type:
+            import warnings
+            warnings.warn(
+                "Modified Wald test is designed for Fixed Effects models. "
+                f"Current model: {self.model_type}"
+            )
+    
+    def run(self, alpha: float = 0.05) -> ValidationTestResult:
+        """
+        Run Modified Wald test for groupwise heteroskedasticity.
+        
+        Parameters
+        ----------
+        alpha : float, default=0.05
+            Significance level
+        
+        Returns
+        -------
+        ValidationTestResult
+            Test results
+        
+        Raises
+        ------
+        ValueError
+            If required data indices are not available
+        """
+        # Get residuals with entity information
+        resid_df = self._prepare_residual_data()
+        
+        # Compute variance for each entity
+        entity_vars = resid_df.groupby('entity')['resid'].var()
+        entity_counts = resid_df.groupby('entity').size()
+        
+        n_entities = len(entity_vars)
+        
+        # Modified Wald statistic
+        # sum over i of: (T_i - 1) * ln(sigma²_pooled) - ln(sigma²_i)
+        # where sigma²_pooled is the pooled variance
+        
+        # Pooled variance (weighted by sample size)
+        total_resid_sq = np.sum((resid_df['resid'] ** 2).values)
+        total_obs = len(resid_df)
+        k = len(self.params)  # number of parameters
+        pooled_var = total_resid_sq / (total_obs - n_entities - k)
+        
+        # Wald statistic
+        wald_stat = 0.0
+        for entity in entity_vars.index:
+            T_i = entity_counts[entity]
+            sigma2_i = entity_vars[entity]
+            
+            if sigma2_i <= 0:
+                continue
+            
+            wald_stat += (T_i * np.log(pooled_var / sigma2_i))
+        
+        # Under H0, the statistic is approximately chi2(N)
+        df = n_entities
+        pvalue = 1 - stats.chi2.cdf(wald_stat, df)
+        
+        # Metadata
+        metadata = {
+            'n_entities': n_entities,
+            'pooled_variance': pooled_var,
+            'min_entity_var': entity_vars.min(),
+            'max_entity_var': entity_vars.max(),
+            'variance_ratio': entity_vars.max() / entity_vars.min() if entity_vars.min() > 0 else np.inf
+        }
+        
+        result = ValidationTestResult(
+            test_name="Modified Wald Test for Groupwise Heteroskedasticity",
+            statistic=wald_stat,
+            pvalue=pvalue,
+            null_hypothesis="Homoskedasticity (constant variance across entities)",
+            alternative_hypothesis="Groupwise heteroskedasticity present",
+            alpha=alpha,
+            df=df,
+            metadata=metadata
+        )
+        
+        return result
+    
+    def _prepare_residual_data(self) -> pd.DataFrame:
+        """
+        Prepare residual data with entity identifiers.
+        
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame with columns: entity, resid
+        """
+        if hasattr(self.results, 'entity_index'):
+            # Ensure resid is 1D
+            resid_flat = self.resid.ravel() if hasattr(self.resid, 'ravel') else self.resid
+
+            resid_df = pd.DataFrame({
+                'entity': self.results.entity_index,
+                'resid': resid_flat
+            })
+        else:
+            raise AttributeError(
+                "Results object must have 'entity_index' attribute. "
+                "Please ensure your model stores this during estimation."
+            )
+        
+        return resid_df

panelbox/validation/heteroskedasticity/white.py

@@ -0,0 +1,208 @@
+"""
+White test for heteroskedasticity in panel data.
+
+References
+----------
+White, H. (1980). A heteroskedasticity-consistent covariance matrix estimator
+and a direct test for heteroskedasticity. Econometrica, 48(4), 817-838.
+"""
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+from itertools import combinations_with_replacement
+
+from panelbox.validation.base import ValidationTest, ValidationTestResult
+
+
+class WhiteTest(ValidationTest):
+    """
+    White test for heteroskedasticity.
+    
+    Tests the null hypothesis of homoskedasticity against a general
+    alternative of heteroskedasticity. Unlike Breusch-Pagan, this test
+    does not assume a specific functional form for the heteroskedasticity.
+    
+    H0: sigma²_i = sigma² (homoskedasticity)
+    H1: sigma²_i depends on regressors in a general way
+    
+    The test regresses squared residuals on the original regressors,
+    their squares, and cross-products (interactions).
+    
+    Notes
+    -----
+    The test statistic is n*R² from the auxiliary regression, which
+    follows a chi-squared distribution under the null hypothesis.
+    
+    For models with many regressors, the test can have low power due
+    to the large number of terms in the auxiliary regression.
+    
+    Examples
+    --------
+    >>> from panelbox.models.static.pooled_ols import PooledOLS
+    >>> model = PooledOLS("y ~ x1 + x2", data, "entity", "time")
+    >>> results = model.fit()
+    >>> 
+    >>> from panelbox.validation.heteroskedasticity.white import WhiteTest
+    >>> test = WhiteTest(results)
+    >>> result = test.run()
+    >>> print(result)
+    """
+    
+    def __init__(self, results: 'PanelResults'):
+        """
+        Initialize White test.
+        
+        Parameters
+        ----------
+        results : PanelResults
+            Results from panel model estimation
+        """
+        super().__init__(results)
+        self._X = None
+        if hasattr(results, '_model'):
+            if hasattr(results._model, '_X_orig'):
+                self._X = results._model._X_orig
+    
+    def run(self, alpha: float = 0.05, cross_terms: bool = True) -> ValidationTestResult:
+        """
+        Run White test for heteroskedasticity.
+        
+        Parameters
+        ----------
+        alpha : float, default=0.05
+            Significance level
+        cross_terms : bool, default=True
+            If True, include cross-product terms in auxiliary regression
+            If False, only include squared terms (less computationally intensive)
+        
+        Returns
+        -------
+        ValidationTestResult
+            Test results
+        
+        Raises
+        ------
+        ValueError
+            If design matrix is not available
+        """
+        # Get squared residuals
+        resid_sq = self.resid ** 2
+        
+        # Get design matrix
+        X = self._get_design_matrix()
+        
+        if X is None:
+            raise ValueError(
+                "Design matrix not available. "
+                "White test requires access to the original regressors."
+            )
+        
+        n = len(resid_sq)
+        k_orig = X.shape[1]
+        
+        # Build augmented design matrix with squares and cross-products
+        # Remove constant column if present (first column all 1s)
+        if np.allclose(X[:, 0], 1.0):
+            X_vars = X[:, 1:]  # Exclude constant
+            has_constant = True
+        else:
+            X_vars = X
+            has_constant = False
+        
+        k_vars = X_vars.shape[1]
+        
+        # Create list of columns for auxiliary regression
+        aux_cols = [np.ones(n)] if has_constant or not has_constant else [np.ones(n)]
+        
+        # Add original variables
+        for j in range(k_vars):
+            aux_cols.append(X_vars[:, j])
+        
+        # Add squared terms
+        for j in range(k_vars):
+            aux_cols.append(X_vars[:, j] ** 2)
+        
+        # Add cross-product terms if requested
+        if cross_terms and k_vars > 1:
+            for i, j in combinations_with_replacement(range(k_vars), 2):
+                if i < j:  # Only upper triangle (avoid duplicates)
+                    aux_cols.append(X_vars[:, i] * X_vars[:, j])
+        
+        # Stack into matrix
+        X_aux = np.column_stack(aux_cols)
+        
+        # Auxiliary regression: resid² on X_aux
+        try:
+            XtX = X_aux.T @ X_aux
+            Xty = X_aux.T @ resid_sq
+            beta_aux = np.linalg.solve(XtX, Xty)
+        except np.linalg.LinAlgError:
+            beta_aux = np.linalg.lstsq(X_aux, resid_sq, rcond=None)[0]
+        
+        # Fitted values
+        fitted_aux = X_aux @ beta_aux
+        
+        # R²
+        mean_resid_sq = np.mean(resid_sq)
+        SST = np.sum((resid_sq - mean_resid_sq) ** 2)
+        SSR = np.sum((resid_sq - fitted_aux) ** 2)
+        
+        if SST > 0:
+            R2_aux = 1 - SSR / SST
+        else:
+            R2_aux = 0.0
+        
+        # LM statistic
+        lm_stat = n * R2_aux
+        
+        # Degrees of freedom = number of auxiliary regressors - 1 (for constant)
+        df = X_aux.shape[1] - 1
+        
+        if df <= 0:
+            df = 1
+        
+        # P-value
+        pvalue = 1 - stats.chi2.cdf(lm_stat, df)
+        
+        # Metadata
+        metadata = {
+            'R2_auxiliary': R2_aux,
+            'n_obs': n,
+            'n_original_regressors': k_orig,
+            'n_auxiliary_terms': X_aux.shape[1],
+            'includes_cross_terms': cross_terms
+        }
+        
+        result = ValidationTestResult(
+            test_name="White Test for Heteroskedasticity",
+            statistic=lm_stat,
+            pvalue=pvalue,
+            null_hypothesis="Homoskedasticity (constant error variance)",
+            alternative_hypothesis="General heteroskedasticity",
+            alpha=alpha,
+            df=df,
+            metadata=metadata
+        )
+        
+        return result
+    
+    def _get_design_matrix(self) -> np.ndarray:
+        """Get the design matrix X."""
+        if self._X is not None:
+            return self._X
+        
+        if hasattr(self.results, '_model'):
+            model = self.results._model
+            
+            if hasattr(model, 'formula_parser') and hasattr(model, 'data'):
+                try:
+                    _, X = model.formula_parser.build_design_matrices(
+                        model.data.data,
+                        return_type='array'
+                    )
+                    return X
+                except Exception:
+                    pass
+        
+        return None

panelbox/validation/serial_correlation/__init__.py

@@ -0,0 +1,13 @@
+"""
+Serial correlation tests for panel models.
+"""
+
+from panelbox.validation.serial_correlation.wooldridge_ar import WooldridgeARTest
+from panelbox.validation.serial_correlation.breusch_godfrey import BreuschGodfreyTest
+from panelbox.validation.serial_correlation.baltagi_wu import BaltagiWuTest
+
+__all__ = [
+    'WooldridgeARTest',
+    'BreuschGodfreyTest',
+    'BaltagiWuTest',
+]