diff-diff 1.3.0__tar.gz → 1.4.0__tar.gz

{diff_diff-1.3.0 → diff_diff-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 1.3.0
+Version: 1.4.0
 Summary: A library for Difference-in-Differences causal inference analysis
 Author: diff-diff contributors
 License-Expression: MIT
@@ -116,6 +116,7 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 - **Pre-trends power analysis**: Roth (2022) minimum detectable violation (MDV) and power curves for pre-trends tests
 - **Power analysis**: MDE, sample size, and power calculations for study design; simulation-based power for any estimator
 - **Data prep utilities**: Helper functions for common data preparation tasks
+- **Validated against R**: Benchmarked against `did`, `synthdid`, and `fixest` packages (see [benchmarks](docs/benchmarks.rst))
 
 ## Tutorials
 

{diff_diff-1.3.0 → diff_diff-1.4.0}/README.md

@@ -81,6 +81,7 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 - **Pre-trends power analysis**: Roth (2022) minimum detectable violation (MDV) and power curves for pre-trends tests
 - **Power analysis**: MDE, sample size, and power calculations for study design; simulation-based power for any estimator
 - **Data prep utilities**: Helper functions for common data preparation tasks
+- **Validated against R**: Benchmarked against `did`, `synthdid`, and `fixest` packages (see [benchmarks](docs/benchmarks.rst))
 
 ## Tutorials
 

{diff_diff-1.3.0 → diff_diff-1.4.0}/diff_diff/__init__.py

@@ -103,7 +103,7 @@ from diff_diff.visualization import (
     plot_sensitivity,
 )
 
-__version__ = "1.2.1"
+__version__ = "1.4.0"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",

{diff_diff-1.3.0 → diff_diff-1.4.0}/diff_diff/estimators.py

@@ -17,12 +17,12 @@ from typing import Any, Dict, List, Optional, Tuple
 import numpy as np
 import pandas as pd
 
+from diff_diff.linalg import compute_r_squared, compute_robust_vcov, solve_ols
 from diff_diff.results import DiDResults, MultiPeriodDiDResults, PeriodEffect
 from diff_diff.utils import (
     WildBootstrapResults,
     compute_confidence_interval,
     compute_p_value,
-    compute_robust_se,
     validate_binary,
     wild_bootstrap_se,
 )
@@ -261,8 +261,11 @@ class DifferenceInDifferences:
                     X = np.column_stack([X, dummies[col].values.astype(float)])
                     var_names.append(col)
 
-        # Fit OLS
-        coefficients, residuals, fitted, r_squared = self._fit_ols(X, y)
+        # Fit OLS using unified backend
+        coefficients, residuals, fitted, vcov = solve_ols(
+            X, y, return_fitted=True, return_vcov=False
+        )
+        r_squared = compute_r_squared(y, residuals)
 
         # Extract ATT (coefficient on interaction term)
         att_idx = 3  # Index of interaction term
@@ -285,13 +288,13 @@ class DifferenceInDifferences:
             )
         elif self.cluster is not None:
             cluster_ids = data[self.cluster].values
-            vcov = compute_robust_se(X, residuals, cluster_ids)
+            vcov = compute_robust_vcov(X, residuals, cluster_ids)
             se = np.sqrt(vcov[att_idx, att_idx])
             t_stat = att / se
             p_value = compute_p_value(t_stat, df=df)
             conf_int = compute_confidence_interval(att, se, self.alpha, df=df)
         elif self.robust:
-            vcov = compute_robust_se(X, residuals)
+            vcov = compute_robust_vcov(X, residuals)
             se = np.sqrt(vcov[att_idx, att_idx])
             t_stat = att / se
             p_value = compute_p_value(t_stat, df=df)
@@ -300,7 +303,7 @@ class DifferenceInDifferences:
             # Classical OLS standard errors
             n = len(y)
             k = X.shape[1]
-            mse = np.sum(residuals ** 2) / (n - k)
+            mse = np.sum(residuals**2) / (n - k)
             # Use solve() instead of inv() for numerical stability
             # solve(A, B) computes X where AX=B, so this yields (X'X)^{-1} * mse
             vcov = np.linalg.solve(X.T @ X, mse * np.eye(k))
@@ -352,10 +355,15 @@ class DifferenceInDifferences:
 
         return self.results_
 
-    def _fit_ols(self, X: np.ndarray, y: np.ndarray) -> Tuple[np.ndarray, np.ndarray, np.ndarray, float]:
+    def _fit_ols(
+        self, X: np.ndarray, y: np.ndarray
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, float]:
         """
         Fit OLS regression.
 
+        This method is kept for backwards compatibility. Internally uses the
+        unified solve_ols from diff_diff.linalg for optimized computation.
+
         Parameters
         ----------
         X : np.ndarray
@@ -367,32 +375,12 @@ class DifferenceInDifferences:
         -------
         tuple
             (coefficients, residuals, fitted_values, r_squared)
-
-        Raises
-        ------
-        ValueError
-            If design matrix is rank-deficient (perfect multicollinearity).
         """
-        # Check for rank deficiency (perfect multicollinearity)
-        rank = np.linalg.matrix_rank(X)
-        if rank < X.shape[1]:
-            raise ValueError(
-                f"Design matrix is rank-deficient (rank {rank} < {X.shape[1]} columns). "
-                "This indicates perfect multicollinearity. Check your fixed effects "
-                "and covariates for linear dependencies."
-            )
-
-        # Solve normal equations: β = (X'X)^(-1) X'y
-        coefficients = np.linalg.lstsq(X, y, rcond=None)[0]
-
-        # Compute fitted values and residuals
-        fitted = X @ coefficients
-        residuals = y - fitted
-
-        # Compute R-squared
-        ss_res = np.sum(residuals ** 2)
-        ss_tot = np.sum((y - np.mean(y)) ** 2)
-        r_squared = 1 - (ss_res / ss_tot) if ss_tot > 0 else 0.0
+        # Use unified OLS backend
+        coefficients, residuals, fitted, _ = solve_ols(
+            X, y, return_fitted=True, return_vcov=False
+        )
+        r_squared = compute_r_squared(y, residuals)
 
         return coefficients, residuals, fitted, r_squared
 
@@ -442,7 +430,7 @@ class DifferenceInDifferences:
         t_stat = bootstrap_results.t_stat_original
 
         # Also compute vcov for storage (using cluster-robust for consistency)
-        vcov = compute_robust_se(X, residuals, cluster_ids)
+        vcov = compute_robust_vcov(X, residuals, cluster_ids)
 
         return se, p_value, conf_int, t_stat, vcov, bootstrap_results
 
@@ -889,8 +877,11 @@ class MultiPeriodDiD(DifferenceInDifferences):
                     X = np.column_stack([X, dummies[col].values.astype(float)])
                     var_names.append(col)
 
-        # Fit OLS
-        coefficients, residuals, fitted, r_squared = self._fit_ols(X, y)
+        # Fit OLS using unified backend
+        coefficients, residuals, fitted, _ = solve_ols(
+            X, y, return_fitted=True, return_vcov=False
+        )
+        r_squared = compute_r_squared(y, residuals)
 
         # Degrees of freedom
         df = len(y) - X.shape[1] - n_absorbed_effects
@@ -900,13 +891,13 @@ class MultiPeriodDiD(DifferenceInDifferences):
         # For now, we use analytical inference even if inference="wild_bootstrap"
         if self.cluster is not None:
             cluster_ids = data[self.cluster].values
-            vcov = compute_robust_se(X, residuals, cluster_ids)
+            vcov = compute_robust_vcov(X, residuals, cluster_ids)
         elif self.robust:
-            vcov = compute_robust_se(X, residuals)
+            vcov = compute_robust_vcov(X, residuals)
         else:
             n = len(y)
             k = X.shape[1]
-            mse = np.sum(residuals ** 2) / (n - k)
+            mse = np.sum(residuals**2) / (n - k)
             # Use solve() instead of inv() for numerical stability
             # solve(A, B) computes X where AX=B, so this yields (X'X)^{-1} * mse
             vcov = np.linalg.solve(X.T @ X, mse * np.eye(k))

diff_diff-1.4.0/diff_diff/linalg.py

@@ -0,0 +1,271 @@
+"""
+Unified linear algebra backend for diff-diff.
+
+This module provides optimized OLS and variance estimation that can be
+swapped to a compiled backend (Rust/C++) for maximum performance.
+
+The key optimizations are:
+1. scipy.linalg.lstsq with 'gelsy' driver (QR-based, faster than SVD)
+2. Vectorized cluster-robust SE via groupby (eliminates O(n*clusters) loop)
+3. Single interface for all estimators (reduces code duplication)
+
+Future: This module can be extended with a Rust backend for additional speedup.
+"""
+
+from typing import Optional, Tuple, Union
+
+import numpy as np
+import pandas as pd
+from scipy.linalg import lstsq as scipy_lstsq
+
+
+def solve_ols(
+    X: np.ndarray,
+    y: np.ndarray,
+    *,
+    cluster_ids: Optional[np.ndarray] = None,
+    return_vcov: bool = True,
+    return_fitted: bool = False,
+    check_finite: bool = True,
+) -> Union[
+    Tuple[np.ndarray, np.ndarray, Optional[np.ndarray]],
+    Tuple[np.ndarray, np.ndarray, np.ndarray, Optional[np.ndarray]],
+]:
+    """
+    Solve OLS regression with optional clustered standard errors.
+
+    This is the unified OLS solver for all diff-diff estimators. It uses
+    scipy's optimized LAPACK routines and vectorized variance estimation.
+
+    Parameters
+    ----------
+    X : ndarray of shape (n, k)
+        Design matrix (should include intercept if desired).
+    y : ndarray of shape (n,)
+        Response vector.
+    cluster_ids : ndarray of shape (n,), optional
+        Cluster identifiers for cluster-robust standard errors.
+        If None, HC1 (heteroskedasticity-robust) SEs are computed.
+    return_vcov : bool, default True
+        Whether to compute and return the variance-covariance matrix.
+        Set to False for faster computation when SEs are not needed.
+    return_fitted : bool, default False
+        Whether to return fitted values in addition to residuals.
+    check_finite : bool, default True
+        Whether to check that X and y contain only finite values (no NaN/Inf).
+        Set to False for faster computation if you are certain your data is clean.
+
+    Returns
+    -------
+    coefficients : ndarray of shape (k,)
+        OLS coefficient estimates.
+    residuals : ndarray of shape (n,)
+        Residuals (y - X @ coefficients).
+    fitted : ndarray of shape (n,), optional
+        Fitted values (X @ coefficients). Only returned if return_fitted=True.
+    vcov : ndarray of shape (k, k) or None
+        Variance-covariance matrix (HC1 or cluster-robust).
+        None if return_vcov=False.
+
+    Notes
+    -----
+    This function uses scipy.linalg.lstsq with the 'gelsy' driver, which is
+    QR-based and typically faster than NumPy's default SVD-based solver for
+    well-conditioned matrices.
+
+    The cluster-robust standard errors use the sandwich estimator with the
+    standard small-sample adjustment: (G/(G-1)) * ((n-1)/(n-k)).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from diff_diff.linalg import solve_ols
+    >>> X = np.column_stack([np.ones(100), np.random.randn(100)])
+    >>> y = 2 + 3 * X[:, 1] + np.random.randn(100)
+    >>> coef, resid, vcov = solve_ols(X, y)
+    >>> print(f"Intercept: {coef[0]:.2f}, Slope: {coef[1]:.2f}")
+    """
+    # Validate inputs
+    X = np.asarray(X, dtype=np.float64)
+    y = np.asarray(y, dtype=np.float64)
+
+    if X.ndim != 2:
+        raise ValueError(f"X must be 2-dimensional, got shape {X.shape}")
+    if y.ndim != 1:
+        raise ValueError(f"y must be 1-dimensional, got shape {y.shape}")
+    if X.shape[0] != y.shape[0]:
+        raise ValueError(
+            f"X and y must have same number of observations: "
+            f"{X.shape[0]} vs {y.shape[0]}"
+        )
+
+    n, k = X.shape
+    if n < k:
+        raise ValueError(
+            f"Fewer observations ({n}) than parameters ({k}). "
+            "Cannot solve underdetermined system."
+        )
+
+    # Check for NaN/Inf values if requested
+    if check_finite:
+        if not np.isfinite(X).all():
+            raise ValueError(
+                "X contains NaN or Inf values. "
+                "Clean your data or set check_finite=False to skip this check."
+            )
+        if not np.isfinite(y).all():
+            raise ValueError(
+                "y contains NaN or Inf values. "
+                "Clean your data or set check_finite=False to skip this check."
+            )
+
+    # Solve OLS using scipy's optimized solver
+    # 'gelsy' uses QR with column pivoting, faster than default 'gelsd' (SVD)
+    # Note: gelsy doesn't reliably report rank, so we don't check for deficiency
+    coefficients = scipy_lstsq(X, y, lapack_driver="gelsy", check_finite=False)[0]
+
+    # Compute residuals and fitted values
+    fitted = X @ coefficients
+    residuals = y - fitted
+
+    # Compute variance-covariance matrix if requested
+    vcov = None
+    if return_vcov:
+        vcov = compute_robust_vcov(X, residuals, cluster_ids)
+
+    if return_fitted:
+        return coefficients, residuals, fitted, vcov
+    else:
+        return coefficients, residuals, vcov
+
+
+def compute_robust_vcov(
+    X: np.ndarray,
+    residuals: np.ndarray,
+    cluster_ids: Optional[np.ndarray] = None,
+) -> np.ndarray:
+    """
+    Compute heteroskedasticity-robust or cluster-robust variance-covariance matrix.
+
+    Uses the sandwich estimator: (X'X)^{-1} * meat * (X'X)^{-1}
+
+    Parameters
+    ----------
+    X : ndarray of shape (n, k)
+        Design matrix.
+    residuals : ndarray of shape (n,)
+        OLS residuals.
+    cluster_ids : ndarray of shape (n,), optional
+        Cluster identifiers. If None, computes HC1 robust SEs.
+
+    Returns
+    -------
+    vcov : ndarray of shape (k, k)
+        Variance-covariance matrix.
+
+    Notes
+    -----
+    For HC1 (no clustering):
+        meat = X' * diag(u^2) * X
+        adjustment = n / (n - k)
+
+    For cluster-robust:
+        meat = sum_g (X_g' u_g)(X_g' u_g)'
+        adjustment = (G / (G-1)) * ((n-1) / (n-k))
+
+    The cluster-robust computation is vectorized using pandas groupby,
+    which is much faster than a Python loop over clusters.
+    """
+    n, k = X.shape
+    XtX = X.T @ X
+
+    if cluster_ids is None:
+        # HC1 (heteroskedasticity-robust) standard errors
+        adjustment = n / (n - k)
+        u_squared = residuals**2
+        # Vectorized meat computation: X' diag(u^2) X = (X * u^2)' X
+        meat = X.T @ (X * u_squared[:, np.newaxis])
+    else:
+        # Cluster-robust standard errors (vectorized via groupby)
+        cluster_ids = np.asarray(cluster_ids)
+        unique_clusters = np.unique(cluster_ids)
+        n_clusters = len(unique_clusters)
+
+        if n_clusters < 2:
+            raise ValueError(
+                f"Need at least 2 clusters for cluster-robust SEs, got {n_clusters}"
+            )
+
+        # Small-sample adjustment
+        adjustment = (n_clusters / (n_clusters - 1)) * ((n - 1) / (n - k))
+
+        # Compute cluster-level scores: sum of X_i * u_i within each cluster
+        # scores[i] = X[i] * residuals[i] for each observation
+        scores = X * residuals[:, np.newaxis]  # (n, k)
+
+        # Sum scores within each cluster using pandas groupby (vectorized)
+        # This is much faster than looping over clusters
+        cluster_scores = pd.DataFrame(scores).groupby(cluster_ids).sum().values  # (G, k)
+
+        # Meat is the outer product sum: sum_g (score_g)(score_g)'
+        # Equivalent to cluster_scores.T @ cluster_scores
+        meat = cluster_scores.T @ cluster_scores  # (k, k)
+
+    # Sandwich estimator: (X'X)^{-1} meat (X'X)^{-1}
+    # Solve (X'X) temp = meat, then solve (X'X) vcov' = temp'
+    # More stable than explicit inverse
+    try:
+        temp = np.linalg.solve(XtX, meat)
+        vcov = adjustment * np.linalg.solve(XtX, temp.T).T
+    except np.linalg.LinAlgError as e:
+        if "Singular" in str(e):
+            raise ValueError(
+                "Design matrix is rank-deficient (singular X'X matrix). "
+                "This indicates perfect multicollinearity. Check your fixed effects "
+                "and covariates for linear dependencies."
+            ) from e
+        raise
+
+    return vcov
+
+
+def compute_r_squared(
+    y: np.ndarray,
+    residuals: np.ndarray,
+    adjusted: bool = False,
+    n_params: int = 0,
+) -> float:
+    """
+    Compute R-squared or adjusted R-squared.
+
+    Parameters
+    ----------
+    y : ndarray of shape (n,)
+        Response vector.
+    residuals : ndarray of shape (n,)
+        OLS residuals.
+    adjusted : bool, default False
+        If True, compute adjusted R-squared.
+    n_params : int, default 0
+        Number of parameters (including intercept). Required if adjusted=True.
+
+    Returns
+    -------
+    r_squared : float
+        R-squared or adjusted R-squared.
+    """
+    ss_res = np.sum(residuals**2)
+    ss_tot = np.sum((y - np.mean(y)) ** 2)
+
+    if ss_tot == 0:
+        return 0.0
+
+    r_squared = 1 - (ss_res / ss_tot)
+
+    if adjusted:
+        n = len(y)
+        if n <= n_params:
+            return r_squared
+        r_squared = 1 - (1 - r_squared) * (n - 1) / (n - n_params)
+
+    return r_squared

{diff_diff-1.3.0 → diff_diff-1.4.0}/diff_diff/results.py

@@ -507,6 +507,8 @@ class SyntheticDiDResults:
         List of pre-treatment period identifiers.
     post_periods : list
         List of post-treatment period identifiers.
+    variance_method : str
+        Method used for variance estimation: "bootstrap" or "placebo".
     """
 
     att: float
@@ -522,9 +524,11 @@ class SyntheticDiDResults:
     pre_periods: List[Any]
     post_periods: List[Any]
     alpha: float = 0.05
+    variance_method: str = field(default="bootstrap")
     lambda_reg: Optional[float] = field(default=None)
     pre_treatment_fit: Optional[float] = field(default=None)
     placebo_effects: Optional[np.ndarray] = field(default=None)
+    n_bootstrap: Optional[int] = field(default=None)
 
     def __repr__(self) -> str:
         """Concise string representation."""
@@ -571,6 +575,11 @@ class SyntheticDiDResults:
         if self.pre_treatment_fit is not None:
             lines.append(f"{'Pre-treatment fit (RMSE):':<25} {self.pre_treatment_fit:>10.4f}")
 
+        # Variance method info
+        lines.append(f"{'Variance method:':<25} {self.variance_method:>10}")
+        if self.variance_method == "bootstrap" and self.n_bootstrap is not None:
+            lines.append(f"{'Bootstrap replications:':<25} {self.n_bootstrap:>10}")
+
         lines.extend([
             "",
             "-" * 75,
@@ -624,7 +633,7 @@ class SyntheticDiDResults:
         Dict[str, Any]
             Dictionary containing all estimation results.
         """
-        return {
+        result = {
             "att": self.att,
             "se": self.se,
             "t_stat": self.t_stat,
@@ -636,9 +645,13 @@ class SyntheticDiDResults:
             "n_control": self.n_control,
             "n_pre_periods": len(self.pre_periods),
             "n_post_periods": len(self.post_periods),
+            "variance_method": self.variance_method,
             "lambda_reg": self.lambda_reg,
             "pre_treatment_fit": self.pre_treatment_fit,
         }
+        if self.n_bootstrap is not None:
+            result["n_bootstrap"] = self.n_bootstrap
+        return result
 
     def to_dataframe(self) -> pd.DataFrame:
         """