diff-diff 1.3.0__py3-none-any.whl → 1.3.1__py3-none-any.whl

diff_diff/__init__.py

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

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:
         """

diff_diff/synthetic_did.py

@@ -14,7 +14,6 @@ from diff_diff.results import SyntheticDiDResults
 from diff_diff.utils import (
     compute_confidence_interval,
     compute_p_value,
-    compute_placebo_effects,
     compute_sdid_estimator,
     compute_synthetic_weights,
     compute_time_weights,
@@ -46,9 +45,17 @@ class SyntheticDiD(DifferenceInDifferences):
         time weights (closer to standard DiD).
     alpha : float, default=0.05
         Significance level for confidence intervals.
+    variance_method : str, default="bootstrap"
+        Method for variance estimation:
+        - "bootstrap": Block bootstrap at unit level (default)
+        - "placebo": Placebo-based variance matching R's synthdid::vcov(method="placebo").
+          Implements Algorithm 4 from Arkhangelsky et al. (2021): randomly permutes
+          control units, designates N₁ as pseudo-treated, renormalizes original
+          weights for remaining pseudo-controls, and computes SDID estimate.
     n_bootstrap : int, default=200
-        Number of bootstrap replications for standard error estimation.
-        Set to 0 to use placebo-based inference instead.
+        Number of replications for variance estimation. Used for both:
+        - Bootstrap: Number of bootstrap samples
+        - Placebo: Number of random permutations (matches R's `replications` argument)
     seed : int, optional
         Random seed for reproducibility. If None (default), results
         will vary between runs.
@@ -125,15 +132,25 @@ class SyntheticDiD(DifferenceInDifferences):
         lambda_reg: float = 0.0,
         zeta: float = 1.0,
         alpha: float = 0.05,
+        variance_method: str = "bootstrap",
         n_bootstrap: int = 200,
         seed: Optional[int] = None
     ):
         super().__init__(robust=True, cluster=None, alpha=alpha)
         self.lambda_reg = lambda_reg
         self.zeta = zeta
+        self.variance_method = variance_method
         self.n_bootstrap = n_bootstrap
         self.seed = seed
 
+        # Validate variance_method
+        valid_methods = ("bootstrap", "placebo")
+        if variance_method not in valid_methods:
+            raise ValueError(
+                f"variance_method must be one of {valid_methods}, "
+                f"got '{variance_method}'"
+            )
+
         self._unit_weights = None
         self._time_weights = None
 
@@ -285,23 +302,27 @@ class SyntheticDiD(DifferenceInDifferences):
         synthetic_pre = Y_pre_control @ unit_weights
         pre_fit_rmse = np.sqrt(np.mean((Y_pre_treated_mean - synthetic_pre) ** 2))
 
-        # Compute standard errors
-        if self.n_bootstrap > 0:
-            se, placebo_effects = self._bootstrap_se(
+        # Compute standard errors based on variance_method
+        if self.variance_method == "bootstrap":
+            se, bootstrap_estimates = self._bootstrap_se(
                 working_data, outcome, unit, time,
                 pre_periods, post_periods, treated_units, control_units
             )
+            placebo_effects = bootstrap_estimates
+            inference_method = "bootstrap"
         else:
-            # Use placebo-based inference
-            placebo_effects = compute_placebo_effects(
+            # Use placebo-based variance (R's synthdid Algorithm 4)
+            se, placebo_effects = self._placebo_variance_se(
                 Y_pre_control,
                 Y_post_control,
                 Y_pre_treated_mean,
+                Y_post_treated_mean,
                 unit_weights,
                 time_weights,
-                control_units
+                n_treated=len(treated_units),
+                replications=self.n_bootstrap  # Reuse n_bootstrap for replications
             )
-            se = np.std(placebo_effects, ddof=1) if len(placebo_effects) > 1 else 0.0
+            inference_method = "placebo"
 
         # Compute test statistics
         if se > 0:
@@ -343,9 +364,11 @@ class SyntheticDiD(DifferenceInDifferences):
             pre_periods=pre_periods,
             post_periods=post_periods,
             alpha=self.alpha,
+            variance_method=inference_method,
             lambda_reg=self.lambda_reg,
             pre_treatment_fit=pre_fit_rmse,
-            placebo_effects=placebo_effects if len(placebo_effects) > 0 else None
+            placebo_effects=placebo_effects if len(placebo_effects) > 0 else None,
+            n_bootstrap=self.n_bootstrap if inference_method == "bootstrap" else None
         )
 
         self._unit_weights = unit_weights
@@ -544,12 +567,163 @@ class SyntheticDiD(DifferenceInDifferences):
 
         return se, bootstrap_estimates
 
+    def _placebo_variance_se(
+        self,
+        Y_pre_control: np.ndarray,
+        Y_post_control: np.ndarray,
+        Y_pre_treated_mean: np.ndarray,
+        Y_post_treated_mean: np.ndarray,
+        unit_weights: np.ndarray,
+        time_weights: np.ndarray,
+        n_treated: int,
+        replications: int = 200
+    ) -> Tuple[float, np.ndarray]:
+        """
+        Compute placebo-based variance matching R's synthdid methodology.
+
+        This implements Algorithm 4 from Arkhangelsky et al. (2021),
+        matching R's synthdid::vcov(method = "placebo"):
+
+        1. Randomly sample N₀ control indices (permutation)
+        2. Designate last N₁ as pseudo-treated, first (N₀-N₁) as pseudo-controls
+        3. Renormalize original unit weights for pseudo-controls
+        4. Compute SDID estimate using renormalized weights
+        5. Repeat `replications` times
+        6. SE = sqrt((r-1)/r) * sd(estimates)
+
+        Parameters
+        ----------
+        Y_pre_control : np.ndarray
+            Control outcomes in pre-treatment periods, shape (n_pre, n_control).
+        Y_post_control : np.ndarray
+            Control outcomes in post-treatment periods, shape (n_post, n_control).
+        Y_pre_treated_mean : np.ndarray
+            Mean treated outcomes in pre-treatment periods, shape (n_pre,).
+        Y_post_treated_mean : np.ndarray
+            Mean treated outcomes in post-treatment periods, shape (n_post,).
+        unit_weights : np.ndarray
+            Original unit weights from main estimation, shape (n_control,).
+        time_weights : np.ndarray
+            Time weights from main estimation, shape (n_pre,).
+        n_treated : int
+            Number of treated units in the original estimation.
+        replications : int, default=200
+            Number of placebo replications.
+
+        Returns
+        -------
+        tuple
+            (se, placebo_effects) where se is the standard error and
+            placebo_effects is the array of placebo treatment effects.
+
+        References
+        ----------
+        Arkhangelsky, D., Athey, S., Hirshberg, D. A., Imbens, G. W., & Wager, S.
+        (2021). Synthetic Difference-in-Differences. American Economic Review,
+        111(12), 4088-4118. Algorithm 4.
+        """
+        rng = np.random.default_rng(self.seed)
+        n_pre, n_control = Y_pre_control.shape
+
+        # Ensure we have enough controls for the split
+        n_pseudo_control = n_control - n_treated
+        if n_pseudo_control < 1:
+            warnings.warn(
+                f"Not enough control units ({n_control}) for placebo variance "
+                f"estimation with {n_treated} treated units. "
+                f"Consider using variance_method='bootstrap'.",
+                UserWarning,
+                stacklevel=3,
+            )
+            return 0.0, np.array([])
+
+        placebo_estimates = []
+
+        for _ in range(replications):
+            try:
+                # Random permutation of control indices (Algorithm 4, step 1)
+                perm = rng.permutation(n_control)
+
+                # Split into pseudo-controls and pseudo-treated (step 2)
+                pseudo_control_idx = perm[:n_pseudo_control]
+                pseudo_treated_idx = perm[n_pseudo_control:]
+
+                # Renormalize original weights for pseudo-controls (step 3)
+                # This keeps the relative importance from the main estimation
+                pseudo_weights = unit_weights[pseudo_control_idx]
+                weight_sum = pseudo_weights.sum()
+                if weight_sum > 0:
+                    pseudo_weights = pseudo_weights / weight_sum
+                else:
+                    # Fallback to uniform if weights sum to zero
+                    pseudo_weights = np.ones(n_pseudo_control) / n_pseudo_control
+
+                # Get pseudo-treated outcomes (mean across pseudo-treated units)
+                Y_pre_pseudo_treated = np.mean(
+                    Y_pre_control[:, pseudo_treated_idx], axis=1
+                )
+                Y_post_pseudo_treated = np.mean(
+                    Y_post_control[:, pseudo_treated_idx], axis=1
+                )
+
+                # Get pseudo-control outcomes
+                Y_pre_pseudo_control = Y_pre_control[:, pseudo_control_idx]
+                Y_post_pseudo_control = Y_post_control[:, pseudo_control_idx]
+
+                # Compute placebo SDID estimate (step 4)
+                tau = compute_sdid_estimator(
+                    Y_pre_pseudo_control,
+                    Y_post_pseudo_control,
+                    Y_pre_pseudo_treated,
+                    Y_post_pseudo_treated,
+                    pseudo_weights,
+                    time_weights
+                )
+                placebo_estimates.append(tau)
+
+            except (ValueError, LinAlgError, ZeroDivisionError):
+                # Skip failed iterations
+                continue
+
+        placebo_estimates = np.array(placebo_estimates)
+        n_successful = len(placebo_estimates)
+
+        if n_successful < 2:
+            warnings.warn(
+                f"Only {n_successful} placebo replications completed successfully. "
+                f"Standard error cannot be estimated reliably. "
+                f"Consider using variance_method='bootstrap' or increasing "
+                f"the number of control units.",
+                UserWarning,
+                stacklevel=3,
+            )
+            return 0.0, placebo_estimates
+
+        # Warn if many replications failed
+        failure_rate = 1 - (n_successful / replications)
+        if failure_rate > 0.05:
+            warnings.warn(
+                f"Only {n_successful}/{replications} placebo replications succeeded "
+                f"({failure_rate:.1%} failure rate). Standard errors may be unreliable.",
+                UserWarning,
+                stacklevel=3,
+            )
+
+        # Compute SE using R's formula: sqrt((r-1)/r) * sd(estimates)
+        # This matches synthdid::vcov.R exactly
+        se = np.sqrt((n_successful - 1) / n_successful) * np.std(
+            placebo_estimates, ddof=1
+        )
+
+        return se, placebo_estimates
+
     def get_params(self) -> Dict[str, Any]:
         """Get estimator parameters."""
         return {
             "lambda_reg": self.lambda_reg,
             "zeta": self.zeta,
             "alpha": self.alpha,
+            "variance_method": self.variance_method,
             "n_bootstrap": self.n_bootstrap,
             "seed": self.seed,
         }

{diff_diff-1.3.0.dist-info → diff_diff-1.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 1.3.0
+Version: 1.3.1
 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.dist-info → diff_diff-1.3.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-diff_diff/__init__.py,sha256=nFRs83ejpriyI1Umhx0-t6db6r8uQiK0c04vR0KTm7w,4361
+diff_diff/__init__.py,sha256=1Izex7iZprjS_UGqIJj6iw9fO17US6ZI1HRINYW_tsA,4361
 diff_diff/bacon.py,sha256=AgQOtGUN-gtMh8q6KsGmOiVF4uCCFG2IexbeKS0mBlQ,36819
 diff_diff/diagnostics.py,sha256=1yOKfauW9RP7alXYlaR8oq5tmol5T24idsfqzyAxBPQ,29572
 diff_diff/estimators.py,sha256=4Jj9xAnF39EWElweFoYUa91YnyELelT8mRDzZKZWj4E,35807
@@ -6,15 +6,15 @@ diff_diff/honest_did.py,sha256=J4l-JyHHhhBiUT-F9Wls_8kjhxWhEj-N3BOe02pv0AA,46925
 diff_diff/power.py,sha256=cpdbWG-lxqAKjeAoM_8Un8gYaDwADIeYdWUIkEBfXZg,42800
 diff_diff/prep.py,sha256=bTPXTWajBzdNVPcLQ_IBYjww63DhgS3Z37V9h5tsIgc,46985
 diff_diff/pretrends.py,sha256=NeYjTxC9s_iIj-3beYupiDAZROYaLjFIzbm-76XhqKk,36538
-diff_diff/results.py,sha256=qmostsUy7uqX2VjAT7qSUPS3W1q_K8bqBB2JuUri_-k,22097
+diff_diff/results.py,sha256=ymN7_WVd-XTzJGmuULO8Ryda929uBOJX0FQZ341iJek,22746
 diff_diff/staggered.py,sha256=DPx6VRlF67IryT8cXYq_gfdclQZEDHIYzQakR3OSvWA,69465
 diff_diff/sun_abraham.py,sha256=ux6igLILW7Y1bh3TK33P781ATUWJS4fkwrjnpTARPlU,41685
-diff_diff/synthetic_did.py,sha256=g_Es1H-Yi1UozGXyoW2ZDK8x7BrEEf73DWNqJD9mpGk,19303
+diff_diff/synthetic_did.py,sha256=PjVFvCWQeE0X_4YZhw8iKSkyoyS2LEy7-yiwIQQd4bE,26765
 diff_diff/triple_diff.py,sha256=Jb8ld5ME6E7uQNvS2pgNmi0kHY3WikrLWm4TjTe__xI,44679
 diff_diff/twfe.py,sha256=iB-hvmOQd97B5_3hWvoaYGCSfcwJbXfg6towhRYD_Bw,11931
 diff_diff/utils.py,sha256=F0vRZ32k065VsP4YcAcUdaF_dom834QOgYj3ZaGS2pI,44211
 diff_diff/visualization.py,sha256=1X074fUk_fZleAlHdSGYc-ihdShY9FJ6WoKmBFCV6oI,51537
-diff_diff-1.3.0.dist-info/METADATA,sha256=OCVwiWDzu4-PiXtli41wEGNa7funUpZi6Ufccq9Q1Qs,77591
-diff_diff-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-diff_diff-1.3.0.dist-info/top_level.txt,sha256=-7mAFgjEQIA2okDLHlh5pDwBQXnsO1Z85qvtHjZILoQ,10
-diff_diff-1.3.0.dist-info/RECORD,,
+diff_diff-1.3.1.dist-info/METADATA,sha256=nML3_aj-pgfeQiWsz7mOI0HRAczQc1nPPOSJkqqqpNw,77719
+diff_diff-1.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+diff_diff-1.3.1.dist-info/top_level.txt,sha256=-7mAFgjEQIA2okDLHlh5pDwBQXnsO1Z85qvtHjZILoQ,10
+diff_diff-1.3.1.dist-info/RECORD,,