StatsPAI

StatsPAI's test suite is organized into functional batches that define the library's core capabilities. Developers can use this categorization to understand which econometric and causal inference methods are supported and verified. The suites cover everything from basic OLS to advanced Agentic workflows and Machine Learning-based causal discovery.

Core Capabilities by Batch:

• Infrastructure & Core: OLS, diagnostics, postestimation, and model summary tools.
• Difference-in-Differences (DiD): Advanced DiD, staggered DiD, and time-varying covariates.
• Instrumental Variables (IV): Standard IV, 2SLS, mediation, and proximal methods.
• Regression Discontinuity (RD): Standard RD, RDDensity, and bunching.
• DML & Meta-learners: Double Machine Learning, Causal Forests, and Auto-CATE.
• Synthetic Control (Synth): Advanced synthetic control and sequential SDID.
• Matching & Panel Data: Optimal matching, GMM, ARIMA, GARCH, and High-Dimensional Fixed Effects (HDFE).
• Bayesian Inference: Bayesian DiD, IV, and BCF (Bayesian Causal Forests).
• ML & Causal Discovery: DAGs, TMLE, Causal Discovery, and Conformal Inference.
• Agent & Workflow: Agentic reasoning, MCP (Model Context Protocol) integration, and causal workflows.
• Output & Reporting: Regression tables, publication-ready exports (Quarto, AER style), and journal presets.

The sp.did module provides a comprehensive suite of Difference-in-Differences (DiD) estimators and diagnostic tools for applied causal inference. The API is organized into several specialized functions and utility modules.

Core Estimators:

• sp.callaway_santanna: Implements Callaway & Sant'Anna (2021) ATT(g,t) and Doubly Robust DiD (DR-DiD).
• sp.sun_abraham: Implements the IW event-study approach.
• sp.did_imputation: Implements Borusyak-Jaravel-Spiess imputation.
• sp.gardner_did / sp.did_2stage: Implements Gardner (2021) two-stage approach.
• sp.wooldridge_did: Implements Wooldridge ETWFE, DR-DiD, and TWFE diagnostics.
• sp.honest_did: Implements Rambachan-Roth (2023) sensitivity analysis.
• sp.bacon_decomposition: Implements Goodman-Bacon (2021) decomposition.
• sp.did_multiplegt: Implements dCDH (2020) DID_M.
• sp.continuous_did: Supports dose-quantile DiD, TWFE, and lpoly dose-response.
• sp.did_2x2: Implements the canonical 2×2 DiD.
• sp.cic: Implements Changes-in-Changes.
• sp.stacked_did: Implements Stacked DiD.
• sp.cohort_anchored: Implements Cohort-anchored DiD.
• sp.ddd: Implements Triple Difference.

Utilities and Diagnostics:

• sp.did_analysis / DIDAnalysis: A unified workflow for DiD analysis.
• sp.event_study: General event-study utility.
• sp.pretrends: Pretrend testing toolkit.
• sp.parallel_trends_plot, sp.bacon_plot, sp.group_time_plot, sp.did_plot: Specialized plotting functions.
• sp.cs_report: Generates LaTeX, Word, or Excel reports.

StatsPAI is an open-source Python package designed for causal inference and applied econometrics. It provides a unified interface for estimating, diagnosing, and reporting models that are typically fragmented across specialized packages (like DoWhy, EconML, or DoubleML) or proprietary environments like Stata.

Key features include:

• Broad Method Coverage: Includes regression, panel models, instrumental variables (IV), difference-in-differences (DiD), regression discontinuity (RD), synthetic control, matching, and machine-learning estimators for heterogeneous treatment effects.
• Unified Reporting: Mature estimators share a common reporting surface, allowing users to generate summaries, figures, LaTeX/Word tables, or citations using consistent calls.
• Agent-Native Design: Every registered function exposes a machine-readable schema (arguments, outputs, and failure metadata), enabling LLM-driven research assistants to discover estimators and validate assumptions programmatically.
• Extensible Backend: While primarily built on NumPy, SciPy, Pandas, statsmodels, scikit-learn, and linearmodels, it supports optional accelerators like PyTorch, JAX, and a Rust/PyO3 kernel for high-dimensional routines.

StatsPAI is optimized for end-to-end AER-style (American Economic Review) empirical workflows and agent-driven analysis. Use it instead of assembling multiple disparate packages in the following scenarios:

If you are calling sp.callaway_santanna (or sp.did) with both anticipation > 0 and base_period="varying", the behavior of pre-treatment placebo cells has changed to match R did.

What changed

StatsPAI now shifts the base period back by anticipation for post-treatment cells only. For pre-treatment placebo cells, the base period remains the period immediately before the treatment.

Impact on Results

• Pre-treatment ATT(g,t): Event-study leads, joint pre-trend tests, and anything built on placebo cells will move. The earliest pre-treatment cells that were previously dropped will now appear in the grid.
• Post-treatment ATT(g,t): These do not move. Consequently, sp.aggte results (overall, simple, group, or calendar effects) and the headline ATT remain unchanged.

Other logic changes

• Cohorts where no period satisfies t + anticipation < g are now dropped with an explicit warning.
• The period grid now uses strict inequalities and handles irregularly spaced periods (e.g., 1990, 1995, 2000) by resolving to the neighboring observed period.

StatsPAI uses a specific error taxonomy to provide machine-readable diagnostics and recovery hints instead of generic Python exceptions. When using fairness diagnostics, decomposition methods, or epidemiology measures, you may encounter the following specialized error types:

• MethodIncompatibility: Raised when parameters, weights, formulas, or methods are incompatible with the requested operation (e.g., invalid wild-bootstrap weights or unknown distributional statistics).
• DataInsufficient: Raised when the input data lacks the necessary information to perform a calculation (e.g., empty exposure rows in relative_risk or risk_difference).
• NumericalInstability: Raised when outputs are non-finite (NaN or Inf) or when numerical methods fail to produce stable results.
• ConvergenceFailure: Raised when iterative methods (like bootstrap paths) fail to converge, often providing n_ok/n_boot diagnostics to indicate the success rate.

Note: Many of these are subclasses of standard Python errors like ValueError, TypeError, or RuntimeError to maintain backward compatibility.

StatsPAI ensures correctness by comparing its implementations against canonical R or Stata references using a byte-for-byte comparison method. This process is designed to catch subtle statistical errors that standard unit tests (which often only check for direction, range, or shape) miss.

The Verification Workflow:

1. Source Inspection: Read the reference's actual source code (using deparse() in R or viewsource in Stata) rather than relying on documentation, to avoid naming traps (e.g., where a variable name like e(B) means different things in different languages).
2. Byte Comparison: Generate a single CSV containing results from StatsPAI, R, and Stata, and compare the values directly.
3. Bisection: If a divergence is found, bisect the calculation (design matrix, weights, residuals, meat matrix, etc.) to find the exact point of failure.
4. Classification:
   • T2 Module: A real gap in implementation.
   • Registered Tolerance: A documented convention difference.
   • Grade C: A gap that cannot be located and remains visibly open.
5. Registration: Finalize via the parity harness contract, tier A fixture lock, and audit scripts.