diff-diff 2.6.1__tar.gz → 2.7.1__tar.gz

{diff_diff-2.6.1 → diff_diff-2.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 2.6.1
+Version: 2.7.1
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -58,7 +58,7 @@ pip install -e .
 
 ```python
 import pandas as pd
-from diff_diff import DifferenceInDifferences
+from diff_diff import DifferenceInDifferences  # or: DiD
 
 # Create sample data
 data = pd.DataFrame({
@@ -108,7 +108,7 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 - **Wild cluster bootstrap**: Valid inference with few clusters (<50) using Rademacher, Webb, or Mammen weights
 - **Panel data support**: Two-way fixed effects estimator for panel designs
 - **Multi-period analysis**: Event-study style DiD with period-specific treatment effects
-- **Staggered adoption**: Callaway-Sant'Anna (2021), Sun-Abraham (2021), Borusyak-Jaravel-Spiess (2024) imputation, Two-Stage DiD (Gardner 2022), and Stacked DiD (Wing, Freedman & Hollingsworth 2024) estimators for heterogeneous treatment timing
+- **Staggered adoption**: Callaway-Sant'Anna (2021), Sun-Abraham (2021), Borusyak-Jaravel-Spiess (2024) imputation, Two-Stage DiD (Gardner 2022), Stacked DiD (Wing, Freedman & Hollingsworth 2024), and Efficient DiD (Chen, Sant'Anna & Xie 2025) estimators for heterogeneous treatment timing
 - **Triple Difference (DDD)**: Ortiz-Villavicencio & Sant'Anna (2025) estimators with proper covariate handling
 - **Synthetic DiD**: Combined DiD with synthetic control for improved robustness
 - **Triply Robust Panel (TROP)**: Factor-adjusted DiD with synthetic weights (Athey et al. 2025)
@@ -122,6 +122,28 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 - **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))
 
+## Estimator Aliases
+
+All estimators have short aliases for convenience:
+
+| Alias | Full Name | Method |
+|-------|-----------|--------|
+| `DiD` | `DifferenceInDifferences` | Basic 2x2 DiD |
+| `TWFE` | `TwoWayFixedEffects` | Two-way fixed effects |
+| `EventStudy` | `MultiPeriodDiD` | Event study / multi-period |
+| `CS` | `CallawaySantAnna` | Callaway & Sant'Anna (2021) |
+| `SA` | `SunAbraham` | Sun & Abraham (2021) |
+| `BJS` | `ImputationDiD` | Borusyak, Jaravel & Spiess (2024) |
+| `Gardner` | `TwoStageDiD` | Gardner (2022) two-stage |
+| `SDiD` | `SyntheticDiD` | Synthetic DiD |
+| `DDD` | `TripleDifference` | Triple difference |
+| `CDiD` | `ContinuousDiD` | Continuous treatment DiD |
+| `Stacked` | `StackedDiD` | Stacked DiD |
+| `Bacon` | `BaconDecomposition` | Goodman-Bacon decomposition |
+| `EDiD` | `EfficientDiD` | Efficient DiD |
+
+`TROP` already uses its short canonical name and needs no alias.
+
 ## Tutorials
 
 We provide Jupyter notebook tutorials in `docs/tutorials/`:
@@ -141,6 +163,7 @@ We provide Jupyter notebook tutorials in `docs/tutorials/`:
 | `11_imputation_did.ipynb` | Imputation DiD (Borusyak et al. 2024), pre-trend test, efficiency comparison |
 | `12_two_stage_did.ipynb` | Two-Stage DiD (Gardner 2022), GMM sandwich variance, per-observation effects |
 | `13_stacked_did.ipynb` | Stacked DiD (Wing et al. 2024), Q-weights, sub-experiment inspection, trimming, clean control definitions |
+| `15_efficient_did.ipynb` | Efficient DiD (Chen et al. 2025), optimal weighting, PT-All vs PT-Post, efficiency gains, bootstrap inference |
 
 ## Data Preparation
 
@@ -1087,6 +1110,56 @@ results = stacked_did(
 )
 ```
 
+### Efficient DiD (Chen, Sant'Anna & Xie 2025)
+
+Efficient DiD achieves the semiparametric efficiency bound for ATT estimation in staggered adoption designs. It optimally weights across all valid comparison groups and baselines via the inverse covariance matrix Omega*, producing tighter confidence intervals than standard estimators like Callaway-Sant'Anna when the stronger PT-All assumption holds.
+
+```python
+from diff_diff import EfficientDiD, generate_staggered_data
+
+# Generate sample data
+data = generate_staggered_data(n_units=300, n_periods=10,
+                                cohort_periods=[4, 6, 8], seed=42)
+
+# Fit with PT-All (overidentified, tighter SEs)
+edid = EfficientDiD(pt_assumption="all")
+results = edid.fit(data, outcome='outcome', unit='unit',
+                   time='period', first_treat='first_treat',
+                   aggregate='all')
+results.print_summary()
+
+# PT-Post mode (matches CS for post-treatment effects)
+edid_post = EfficientDiD(pt_assumption="post")
+results_post = edid_post.fit(data, outcome='outcome', unit='unit',
+                              time='period', first_treat='first_treat')
+```
+
+**Parameters:**
+
+```python
+EfficientDiD(
+    pt_assumption='all',            # 'all' (overidentified) or 'post' (matches CS post-treatment ATT)
+    alpha=0.05,                     # Significance level
+    n_bootstrap=0,                  # Bootstrap iterations (0 = analytical only)
+    bootstrap_weights='rademacher', # 'rademacher', 'mammen', or 'webb'
+    seed=None,                      # Random seed
+    anticipation=0,                 # Anticipation periods
+)
+```
+
+> **Note:** Phase 1 supports the no-covariates path only. Use CallawaySantAnna with
+> `estimation_method='dr'` if you need covariate adjustment.
+
+**When to use Efficient DiD vs Callaway-Sant'Anna:**
+
+| Aspect | Efficient DiD | Callaway-Sant'Anna |
+|--------|--------------|-------------------|
+| Approach | Optimal EIF-based weighting | Separate 2x2 DiD aggregation |
+| PT assumption | PT-All (stronger) or PT-Post | Conditional PT |
+| Efficiency | Achieves semiparametric bound | Not efficient |
+| Covariates | Not yet (Phase 2) | Supported (OR, IPW, DR) |
+| When to choose | Maximum efficiency, PT-All credible | Covariates needed, weaker PT |
+
 ### Triple Difference (DDD)
 
 Triple Difference (DDD) is used when treatment requires satisfying two criteria: belonging to a treated **group** AND being in an eligible **partition**. The `TripleDifference` class implements the methodology from Ortiz-Villavicencio & Sant'Anna (2025), which correctly handles covariate adjustment (unlike naive implementations).

{diff_diff-2.6.1 → diff_diff-2.7.1}/README.md

@@ -20,7 +20,7 @@ pip install -e .
 
 ```python
 import pandas as pd
-from diff_diff import DifferenceInDifferences
+from diff_diff import DifferenceInDifferences  # or: DiD
 
 # Create sample data
 data = pd.DataFrame({
@@ -70,7 +70,7 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 - **Wild cluster bootstrap**: Valid inference with few clusters (<50) using Rademacher, Webb, or Mammen weights
 - **Panel data support**: Two-way fixed effects estimator for panel designs
 - **Multi-period analysis**: Event-study style DiD with period-specific treatment effects
-- **Staggered adoption**: Callaway-Sant'Anna (2021), Sun-Abraham (2021), Borusyak-Jaravel-Spiess (2024) imputation, Two-Stage DiD (Gardner 2022), and Stacked DiD (Wing, Freedman & Hollingsworth 2024) estimators for heterogeneous treatment timing
+- **Staggered adoption**: Callaway-Sant'Anna (2021), Sun-Abraham (2021), Borusyak-Jaravel-Spiess (2024) imputation, Two-Stage DiD (Gardner 2022), Stacked DiD (Wing, Freedman & Hollingsworth 2024), and Efficient DiD (Chen, Sant'Anna & Xie 2025) estimators for heterogeneous treatment timing
 - **Triple Difference (DDD)**: Ortiz-Villavicencio & Sant'Anna (2025) estimators with proper covariate handling
 - **Synthetic DiD**: Combined DiD with synthetic control for improved robustness
 - **Triply Robust Panel (TROP)**: Factor-adjusted DiD with synthetic weights (Athey et al. 2025)
@@ -84,6 +84,28 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 - **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))
 
+## Estimator Aliases
+
+All estimators have short aliases for convenience:
+
+| Alias | Full Name | Method |
+|-------|-----------|--------|
+| `DiD` | `DifferenceInDifferences` | Basic 2x2 DiD |
+| `TWFE` | `TwoWayFixedEffects` | Two-way fixed effects |
+| `EventStudy` | `MultiPeriodDiD` | Event study / multi-period |
+| `CS` | `CallawaySantAnna` | Callaway & Sant'Anna (2021) |
+| `SA` | `SunAbraham` | Sun & Abraham (2021) |
+| `BJS` | `ImputationDiD` | Borusyak, Jaravel & Spiess (2024) |
+| `Gardner` | `TwoStageDiD` | Gardner (2022) two-stage |
+| `SDiD` | `SyntheticDiD` | Synthetic DiD |
+| `DDD` | `TripleDifference` | Triple difference |
+| `CDiD` | `ContinuousDiD` | Continuous treatment DiD |
+| `Stacked` | `StackedDiD` | Stacked DiD |
+| `Bacon` | `BaconDecomposition` | Goodman-Bacon decomposition |
+| `EDiD` | `EfficientDiD` | Efficient DiD |
+
+`TROP` already uses its short canonical name and needs no alias.
+
 ## Tutorials
 
 We provide Jupyter notebook tutorials in `docs/tutorials/`:
@@ -103,6 +125,7 @@ We provide Jupyter notebook tutorials in `docs/tutorials/`:
 | `11_imputation_did.ipynb` | Imputation DiD (Borusyak et al. 2024), pre-trend test, efficiency comparison |
 | `12_two_stage_did.ipynb` | Two-Stage DiD (Gardner 2022), GMM sandwich variance, per-observation effects |
 | `13_stacked_did.ipynb` | Stacked DiD (Wing et al. 2024), Q-weights, sub-experiment inspection, trimming, clean control definitions |
+| `15_efficient_did.ipynb` | Efficient DiD (Chen et al. 2025), optimal weighting, PT-All vs PT-Post, efficiency gains, bootstrap inference |
 
 ## Data Preparation
 
@@ -1049,6 +1072,56 @@ results = stacked_did(
 )
 ```
 
+### Efficient DiD (Chen, Sant'Anna & Xie 2025)
+
+Efficient DiD achieves the semiparametric efficiency bound for ATT estimation in staggered adoption designs. It optimally weights across all valid comparison groups and baselines via the inverse covariance matrix Omega*, producing tighter confidence intervals than standard estimators like Callaway-Sant'Anna when the stronger PT-All assumption holds.
+
+```python
+from diff_diff import EfficientDiD, generate_staggered_data
+
+# Generate sample data
+data = generate_staggered_data(n_units=300, n_periods=10,
+                                cohort_periods=[4, 6, 8], seed=42)
+
+# Fit with PT-All (overidentified, tighter SEs)
+edid = EfficientDiD(pt_assumption="all")
+results = edid.fit(data, outcome='outcome', unit='unit',
+                   time='period', first_treat='first_treat',
+                   aggregate='all')
+results.print_summary()
+
+# PT-Post mode (matches CS for post-treatment effects)
+edid_post = EfficientDiD(pt_assumption="post")
+results_post = edid_post.fit(data, outcome='outcome', unit='unit',
+                              time='period', first_treat='first_treat')
+```
+
+**Parameters:**
+
+```python
+EfficientDiD(
+    pt_assumption='all',            # 'all' (overidentified) or 'post' (matches CS post-treatment ATT)
+    alpha=0.05,                     # Significance level
+    n_bootstrap=0,                  # Bootstrap iterations (0 = analytical only)
+    bootstrap_weights='rademacher', # 'rademacher', 'mammen', or 'webb'
+    seed=None,                      # Random seed
+    anticipation=0,                 # Anticipation periods
+)
+```
+
+> **Note:** Phase 1 supports the no-covariates path only. Use CallawaySantAnna with
+> `estimation_method='dr'` if you need covariate adjustment.
+
+**When to use Efficient DiD vs Callaway-Sant'Anna:**
+
+| Aspect | Efficient DiD | Callaway-Sant'Anna |
+|--------|--------------|-------------------|
+| Approach | Optimal EIF-based weighting | Separate 2x2 DiD aggregation |
+| PT assumption | PT-All (stronger) or PT-Post | Conditional PT |
+| Efficiency | Achieves semiparametric bound | Not efficient |
+| Covariates | Not yet (Phase 2) | Supported (OR, IPW, DR) |
+| When to choose | Maximum efficiency, PT-All credible | Covariates needed, weaker PT |
+
 ### Triple Difference (DDD)
 
 Triple Difference (DDD) is used when treatment requires satisfying two criteria: belonging to a treated **group** AND being in an eligible **partition**. The `TripleDifference` class implements the methodology from Ortiz-Villavicencio & Sant'Anna (2025), which correctly handles covariate adjustment (unlike naive implementations).

{diff_diff-2.6.1 → diff_diff-2.7.1}/diff_diff/__init__.py

@@ -128,6 +128,11 @@ from diff_diff.continuous_did import (
     ContinuousDiDResults,
     DoseResponseCurve,
 )
+from diff_diff.efficient_did import (
+    EfficientDiD,
+    EfficientDiDResults,
+    EDiDBootstrapResults,
+)
 from diff_diff.trop import (
     TROP,
     TROPResults,
@@ -172,8 +177,9 @@ Gardner = TwoStageDiD
 DDD = TripleDifference
 Stacked = StackedDiD
 Bacon = BaconDecomposition
+EDiD = EfficientDiD
 
-__version__ = "2.6.1"
+__version__ = "2.7.1"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -231,6 +237,11 @@ __all__ = [
     "trop",
     "StackedDiDResults",
     "stacked_did",
+    # EfficientDiD
+    "EfficientDiD",
+    "EfficientDiDResults",
+    "EDiDBootstrapResults",
+    "EDiD",
     # Visualization
     "plot_event_study",
     "plot_group_effects",

{diff_diff-2.6.1 → diff_diff-2.7.1}/diff_diff/bootstrap_utils.py

@@ -19,6 +19,7 @@ __all__ = [
     "compute_percentile_ci",
     "compute_bootstrap_pvalue",
     "compute_effect_bootstrap_stats",
+    "compute_effect_bootstrap_stats_batch",
 ]
 
 
@@ -277,3 +278,126 @@ def compute_effect_bootstrap_stats(
         original_effect, valid_dist, n_valid=len(valid_dist)
     )
     return se, ci, p_value
+
+
+def compute_effect_bootstrap_stats_batch(
+    original_effects: np.ndarray,
+    bootstrap_matrix: np.ndarray,
+    alpha: float = 0.05,
+) -> tuple:
+    """
+    Batch-compute bootstrap statistics for multiple effects at once.
+
+    Parameters
+    ----------
+    original_effects : np.ndarray
+        Array of original point estimates, shape (n_effects,).
+    bootstrap_matrix : np.ndarray
+        Bootstrap distributions, shape (n_bootstrap, n_effects).
+    alpha : float, default=0.05
+        Significance level.
+
+    Returns
+    -------
+    ses : np.ndarray
+        Bootstrap SEs for each effect.
+    ci_lowers : np.ndarray
+        Lower CI bounds for each effect.
+    ci_uppers : np.ndarray
+        Upper CI bounds for each effect.
+    p_values : np.ndarray
+        Bootstrap p-values for each effect.
+    """
+    n_bootstrap, n_effects = bootstrap_matrix.shape
+    ses = np.full(n_effects, np.nan)
+    ci_lowers = np.full(n_effects, np.nan)
+    ci_uppers = np.full(n_effects, np.nan)
+    p_values = np.full(n_effects, np.nan)
+
+    # Check for non-finite original effects
+    valid_effects = np.isfinite(original_effects)
+    if not np.any(valid_effects):
+        return ses, ci_lowers, ci_uppers, p_values
+
+    # Count valid bootstrap samples per effect
+    finite_mask = np.isfinite(bootstrap_matrix)  # (n_bootstrap, n_effects)
+    n_valid = finite_mask.sum(axis=0)  # (n_effects,)
+
+    # Determine which effects have enough valid samples
+    enough_valid = (n_valid >= n_bootstrap * 0.5) & valid_effects
+
+    if not np.any(enough_valid):
+        n_insufficient = int(np.sum(valid_effects))
+        if n_insufficient > 0:
+            warnings.warn(
+                f"{n_insufficient} effect(s) had too few valid bootstrap samples (<50%). "
+                "Returning NaN for SE/CI/p-value.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+        return ses, ci_lowers, ci_uppers, p_values
+
+    # Warn about subset with insufficient samples
+    n_insufficient = int(np.sum(valid_effects & ~enough_valid))
+    if n_insufficient > 0:
+        warnings.warn(
+            f"{n_insufficient} effect(s) had too few valid bootstrap samples (<50%). "
+            "Returning NaN for SE/CI/p-value.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+
+    # For effects with all-finite bootstraps (common case), use vectorized ops
+    all_finite = (n_valid == n_bootstrap) & enough_valid
+    if np.any(all_finite):
+        idx = np.where(all_finite)[0]
+        sub = bootstrap_matrix[:, idx]
+
+        # Vectorized SE: std across bootstrap dimension
+        batch_ses = np.std(sub, axis=0, ddof=1)
+
+        # Vectorized percentile CI
+        lower_pct = alpha / 2 * 100
+        upper_pct = (1 - alpha / 2) * 100
+        batch_ci = np.percentile(sub, [lower_pct, upper_pct], axis=0)
+
+        # Vectorized p-values
+        batch_p = np.empty(len(idx))
+        for j, eff_idx in enumerate(idx):
+            eff = original_effects[eff_idx]
+            if eff >= 0:
+                batch_p[j] = np.mean(sub[:, j] <= 0)
+            else:
+                batch_p[j] = np.mean(sub[:, j] >= 0)
+        batch_p = np.minimum(2 * batch_p, 1.0)
+        batch_p = np.maximum(batch_p, 1 / (n_bootstrap + 1))
+
+        # Guard: SE must be positive and finite
+        se_valid = np.isfinite(batch_ses) & (batch_ses > 0)
+        n_bad_se = int(np.sum(~se_valid))
+        if n_bad_se > 0:
+            warnings.warn(
+                f"{n_bad_se} effect(s) had non-finite or zero bootstrap SE. "
+                "Returning NaN for SE/CI/p-value.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+        ses[idx[se_valid]] = batch_ses[se_valid]
+        ci_lowers[idx[se_valid]] = batch_ci[0][se_valid]
+        ci_uppers[idx[se_valid]] = batch_ci[1][se_valid]
+        p_values[idx[se_valid]] = batch_p[se_valid]
+
+    # Handle effects with some non-finite bootstraps (rare) via scalar fallback
+    partial_valid = enough_valid & ~all_finite
+    if np.any(partial_valid):
+        for j in np.where(partial_valid)[0]:
+            se, ci, pv = compute_effect_bootstrap_stats(
+                original_effects[j], bootstrap_matrix[:, j], alpha=alpha,
+                context=f"effect {j}"
+            )
+            ses[j] = se
+            ci_lowers[j] = ci[0]
+            ci_uppers[j] = ci[1]
+            p_values[j] = pv
+
+    return ses, ci_lowers, ci_uppers, p_values