panelbox 0.2.0__py3-none-any.whl

panelbox/validation/validation_report.py

@@ -0,0 +1,257 @@
+"""
+Validation report container.
+"""
+
+from typing import Dict, Optional, List
+from panelbox.validation.base import ValidationTestResult
+
+
+class ValidationReport:
+    """
+    Container for validation test results.
+    
+    Attributes
+    ----------
+    model_info : dict
+        Information about the model being validated
+    specification_tests : dict
+        Results of specification tests (Hausman, Mundlak, etc.)
+    serial_tests : dict
+        Results of serial correlation tests
+    het_tests : dict
+        Results of heteroskedasticity tests
+    cd_tests : dict
+        Results of cross-sectional dependence tests
+    """
+    
+    def __init__(
+        self,
+        model_info: Dict[str, any],
+        specification_tests: Optional[Dict[str, ValidationTestResult]] = None,
+        serial_tests: Optional[Dict[str, ValidationTestResult]] = None,
+        het_tests: Optional[Dict[str, ValidationTestResult]] = None,
+        cd_tests: Optional[Dict[str, ValidationTestResult]] = None
+    ):
+        self.model_info = model_info
+        self.specification_tests = specification_tests or {}
+        self.serial_tests = serial_tests or {}
+        self.het_tests = het_tests or {}
+        self.cd_tests = cd_tests or {}
+    
+    def __str__(self) -> str:
+        """String representation."""
+        return self.summary()
+    
+    def __repr__(self) -> str:
+        """Repr."""
+        n_tests = (
+            len(self.specification_tests) +
+            len(self.serial_tests) +
+            len(self.het_tests) +
+            len(self.cd_tests)
+        )
+        return f"ValidationReport(model='{self.model_info.get('model_type')}', tests={n_tests})"
+    
+    def summary(self, verbose: bool = True) -> str:
+        """
+        Generate formatted summary of all validation tests.
+        
+        Parameters
+        ----------
+        verbose : bool, default=True
+            If True, include full details of each test
+            If False, show only summary table
+        
+        Returns
+        -------
+        str
+            Formatted validation report
+        """
+        lines = []
+        lines.append("=" * 78)
+        lines.append("MODEL VALIDATION REPORT")
+        lines.append("=" * 78)
+        lines.append("")
+        
+        # Model information
+        lines.append("Model Information:")
+        lines.append(f"  Type:    {self.model_info.get('model_type', 'Unknown')}")
+        lines.append(f"  Formula: {self.model_info.get('formula', 'Unknown')}")
+        lines.append(f"  N obs:   {self.model_info.get('nobs', 'Unknown')}")
+        lines.append(f"  N entities: {self.model_info.get('n_entities', 'Unknown')}")
+        lines.append("")
+        
+        # Summary table
+        lines.append("=" * 78)
+        lines.append("VALIDATION TESTS SUMMARY")
+        lines.append("=" * 78)
+        lines.append(f"{'Test':<35} {'Statistic':<12} {'P-value':<10} {'Result':<10}")
+        lines.append("-" * 78)
+        
+        # Helper function to add test row
+        def add_test_row(test_name, test_result):
+            if test_result is None:
+                return
+            
+            stat_str = f"{test_result.statistic:.3f}"
+            pval_str = f"{test_result.pvalue:.4f}"
+            result = "REJECT" if test_result.reject_null else "OK"
+            
+            lines.append(f"{test_name:<35} {stat_str:<12} {pval_str:<10} {result:<10}")
+        
+        # Specification tests
+        if self.specification_tests:
+            lines.append("")
+            lines.append("Specification Tests:")
+            for name, result in self.specification_tests.items():
+                add_test_row(f"  {name}", result)
+        
+        # Serial correlation tests
+        if self.serial_tests:
+            lines.append("")
+            lines.append("Serial Correlation Tests:")
+            for name, result in self.serial_tests.items():
+                add_test_row(f"  {name}", result)
+        
+        # Heteroskedasticity tests
+        if self.het_tests:
+            lines.append("")
+            lines.append("Heteroskedasticity Tests:")
+            for name, result in self.het_tests.items():
+                add_test_row(f"  {name}", result)
+        
+        # Cross-sectional dependence tests
+        if self.cd_tests:
+            lines.append("")
+            lines.append("Cross-Sectional Dependence Tests:")
+            for name, result in self.cd_tests.items():
+                add_test_row(f"  {name}", result)
+        
+        lines.append("=" * 78)
+        lines.append("")
+        
+        # Diagnostics summary
+        problems = []
+        
+        for category, tests in [
+            ("specification", self.specification_tests),
+            ("serial correlation", self.serial_tests),
+            ("heteroskedasticity", self.het_tests),
+            ("cross-sectional dependence", self.cd_tests)
+        ]:
+            for name, result in tests.items():
+                if result.reject_null:
+                    problems.append(f"  - {name}: {category}")
+        
+        if problems:
+            lines.append("⚠️  POTENTIAL ISSUES DETECTED:")
+            lines.extend(problems)
+            lines.append("")
+            lines.append("Consider:")
+            
+            if any("serial correlation" in p for p in problems):
+                lines.append("  • Use clustered standard errors or HAC errors")
+            
+            if any("heteroskedasticity" in p for p in problems):
+                lines.append("  • Use robust standard errors")
+            
+            if any("cross-sectional dependence" in p for p in problems):
+                lines.append("  • Use Driscoll-Kraay standard errors")
+            
+            if any("specification" in p for p in problems):
+                lines.append("  • Review model specification")
+        else:
+            lines.append("✓ No major issues detected in validation tests")
+        
+        lines.append("")
+        lines.append("=" * 78)
+        lines.append("")
+        
+        # Verbose output: detailed results
+        if verbose and (self.specification_tests or self.serial_tests or 
+                       self.het_tests or self.cd_tests):
+            lines.append("")
+            lines.append("DETAILED TEST RESULTS")
+            lines.append("=" * 78)
+            lines.append("")
+            
+            for category, tests in [
+                ("SPECIFICATION TESTS", self.specification_tests),
+                ("SERIAL CORRELATION TESTS", self.serial_tests),
+                ("HETEROSKEDASTICITY TESTS", self.het_tests),
+                ("CROSS-SECTIONAL DEPENDENCE TESTS", self.cd_tests)
+            ]:
+                if tests:
+                    lines.append("")
+                    lines.append(category)
+                    lines.append("-" * 78)
+                    for name, result in tests.items():
+                        lines.append("")
+                        lines.append(result.summary())
+        
+        return "\n".join(lines)
+    
+    def to_dict(self) -> Dict:
+        """
+        Export validation report to dictionary.
+        
+        Returns
+        -------
+        dict
+            Dictionary with all test results
+        """
+        result = {
+            'model_info': self.model_info,
+            'specification_tests': {},
+            'serial_tests': {},
+            'het_tests': {},
+            'cd_tests': {}
+        }
+        
+        # Helper to convert test result to dict
+        def test_to_dict(test):
+            return {
+                'statistic': test.statistic,
+                'pvalue': test.pvalue,
+                'df': test.df,
+                'reject_null': test.reject_null,
+                'conclusion': test.conclusion,
+                'metadata': test.metadata
+            }
+        
+        for name, test in self.specification_tests.items():
+            result['specification_tests'][name] = test_to_dict(test)
+        
+        for name, test in self.serial_tests.items():
+            result['serial_tests'][name] = test_to_dict(test)
+        
+        for name, test in self.het_tests.items():
+            result['het_tests'][name] = test_to_dict(test)
+        
+        for name, test in self.cd_tests.items():
+            result['cd_tests'][name] = test_to_dict(test)
+        
+        return result
+    
+    def get_failed_tests(self) -> List[str]:
+        """
+        Get list of tests that rejected the null hypothesis.
+        
+        Returns
+        -------
+        list
+            Names of tests that detected issues
+        """
+        failed = []
+        
+        for category, tests in [
+            ("spec", self.specification_tests),
+            ("serial", self.serial_tests),
+            ("het", self.het_tests),
+            ("cd", self.cd_tests)
+        ]:
+            for name, result in tests.items():
+                if result.reject_null:
+                    failed.append(f"{category}/{name}")
+        
+        return failed

panelbox/validation/validation_suite.py

@@ -0,0 +1,401 @@
+"""
+Validation suite for panel models.
+"""
+
+from typing import List, Optional, Dict, Union
+import warnings
+
+from panelbox.core.results import PanelResults
+from panelbox.validation.validation_report import ValidationReport
+from panelbox.validation.base import ValidationTestResult
+
+# Import tests
+from panelbox.validation.specification.hausman import HausmanTest
+from panelbox.validation.specification.mundlak import MundlakTest
+from panelbox.validation.specification.reset import RESETTest
+from panelbox.validation.specification.chow import ChowTest
+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
+from panelbox.validation.heteroskedasticity.modified_wald import ModifiedWaldTest
+from panelbox.validation.heteroskedasticity.breusch_pagan import BreuschPaganTest
+from panelbox.validation.heteroskedasticity.white import WhiteTest
+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
+
+
+class ValidationSuite:
+    """
+    Suite of validation tests for panel models.
+    
+    This class provides a unified interface to run various diagnostic tests
+    on panel model results.
+    
+    Parameters
+    ----------
+    results : PanelResults
+        Results from panel model estimation
+    
+    Examples
+    --------
+    >>> from panelbox.models.static.fixed_effects import FixedEffects
+    >>> fe = FixedEffects("y ~ x1 + x2", data, "entity", "time")
+    >>> results = fe.fit()
+    >>> 
+    >>> from panelbox.validation.validation_suite import ValidationSuite
+    >>> suite = ValidationSuite(results)
+    >>> report = suite.run(tests='all')
+    >>> print(report)
+    """
+    
+    def __init__(self, results: PanelResults):
+        """
+        Initialize validation suite.
+        
+        Parameters
+        ----------
+        results : PanelResults
+            Results from panel model estimation
+        """
+        self.results = results
+        self.model_type = results.model_type
+    
+    def run(
+        self,
+        tests: Union[str, List[str]] = 'default',
+        alpha: float = 0.05,
+        verbose: bool = False
+    ) -> ValidationReport:
+        """
+        Run validation tests.
+        
+        Parameters
+        ----------
+        tests : str or list of str, default='default'
+            Which tests to run:
+            - 'all': Run all available tests
+            - 'default': Run recommended tests for this model type
+            - 'serial': Serial correlation tests only
+            - 'het': Heteroskedasticity tests only
+            - 'cd': Cross-sectional dependence tests only
+            - List of test names
+        alpha : float, default=0.05
+            Significance level for tests
+        verbose : bool, default=False
+            If True, print progress during testing
+        
+        Returns
+        -------
+        ValidationReport
+            Report containing all test results
+        """
+        # Determine which tests to run
+        tests_to_run = self._determine_tests(tests)
+        
+        # Run tests by category
+        specification_tests = {}
+        serial_tests = {}
+        het_tests = {}
+        cd_tests = {}
+        
+        # Specification tests
+        if 'specification' in tests_to_run:
+            specification_tests = self.run_specification_tests(alpha, verbose)
+        
+        # Serial correlation tests
+        if 'serial' in tests_to_run:
+            serial_tests = self.run_serial_correlation_tests(alpha, verbose)
+        
+        # Heteroskedasticity tests
+        if 'het' in tests_to_run:
+            het_tests = self.run_heteroskedasticity_tests(alpha, verbose)
+        
+        # Cross-sectional dependence tests
+        if 'cd' in tests_to_run:
+            cd_tests = self.run_cross_sectional_tests(alpha, verbose)
+        
+        # Create validation report
+        model_info = {
+            'model_type': self.model_type,
+            'formula': self.results.formula,
+            'nobs': self.results.nobs,
+            'n_entities': self.results.n_entities,
+            'n_periods': self.results.n_periods
+        }
+        
+        report = ValidationReport(
+            model_info=model_info,
+            specification_tests=specification_tests,
+            serial_tests=serial_tests,
+            het_tests=het_tests,
+            cd_tests=cd_tests
+        )
+        
+        return report
+    
+    def run_specification_tests(
+        self,
+        alpha: float = 0.05,
+        verbose: bool = False
+    ) -> Dict[str, ValidationTestResult]:
+        """
+        Run specification tests.
+
+        Parameters
+        ----------
+        alpha : float, default=0.05
+            Significance level
+        verbose : bool, default=False
+            Print progress
+
+        Returns
+        -------
+        dict
+            Dictionary of test results
+        """
+        results = {}
+
+        # Note: Hausman test requires two model results (FE and RE)
+        # It cannot be run from a single results object
+        # Users should run it separately
+
+        # Mundlak test (for RE models)
+        if 'Random Effects' in self.model_type:
+            try:
+                if verbose:
+                    print("Running Mundlak test...")
+                test = MundlakTest(self.results)
+                results['Mundlak'] = test.run(alpha)
+            except Exception as e:
+                if verbose:
+                    print(f"  Warning: Mundlak test failed: {e}")
+                warnings.warn(f"Mundlak test failed: {e}")
+
+        # RESET test (for all models)
+        try:
+            if verbose:
+                print("Running RESET test...")
+            test = RESETTest(self.results)
+            results['RESET'] = test.run(alpha=alpha)
+        except Exception as e:
+            if verbose:
+                print(f"  Warning: RESET test failed: {e}")
+            warnings.warn(f"RESET test failed: {e}")
+
+        # Chow test (for all models)
+        # Note: Requires break_point parameter, skip by default
+        # Users can run separately with specific break point
+
+        return results
+    
+    def run_serial_correlation_tests(
+        self,
+        alpha: float = 0.05,
+        verbose: bool = False
+    ) -> Dict[str, ValidationTestResult]:
+        """
+        Run serial correlation tests.
+
+        Parameters
+        ----------
+        alpha : float, default=0.05
+            Significance level
+        verbose : bool, default=False
+            Print progress
+
+        Returns
+        -------
+        dict
+            Dictionary of test results
+        """
+        results = {}
+
+        # Wooldridge test (for FE models)
+        if 'Fixed Effects' in self.model_type:
+            try:
+                if verbose:
+                    print("Running Wooldridge AR test...")
+                test = WooldridgeARTest(self.results)
+                results['Wooldridge'] = test.run(alpha)
+            except Exception as e:
+                if verbose:
+                    print(f"  Warning: Wooldridge test failed: {e}")
+                warnings.warn(f"Wooldridge test failed: {e}")
+
+        # Breusch-Godfrey test (for all models)
+        try:
+            if verbose:
+                print("Running Breusch-Godfrey test...")
+            test = BreuschGodfreyTest(self.results)
+            results['Breusch-Godfrey'] = test.run(lags=1, alpha=alpha)
+        except Exception as e:
+            if verbose:
+                print(f"  Warning: Breusch-Godfrey test failed: {e}")
+            warnings.warn(f"Breusch-Godfrey test failed: {e}")
+
+        # Baltagi-Wu LBI test (for all models, especially unbalanced panels)
+        try:
+            if verbose:
+                print("Running Baltagi-Wu LBI test...")
+            test = BaltagiWuTest(self.results)
+            results['Baltagi-Wu'] = test.run(alpha=alpha)
+        except Exception as e:
+            if verbose:
+                print(f"  Warning: Baltagi-Wu test failed: {e}")
+            warnings.warn(f"Baltagi-Wu test failed: {e}")
+
+        return results
+    
+    def run_heteroskedasticity_tests(
+        self,
+        alpha: float = 0.05,
+        verbose: bool = False
+    ) -> Dict[str, ValidationTestResult]:
+        """
+        Run heteroskedasticity tests.
+        
+        Parameters
+        ----------
+        alpha : float, default=0.05
+            Significance level
+        verbose : bool, default=False
+            Print progress
+        
+        Returns
+        -------
+        dict
+            Dictionary of test results
+        """
+        results = {}
+        
+        # Modified Wald test (for FE models)
+        if 'Fixed Effects' in self.model_type:
+            try:
+                if verbose:
+                    print("Running Modified Wald test...")
+                test = ModifiedWaldTest(self.results)
+                results['Modified Wald'] = test.run(alpha)
+            except Exception as e:
+                if verbose:
+                    print(f"  Warning: Modified Wald test failed: {e}")
+                warnings.warn(f"Modified Wald test failed: {e}")
+
+        # Breusch-Pagan LM test (for all models)
+        try:
+            if verbose:
+                print("Running Breusch-Pagan test...")
+            test = BreuschPaganTest(self.results)
+            results['Breusch-Pagan'] = test.run(alpha)
+        except Exception as e:
+            if verbose:
+                print(f"  Warning: Breusch-Pagan test failed: {e}")
+            warnings.warn(f"Breusch-Pagan test failed: {e}")
+
+        # White test (for all models)
+        try:
+            if verbose:
+                print("Running White test...")
+            test = WhiteTest(self.results)
+            results['White'] = test.run(alpha, cross_terms=False)  # Without cross terms for speed
+        except Exception as e:
+            if verbose:
+                print(f"  Warning: White test failed: {e}")
+            warnings.warn(f"White test failed: {e}")
+
+        return results
+    
+    def run_cross_sectional_tests(
+        self,
+        alpha: float = 0.05,
+        verbose: bool = False
+    ) -> Dict[str, ValidationTestResult]:
+        """
+        Run cross-sectional dependence tests.
+
+        Parameters
+        ----------
+        alpha : float, default=0.05
+            Significance level
+        verbose : bool, default=False
+            Print progress
+
+        Returns
+        -------
+        dict
+            Dictionary of test results
+        """
+        results = {}
+
+        # Pesaran CD test (for all models, large N)
+        try:
+            if verbose:
+                print("Running Pesaran CD test...")
+            test = PesaranCDTest(self.results)
+            results['Pesaran CD'] = test.run(alpha)
+        except Exception as e:
+            if verbose:
+                print(f"  Warning: Pesaran CD test failed: {e}")
+            warnings.warn(f"Pesaran CD test failed: {e}")
+
+        # Breusch-Pagan LM test (for all models, small to moderate N)
+        try:
+            if verbose:
+                print("Running Breusch-Pagan LM test...")
+            test = BreuschPaganLMTest(self.results)
+            results['Breusch-Pagan LM'] = test.run(alpha=alpha)
+        except Exception as e:
+            if verbose:
+                print(f"  Warning: Breusch-Pagan LM test failed: {e}")
+            warnings.warn(f"Breusch-Pagan LM test failed: {e}")
+
+        # Frees test (non-parametric, robust to non-normality)
+        try:
+            if verbose:
+                print("Running Frees test...")
+            test = FreesTest(self.results)
+            results['Frees'] = test.run(alpha=alpha)
+        except Exception as e:
+            if verbose:
+                print(f"  Warning: Frees test failed: {e}")
+            warnings.warn(f"Frees test failed: {e}")
+
+        return results
+    
+    def _determine_tests(self, tests: Union[str, List[str]]) -> List[str]:
+        """
+        Determine which test categories to run.
+        
+        Parameters
+        ----------
+        tests : str or list
+            Test specification
+        
+        Returns
+        -------
+        list
+            List of test categories
+        """
+        if tests == 'all':
+            return ['specification', 'serial', 'het', 'cd']
+        elif tests == 'default':
+            # Recommended tests based on model type
+            if 'Fixed Effects' in self.model_type:
+                return ['serial', 'het', 'cd']
+            elif 'Random Effects' in self.model_type:
+                return ['cd']
+            else:  # Pooled OLS
+                return ['het', 'cd']
+        elif tests == 'serial':
+            return ['serial']
+        elif tests == 'het':
+            return ['het']
+        elif tests == 'cd':
+            return ['cd']
+        elif isinstance(tests, list):
+            return tests
+        else:
+            raise ValueError(
+                f"Invalid tests specification: {tests}. "
+                "Use 'all', 'default', 'serial', 'het', 'cd', or a list of test names"
+            )