panelbox 0.2.0__py3-none-any.whl

panelbox/utils/matrix_ops.py

@@ -0,0 +1,233 @@
+"""
+Matrix operations for panel econometrics.
+
+This module provides optimized matrix operations commonly used in
+panel data estimation.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Tuple
+
+
+def add_intercept(X: np.ndarray) -> np.ndarray:
+    """
+    Add intercept column to design matrix.
+
+    Parameters
+    ----------
+    X : np.ndarray
+        Design matrix without intercept
+
+    Returns
+    -------
+    np.ndarray
+        Design matrix with intercept as first column
+    """
+    n = X.shape[0]
+    return np.column_stack([np.ones(n), X])
+
+
+def demean_matrix(
+    X: np.ndarray,
+    groups: np.ndarray
+) -> np.ndarray:
+    """
+    Demean matrix by groups (within transformation).
+
+    Parameters
+    ----------
+    X : np.ndarray
+        Matrix to demean (n x k)
+    groups : np.ndarray
+        Group identifiers (length n)
+
+    Returns
+    -------
+    np.ndarray
+        Demeaned matrix
+    """
+    X_demeaned = X.copy()
+    unique_groups = np.unique(groups)
+
+    for group in unique_groups:
+        mask = groups == group
+        group_mean = X[mask].mean(axis=0)
+        X_demeaned[mask] -= group_mean
+
+    return X_demeaned
+
+
+def compute_ols(
+    y: np.ndarray,
+    X: np.ndarray,
+    weights: np.ndarray = None
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Compute OLS estimates.
+
+    Parameters
+    ----------
+    y : np.ndarray
+        Dependent variable (n x 1 or length n)
+    X : np.ndarray
+        Design matrix (n x k)
+    weights : np.ndarray, optional
+        Observation weights
+
+    Returns
+    -------
+    beta : np.ndarray
+        Coefficient estimates (k x 1)
+    resid : np.ndarray
+        Residuals (n x 1)
+    fitted : np.ndarray
+        Fitted values (n x 1)
+    """
+    # Ensure y is column vector
+    if y.ndim == 1:
+        y = y.reshape(-1, 1)
+
+    if weights is not None:
+        # Weighted least squares
+        W = np.diag(np.sqrt(weights))
+        y_w = W @ y
+        X_w = W @ X
+        beta = np.linalg.lstsq(X_w, y_w, rcond=None)[0]
+    else:
+        # Ordinary least squares
+        beta = np.linalg.lstsq(X, y, rcond=None)[0]
+
+    # Compute fitted values and residuals
+    fitted = X @ beta
+    resid = y - fitted
+
+    return beta, resid.ravel(), fitted.ravel()
+
+
+def compute_vcov_nonrobust(
+    X: np.ndarray,
+    resid: np.ndarray,
+    df_resid: int
+) -> np.ndarray:
+    """
+    Compute non-robust covariance matrix.
+
+    Parameters
+    ----------
+    X : np.ndarray
+        Design matrix (n x k)
+    resid : np.ndarray
+        Residuals (length n)
+    df_resid : int
+        Degrees of freedom for residuals
+
+    Returns
+    -------
+    np.ndarray
+        Covariance matrix (k x k)
+    """
+    # Estimate of error variance
+    s2 = np.sum(resid ** 2) / df_resid
+
+    # Covariance matrix: s^2 (X'X)^{-1}
+    XtX_inv = np.linalg.inv(X.T @ X)
+    vcov = s2 * XtX_inv
+
+    return vcov
+
+
+def compute_rsquared(
+    y: np.ndarray,
+    fitted: np.ndarray,
+    resid: np.ndarray,
+    has_intercept: bool = True
+) -> Tuple[float, float]:
+    """
+    Compute R-squared and adjusted R-squared.
+
+    Parameters
+    ----------
+    y : np.ndarray
+        Dependent variable
+    fitted : np.ndarray
+        Fitted values
+    resid : np.ndarray
+        Residuals
+    has_intercept : bool, default=True
+        Whether model includes intercept
+
+    Returns
+    -------
+    rsquared : float
+        R-squared
+    rsquared_adj : float
+        Adjusted R-squared
+    """
+    # Total sum of squares
+    if has_intercept:
+        tss = np.sum((y - y.mean()) ** 2)
+    else:
+        tss = np.sum(y ** 2)
+
+    # Residual sum of squares
+    rss = np.sum(resid ** 2)
+
+    # R-squared
+    rsquared = 1 - (rss / tss) if tss > 0 else 0.0
+
+    return rsquared
+
+
+def compute_panel_rsquared(
+    y: np.ndarray,
+    fitted: np.ndarray,
+    resid: np.ndarray,
+    groups: np.ndarray
+) -> Tuple[float, float, float]:
+    """
+    Compute panel-specific R-squared measures.
+
+    Parameters
+    ----------
+    y : np.ndarray
+        Dependent variable
+    fitted : np.ndarray
+        Fitted values
+    resid : np.ndarray
+        Residuals
+    groups : np.ndarray
+        Group identifiers
+
+    Returns
+    -------
+    rsquared_within : float
+        Within R-squared
+    rsquared_between : float
+        Between R-squared
+    rsquared_overall : float
+        Overall R-squared
+    """
+    # Overall R-squared
+    y_mean = y.mean()
+    tss_overall = np.sum((y - y_mean) ** 2)
+    rss = np.sum(resid ** 2)
+    rsquared_overall = 1 - (rss / tss_overall) if tss_overall > 0 else 0.0
+
+    # Within R-squared (variation within groups)
+    y_demeaned = demean_matrix(y.reshape(-1, 1), groups).ravel()
+    fitted_demeaned = demean_matrix(fitted.reshape(-1, 1), groups).ravel()
+    tss_within = np.sum(y_demeaned ** 2)
+    ess_within = np.sum(fitted_demeaned ** 2)
+    rsquared_within = ess_within / tss_within if tss_within > 0 else 0.0
+
+    # Between R-squared (variation between group means)
+    unique_groups = np.unique(groups)
+    y_means = np.array([y[groups == g].mean() for g in unique_groups])
+    fitted_means = np.array([fitted[groups == g].mean() for g in unique_groups])
+    y_grand_mean = y.mean()
+    tss_between = np.sum((y_means - y_grand_mean) ** 2)
+    ess_between = np.sum((fitted_means - y_grand_mean) ** 2)
+    rsquared_between = ess_between / tss_between if tss_between > 0 else 0.0
+
+    return rsquared_within, rsquared_between, rsquared_overall

panelbox/utils/statistical.py

@@ -0,0 +1,173 @@
+"""
+Statistical functions for panel econometrics.
+
+This module provides statistical functions for hypothesis testing
+and inference in panel models.
+"""
+
+import numpy as np
+from scipy import stats
+from typing import Tuple
+
+
+def compute_tstat(
+    coef: float,
+    se: float
+) -> float:
+    """
+    Compute t-statistic.
+
+    Parameters
+    ----------
+    coef : float
+        Coefficient estimate
+    se : float
+        Standard error
+
+    Returns
+    -------
+    float
+        t-statistic
+    """
+    return coef / se if se > 0 else np.nan
+
+
+def compute_pvalue(
+    tstat: float,
+    df: int,
+    two_sided: bool = True
+) -> float:
+    """
+    Compute p-value for t-statistic.
+
+    Parameters
+    ----------
+    tstat : float
+        t-statistic
+    df : int
+        Degrees of freedom
+    two_sided : bool, default=True
+        Whether to compute two-sided p-value
+
+    Returns
+    -------
+    float
+        p-value
+    """
+    if two_sided:
+        return 2 * (1 - stats.t.cdf(np.abs(tstat), df))
+    else:
+        return 1 - stats.t.cdf(tstat, df)
+
+
+def compute_fstat(
+    rss_restricted: float,
+    rss_unrestricted: float,
+    df_diff: int,
+    df_resid: int
+) -> Tuple[float, float]:
+    """
+    Compute F-statistic for nested model comparison.
+
+    Parameters
+    ----------
+    rss_restricted : float
+        Residual sum of squares from restricted model
+    rss_unrestricted : float
+        Residual sum of squares from unrestricted model
+    df_diff : int
+        Difference in degrees of freedom (number of restrictions)
+    df_resid : int
+        Degrees of freedom for residuals (unrestricted model)
+
+    Returns
+    -------
+    fstat : float
+        F-statistic
+    pvalue : float
+        p-value
+    """
+    numerator = (rss_restricted - rss_unrestricted) / df_diff
+    denominator = rss_unrestricted / df_resid
+
+    fstat = numerator / denominator if denominator > 0 else np.nan
+    pvalue = 1 - stats.f.cdf(fstat, df_diff, df_resid)
+
+    return fstat, pvalue
+
+
+def wald_test(
+    restrictions: np.ndarray,
+    params: np.ndarray,
+    vcov: np.ndarray,
+    q: np.ndarray = None
+) -> Tuple[float, float, int]:
+    """
+    Compute Wald test for linear restrictions.
+
+    Tests H0: R*beta = q
+
+    Parameters
+    ----------
+    restrictions : np.ndarray
+        Restriction matrix R (m x k)
+    params : np.ndarray
+        Parameter estimates (k x 1)
+    vcov : np.ndarray
+        Covariance matrix (k x k)
+    q : np.ndarray, optional
+        RHS of restrictions (m x 1). Default is zeros.
+
+    Returns
+    -------
+    statistic : float
+        Wald chi-squared statistic
+    pvalue : float
+        p-value
+    df : int
+        Degrees of freedom
+    """
+    if params.ndim == 1:
+        params = params.reshape(-1, 1)
+
+    if q is None:
+        q = np.zeros((restrictions.shape[0], 1))
+    elif q.ndim == 1:
+        q = q.reshape(-1, 1)
+
+    # Compute R*beta - q
+    restriction_value = restrictions @ params - q
+
+    # Compute (R * Vcov * R')^{-1}
+    middle = restrictions @ vcov @ restrictions.T
+    middle_inv = np.linalg.inv(middle)
+
+    # Wald statistic: (R*beta - q)' (R * Vcov * R')^{-1} (R*beta - q)
+    statistic = float(restriction_value.T @ middle_inv @ restriction_value)
+
+    # Degrees of freedom
+    df = restrictions.shape[0]
+
+    # p-value from chi-squared distribution
+    pvalue = 1 - stats.chi2.cdf(statistic, df)
+
+    return statistic, pvalue, df
+
+
+def compute_chi2_pvalue(statistic: float, df: int) -> float:
+    """
+    Compute p-value for chi-squared statistic.
+
+    Parameters
+    ----------
+    statistic : float
+        Chi-squared statistic
+    df : int
+        Degrees of freedom
+
+    Returns
+    -------
+    float
+        p-value
+    """
+    return 1 - stats.chi2.cdf(statistic, df)

panelbox/validation/__init__.py

@@ -0,0 +1,58 @@
+"""
+Validation tests for panel data models.
+"""
+
+from panelbox.validation.base import ValidationTest, ValidationTestResult
+from panelbox.validation.validation_suite import ValidationSuite
+from panelbox.validation.validation_report import ValidationReport
+
+# Specification tests
+from panelbox.validation.specification.hausman import HausmanTest, HausmanTestResult
+from panelbox.validation.specification.mundlak import MundlakTest
+from panelbox.validation.specification.reset import RESETTest
+from panelbox.validation.specification.chow import ChowTest
+
+# Serial correlation tests
+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
+
+# Heteroskedasticity tests
+from panelbox.validation.heteroskedasticity.modified_wald import ModifiedWaldTest
+from panelbox.validation.heteroskedasticity.breusch_pagan import BreuschPaganTest
+from panelbox.validation.heteroskedasticity.white import WhiteTest
+
+# Cross-sectional dependence tests
+from panelbox.validation.cross_sectional_dependence.pesaran_cd import PesaranCDTest
+from panelbox.validation.cross_sectional_dependence.breusch_pagan_lm import BreuschPaganLMTest
+from panelbox.validation.cross_sectional_dependence.frees import FreesTest
+
+__all__ = [
+    # Base classes
+    'ValidationTest',
+    'ValidationTestResult',
+    'ValidationSuite',
+    'ValidationReport',
+
+    # Specification tests
+    'HausmanTest',
+    'HausmanTestResult',
+    'MundlakTest',
+    'RESETTest',
+    'ChowTest',
+
+    # Serial correlation tests
+    'WooldridgeARTest',
+    'BreuschGodfreyTest',
+    'BaltagiWuTest',
+
+    # Heteroskedasticity tests
+    'ModifiedWaldTest',
+    'BreuschPaganTest',
+    'WhiteTest',
+
+    # Cross-sectional dependence tests
+    'PesaranCDTest',
+    'BreuschPaganLMTest',
+    'FreesTest',
+]

panelbox/validation/base.py

@@ -0,0 +1,175 @@
+"""
+Base classes for validation tests.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+import pandas as pd
+
+
+class ValidationTestResult:
+    """
+    Container for validation test results.
+    
+    Attributes
+    ----------
+    test_name : str
+        Name of the test
+    statistic : float
+        Test statistic value
+    pvalue : float
+        P-value
+    df : int or tuple, optional
+        Degrees of freedom
+    alpha : float
+        Significance level used
+    conclusion : str
+        Interpretation of test result
+    null_hypothesis : str
+        Description of H0
+    alternative_hypothesis : str
+        Description of H1
+    metadata : dict
+        Additional test-specific information
+    """
+    
+    def __init__(
+        self,
+        test_name: str,
+        statistic: float,
+        pvalue: float,
+        null_hypothesis: str,
+        alternative_hypothesis: str,
+        alpha: float = 0.05,
+        df: Optional[Any] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ):
+        self.test_name = test_name
+        self.statistic = statistic
+        self.pvalue = pvalue
+        self.df = df
+        self.alpha = alpha
+        self.null_hypothesis = null_hypothesis
+        self.alternative_hypothesis = alternative_hypothesis
+        self.metadata = metadata or {}
+        # Add 'df' to metadata for convenience if provided
+        if df is not None and 'df' not in self.metadata:
+            self.metadata['df'] = df
+
+        # Determine conclusion
+        if pvalue < alpha:
+            self.reject_null = True
+            self.conclusion = (
+                f"Reject H0 at {alpha*100:.0f}% level. {alternative_hypothesis}"
+            )
+        else:
+            self.reject_null = False
+            self.conclusion = (
+                f"Fail to reject H0 at {alpha*100:.0f}% level. {null_hypothesis}"
+            )
+
+    @property
+    def details(self):
+        """Alias for metadata for backwards compatibility."""
+        return self.metadata
+    
+    def __str__(self) -> str:
+        """String representation."""
+        return self.summary()
+    
+    def __repr__(self) -> str:
+        """Repr."""
+        return f"{self.test_name}Result(statistic={self.statistic:.3f}, pvalue={self.pvalue:.4f})"
+    
+    def summary(self) -> str:
+        """
+        Generate formatted summary.
+        
+        Returns
+        -------
+        str
+            Formatted test results
+        """
+        lines = []
+        lines.append("=" * 70)
+        lines.append(self.test_name.upper())
+        lines.append("=" * 70)
+        lines.append("")
+        lines.append(f"H0: {self.null_hypothesis}")
+        lines.append(f"H1: {self.alternative_hypothesis}")
+        lines.append("")
+        lines.append("-" * 70)
+        lines.append(f"{'Test Statistic':<30} {self.statistic:>15.4f}")
+        lines.append(f"{'P-value':<30} {self.pvalue:>15.4f}")
+        
+        if self.df is not None:
+            if isinstance(self.df, tuple):
+                df_str = f"({self.df[0]}, {self.df[1]})"
+            else:
+                df_str = str(self.df)
+            lines.append(f"{'Degrees of Freedom':<30} {df_str:>15}")
+        
+        lines.append("-" * 70)
+        lines.append("")
+        lines.append(f"Conclusion: {self.conclusion}")
+        
+        # Add metadata if present
+        if self.metadata:
+            lines.append("")
+            lines.append("Additional Information:")
+            for key, value in self.metadata.items():
+                if isinstance(value, float):
+                    lines.append(f"  {key}: {value:.4f}")
+                else:
+                    lines.append(f"  {key}: {value}")
+        
+        lines.append("=" * 70)
+        lines.append("")
+        
+        return "\n".join(lines)
+
+
+class ValidationTest(ABC):
+    """
+    Abstract base class for validation tests.
+    
+    All validation tests should inherit from this class and implement
+    the `run()` method.
+    """
+    
+    def __init__(self, results: 'PanelResults'):
+        """
+        Initialize validation test.
+        
+        Parameters
+        ----------
+        results : PanelResults
+            Results object from panel model estimation
+        """
+        self.results = results
+        self.resid = results.resid
+        self.fittedvalues = results.fittedvalues
+        self.params = results.params
+        self.nobs = results.nobs
+        self.n_entities = results.n_entities
+        self.n_periods = results.n_periods
+        self.model_type = results.model_type
+    
+    @abstractmethod
+    def run(self, alpha: float = 0.05, **kwargs) -> ValidationTestResult:
+        """
+        Run the validation test.
+        
+        Parameters
+        ----------
+        alpha : float, default=0.05
+            Significance level
+        **kwargs
+            Test-specific keyword arguments
+        
+        Returns
+        -------
+        ValidationTestResult
+            Test results
+        """
+        pass

panelbox/validation/cross_sectional_dependence/__init__.py

@@ -0,0 +1,13 @@
+"""
+Cross-sectional dependence tests for panel models.
+"""
+
+from panelbox.validation.cross_sectional_dependence.pesaran_cd import PesaranCDTest
+from panelbox.validation.cross_sectional_dependence.breusch_pagan_lm import BreuschPaganLMTest
+from panelbox.validation.cross_sectional_dependence.frees import FreesTest
+
+__all__ = [
+    'PesaranCDTest',
+    'BreuschPaganLMTest',
+    'FreesTest',
+]