diff-diff 2.2.1__tar.gz → 2.3.1__tar.gz

{diff_diff-2.2.1 → diff_diff-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 2.2.1
+Version: 2.3.1
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -14,6 +14,7 @@ Requires-Dist: numpy>=1.20.0
 Requires-Dist: pandas>=1.3.0
 Requires-Dist: scipy>=1.7.0
 Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0 ; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
 Requires-Dist: black>=23.0 ; extra == 'dev'
 Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
@@ -106,7 +107,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) and Sun-Abraham (2021) estimators for heterogeneous treatment timing
+- **Staggered adoption**: Callaway-Sant'Anna (2021), Sun-Abraham (2021), and Borusyak-Jaravel-Spiess (2024) imputation 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)
@@ -915,6 +916,54 @@ print(f"Sun-Abraham ATT: {sa_results.overall_att:.3f}")
 # If results differ substantially, investigate heterogeneity
 ```
 
+### Borusyak-Jaravel-Spiess Imputation Estimator
+
+The Borusyak et al. (2024) imputation estimator is the **efficient** estimator for staggered DiD under parallel trends, producing ~50% shorter confidence intervals than Callaway-Sant'Anna and 2-3.5x shorter than Sun-Abraham under homogeneous treatment effects.
+
+```python
+from diff_diff import ImputationDiD, imputation_did
+
+# Basic usage
+est = ImputationDiD()
+results = est.fit(data, outcome='outcome', unit='unit',
+                  time='period', first_treat='first_treat')
+results.print_summary()
+
+# Event study
+results = est.fit(data, outcome='outcome', unit='unit',
+                  time='period', first_treat='first_treat',
+                  aggregate='event_study')
+
+# Pre-trend test (Equation 9)
+pt = results.pretrend_test(n_leads=3)
+print(f"F-stat: {pt['f_stat']:.3f}, p-value: {pt['p_value']:.4f}")
+
+# Convenience function
+results = imputation_did(data, 'outcome', 'unit', 'period', 'first_treat',
+                         aggregate='all')
+```
+
+```python
+ImputationDiD(
+    anticipation=0,         # Number of anticipation periods
+    alpha=0.05,             # Significance level
+    cluster=None,           # Cluster variable (defaults to unit)
+    n_bootstrap=0,          # Bootstrap iterations (0=analytical inference)
+    seed=None,              # Random seed
+    horizon_max=None,       # Max event-study horizon
+    aux_partition="cohort_horizon",  # Variance partition: "cohort_horizon", "cohort", "horizon"
+)
+```
+
+**When to use Imputation DiD vs Callaway-Sant'Anna:**
+
+| Aspect | Imputation DiD | Callaway-Sant'Anna |
+|--------|---------------|-------------------|
+| Efficiency | Most efficient under homogeneous effects | Less efficient but more robust to heterogeneity |
+| Control group | Always uses all untreated obs | Choice of never-treated or not-yet-treated |
+| Inference | Conservative variance (Theorem 3) | Multiplier bootstrap |
+| Pre-trends | Built-in F-test (Equation 9) | Separate testing |
+
 ### 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).
@@ -1151,11 +1200,12 @@ Use Synthetic DiD instead of standard DiD when:
 
 ```python
 SyntheticDiD(
-    lambda_reg=0.0,     # Regularization toward uniform weights (0 = no reg)
-    zeta=1.0,           # Time weight regularization (higher = more uniform)
-    alpha=0.05,         # Significance level
-    n_bootstrap=200,    # Bootstrap iterations for SE (0 = placebo-based)
-    seed=None           # Random seed for reproducibility
+    zeta_omega=None,        # Unit weight regularization (None = auto-computed from data)
+    zeta_lambda=None,       # Time weight regularization (None = auto-computed from data)
+    alpha=0.05,             # Significance level
+    variance_method="placebo",  # "placebo" (default, matches R) or "bootstrap"
+    n_bootstrap=200,        # Replications for SE estimation
+    seed=None               # Random seed for reproducibility
 )
 ```
 
@@ -1860,11 +1910,12 @@ MultiPeriodDiD(
 
 ```python
 SyntheticDiD(
-    lambda_reg=0.0,     # L2 regularization for unit weights
-    zeta=1.0,           # Regularization for time weights
-    alpha=0.05,         # Significance level for CIs
-    n_bootstrap=200,    # Bootstrap iterations for SE
-    seed=None           # Random seed for reproducibility
+    zeta_omega=None,        # Unit weight regularization (None = auto from data)
+    zeta_lambda=None,       # Time weight regularization (None = auto from data)
+    alpha=0.05,             # Significance level for CIs
+    variance_method="placebo",  # "placebo" (R default) or "bootstrap"
+    n_bootstrap=200,        # Replications for SE estimation
+    seed=None               # Random seed for reproducibility
 )
 ```
 
@@ -2036,6 +2087,60 @@ SunAbraham(
 | `print_summary(alpha)` | Print summary to stdout |
 | `to_dataframe(level)` | Convert to DataFrame ('event_study' or 'cohort') |
 
+### ImputationDiD
+
+```python
+ImputationDiD(
+    anticipation=0,                   # Periods of anticipation effects
+    alpha=0.05,                       # Significance level for CIs
+    cluster=None,                     # Column for cluster-robust SEs
+    n_bootstrap=0,                    # Bootstrap iterations (0 = analytical)
+    seed=None,                        # Random seed
+    rank_deficient_action='warn',     # 'warn', 'error', or 'silent'
+    horizon_max=None,                 # Max event-study horizon
+    aux_partition='cohort_horizon',   # Variance partition
+)
+```
+
+**fit() Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | DataFrame | Panel data |
+| `outcome` | str | Outcome variable column name |
+| `unit` | str | Unit identifier column |
+| `time` | str | Time period column |
+| `first_treat` | str | First treatment period column (0 for never-treated) |
+| `covariates` | list | Covariate column names |
+| `aggregate` | str | Aggregation: None, "event_study", "group", "all" |
+| `balance_e` | int | Balance event study to this many pre-treatment periods |
+
+### ImputationDiDResults
+
+**Attributes:**
+
+| Attribute | Description |
+|-----------|-------------|
+| `overall_att` | Overall average treatment effect on the treated |
+| `overall_se` | Standard error (conservative, Theorem 3) |
+| `overall_t_stat` | T-statistic |
+| `overall_p_value` | P-value for H0: ATT = 0 |
+| `overall_conf_int` | Confidence interval |
+| `event_study_effects` | Dict of relative time -> effect dict (if `aggregate='event_study'` or `'all'`) |
+| `group_effects` | Dict of cohort -> effect dict (if `aggregate='group'` or `'all'`) |
+| `treatment_effects` | DataFrame of unit-level imputed treatment effects |
+| `n_treated_obs` | Number of treated observations |
+| `n_untreated_obs` | Number of untreated observations |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `summary(alpha)` | Get formatted summary string |
+| `print_summary(alpha)` | Print summary to stdout |
+| `to_dataframe(level)` | Convert to DataFrame ('observation', 'event_study', 'group') |
+| `pretrend_test(n_leads)` | Run pre-trend F-test (Equation 9) |
+
 ### TripleDifference
 
 ```python
@@ -2500,6 +2605,14 @@ The `HonestDiD` module implements sensitivity analysis methods for relaxing the
 
 ### Multi-Period and Staggered Adoption
 
+- **Borusyak, K., Jaravel, X., & Spiess, J. (2024).** "Revisiting Event-Study Designs: Robust and Efficient Estimation." *Review of Economic Studies*, 91(6), 3253-3285. [https://doi.org/10.1093/restud/rdae007](https://doi.org/10.1093/restud/rdae007)
+
+  This paper introduces the imputation estimator implemented in our `ImputationDiD` class:
+  - **Efficient imputation**: OLS on untreated observations → impute counterfactuals → aggregate
+  - **Conservative variance**: Theorem 3 clustered variance estimator with auxiliary model
+  - **Pre-trend test**: Independent of treatment effect estimation (Proposition 9)
+  - **Efficiency gains**: ~50% shorter CIs than Callaway-Sant'Anna under homogeneous effects
+
 - **Callaway, B., & Sant'Anna, P. H. C. (2021).** "Difference-in-Differences with Multiple Time Periods." *Journal of Econometrics*, 225(2), 200-230. [https://doi.org/10.1016/j.jeconom.2020.12.001](https://doi.org/10.1016/j.jeconom.2020.12.001)
 
 - **Sant'Anna, P. H. C., & Zhao, J. (2020).** "Doubly Robust Difference-in-Differences Estimators." *Journal of Econometrics*, 219(1), 101-122. [https://doi.org/10.1016/j.jeconom.2020.06.003](https://doi.org/10.1016/j.jeconom.2020.06.003)

{diff_diff-2.2.1 → diff_diff-2.3.1}/README.md

@@ -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) and Sun-Abraham (2021) estimators for heterogeneous treatment timing
+- **Staggered adoption**: Callaway-Sant'Anna (2021), Sun-Abraham (2021), and Borusyak-Jaravel-Spiess (2024) imputation 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)
@@ -879,6 +879,54 @@ print(f"Sun-Abraham ATT: {sa_results.overall_att:.3f}")
 # If results differ substantially, investigate heterogeneity
 ```
 
+### Borusyak-Jaravel-Spiess Imputation Estimator
+
+The Borusyak et al. (2024) imputation estimator is the **efficient** estimator for staggered DiD under parallel trends, producing ~50% shorter confidence intervals than Callaway-Sant'Anna and 2-3.5x shorter than Sun-Abraham under homogeneous treatment effects.
+
+```python
+from diff_diff import ImputationDiD, imputation_did
+
+# Basic usage
+est = ImputationDiD()
+results = est.fit(data, outcome='outcome', unit='unit',
+                  time='period', first_treat='first_treat')
+results.print_summary()
+
+# Event study
+results = est.fit(data, outcome='outcome', unit='unit',
+                  time='period', first_treat='first_treat',
+                  aggregate='event_study')
+
+# Pre-trend test (Equation 9)
+pt = results.pretrend_test(n_leads=3)
+print(f"F-stat: {pt['f_stat']:.3f}, p-value: {pt['p_value']:.4f}")
+
+# Convenience function
+results = imputation_did(data, 'outcome', 'unit', 'period', 'first_treat',
+                         aggregate='all')
+```
+
+```python
+ImputationDiD(
+    anticipation=0,         # Number of anticipation periods
+    alpha=0.05,             # Significance level
+    cluster=None,           # Cluster variable (defaults to unit)
+    n_bootstrap=0,          # Bootstrap iterations (0=analytical inference)
+    seed=None,              # Random seed
+    horizon_max=None,       # Max event-study horizon
+    aux_partition="cohort_horizon",  # Variance partition: "cohort_horizon", "cohort", "horizon"
+)
+```
+
+**When to use Imputation DiD vs Callaway-Sant'Anna:**
+
+| Aspect | Imputation DiD | Callaway-Sant'Anna |
+|--------|---------------|-------------------|
+| Efficiency | Most efficient under homogeneous effects | Less efficient but more robust to heterogeneity |
+| Control group | Always uses all untreated obs | Choice of never-treated or not-yet-treated |
+| Inference | Conservative variance (Theorem 3) | Multiplier bootstrap |
+| Pre-trends | Built-in F-test (Equation 9) | Separate testing |
+
 ### 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).
@@ -1115,11 +1163,12 @@ Use Synthetic DiD instead of standard DiD when:
 
 ```python
 SyntheticDiD(
-    lambda_reg=0.0,     # Regularization toward uniform weights (0 = no reg)
-    zeta=1.0,           # Time weight regularization (higher = more uniform)
-    alpha=0.05,         # Significance level
-    n_bootstrap=200,    # Bootstrap iterations for SE (0 = placebo-based)
-    seed=None           # Random seed for reproducibility
+    zeta_omega=None,        # Unit weight regularization (None = auto-computed from data)
+    zeta_lambda=None,       # Time weight regularization (None = auto-computed from data)
+    alpha=0.05,             # Significance level
+    variance_method="placebo",  # "placebo" (default, matches R) or "bootstrap"
+    n_bootstrap=200,        # Replications for SE estimation
+    seed=None               # Random seed for reproducibility
 )
 ```
 
@@ -1824,11 +1873,12 @@ MultiPeriodDiD(
 
 ```python
 SyntheticDiD(
-    lambda_reg=0.0,     # L2 regularization for unit weights
-    zeta=1.0,           # Regularization for time weights
-    alpha=0.05,         # Significance level for CIs
-    n_bootstrap=200,    # Bootstrap iterations for SE
-    seed=None           # Random seed for reproducibility
+    zeta_omega=None,        # Unit weight regularization (None = auto from data)
+    zeta_lambda=None,       # Time weight regularization (None = auto from data)
+    alpha=0.05,             # Significance level for CIs
+    variance_method="placebo",  # "placebo" (R default) or "bootstrap"
+    n_bootstrap=200,        # Replications for SE estimation
+    seed=None               # Random seed for reproducibility
 )
 ```
 
@@ -2000,6 +2050,60 @@ SunAbraham(
 | `print_summary(alpha)` | Print summary to stdout |
 | `to_dataframe(level)` | Convert to DataFrame ('event_study' or 'cohort') |
 
+### ImputationDiD
+
+```python
+ImputationDiD(
+    anticipation=0,                   # Periods of anticipation effects
+    alpha=0.05,                       # Significance level for CIs
+    cluster=None,                     # Column for cluster-robust SEs
+    n_bootstrap=0,                    # Bootstrap iterations (0 = analytical)
+    seed=None,                        # Random seed
+    rank_deficient_action='warn',     # 'warn', 'error', or 'silent'
+    horizon_max=None,                 # Max event-study horizon
+    aux_partition='cohort_horizon',   # Variance partition
+)
+```
+
+**fit() Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | DataFrame | Panel data |
+| `outcome` | str | Outcome variable column name |
+| `unit` | str | Unit identifier column |
+| `time` | str | Time period column |
+| `first_treat` | str | First treatment period column (0 for never-treated) |
+| `covariates` | list | Covariate column names |
+| `aggregate` | str | Aggregation: None, "event_study", "group", "all" |
+| `balance_e` | int | Balance event study to this many pre-treatment periods |
+
+### ImputationDiDResults
+
+**Attributes:**
+
+| Attribute | Description |
+|-----------|-------------|
+| `overall_att` | Overall average treatment effect on the treated |
+| `overall_se` | Standard error (conservative, Theorem 3) |
+| `overall_t_stat` | T-statistic |
+| `overall_p_value` | P-value for H0: ATT = 0 |
+| `overall_conf_int` | Confidence interval |
+| `event_study_effects` | Dict of relative time -> effect dict (if `aggregate='event_study'` or `'all'`) |
+| `group_effects` | Dict of cohort -> effect dict (if `aggregate='group'` or `'all'`) |
+| `treatment_effects` | DataFrame of unit-level imputed treatment effects |
+| `n_treated_obs` | Number of treated observations |
+| `n_untreated_obs` | Number of untreated observations |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `summary(alpha)` | Get formatted summary string |
+| `print_summary(alpha)` | Print summary to stdout |
+| `to_dataframe(level)` | Convert to DataFrame ('observation', 'event_study', 'group') |
+| `pretrend_test(n_leads)` | Run pre-trend F-test (Equation 9) |
+
 ### TripleDifference
 
 ```python
@@ -2464,6 +2568,14 @@ The `HonestDiD` module implements sensitivity analysis methods for relaxing the
 
 ### Multi-Period and Staggered Adoption
 
+- **Borusyak, K., Jaravel, X., & Spiess, J. (2024).** "Revisiting Event-Study Designs: Robust and Efficient Estimation." *Review of Economic Studies*, 91(6), 3253-3285. [https://doi.org/10.1093/restud/rdae007](https://doi.org/10.1093/restud/rdae007)
+
+  This paper introduces the imputation estimator implemented in our `ImputationDiD` class:
+  - **Efficient imputation**: OLS on untreated observations → impute counterfactuals → aggregate
+  - **Conservative variance**: Theorem 3 clustered variance estimator with auxiliary model
+  - **Pre-trend test**: Independent of treatment effect estimation (Proposition 9)
+  - **Efficiency gains**: ~50% shorter CIs than Callaway-Sant'Anna under homogeneous effects
+
 - **Callaway, B., & Sant'Anna, P. H. C. (2021).** "Difference-in-Differences with Multiple Time Periods." *Journal of Econometrics*, 225(2), 200-230. [https://doi.org/10.1016/j.jeconom.2020.12.001](https://doi.org/10.1016/j.jeconom.2020.12.001)
 
 - **Sant'Anna, P. H. C., & Zhao, J. (2020).** "Doubly Robust Difference-in-Differences Estimators." *Journal of Econometrics*, 219(1), 101-122. [https://doi.org/10.1016/j.jeconom.2020.06.003](https://doi.org/10.1016/j.jeconom.2020.06.003)

{diff_diff-2.2.1 → diff_diff-2.3.1}/diff_diff/__init__.py

@@ -95,6 +95,12 @@ from diff_diff.staggered import (
     CSBootstrapResults,
     GroupTimeEffect,
 )
+from diff_diff.imputation import (
+    ImputationBootstrapResults,
+    ImputationDiD,
+    ImputationDiDResults,
+    imputation_did,
+)
 from diff_diff.sun_abraham import (
     SABootstrapResults,
     SunAbraham,
@@ -136,7 +142,7 @@ from diff_diff.datasets import (
     load_mpdta,
 )
 
-__version__ = "2.2.1"
+__version__ = "2.3.1"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -145,6 +151,7 @@ __all__ = [
     "SyntheticDiD",
     "CallawaySantAnna",
     "SunAbraham",
+    "ImputationDiD",
     "TripleDifference",
     "TROP",
     # Bacon Decomposition
@@ -163,6 +170,9 @@ __all__ = [
     "GroupTimeEffect",
     "SunAbrahamResults",
     "SABootstrapResults",
+    "ImputationDiDResults",
+    "ImputationBootstrapResults",
+    "imputation_did",
     "TripleDifferenceResults",
     "triple_difference",
     "TROPResults",

{diff_diff-2.2.1 → diff_diff-2.3.1}/diff_diff/_backend.py

@@ -30,6 +30,11 @@ try:
         # TROP estimator acceleration (joint method)
         loocv_grid_search_joint as _rust_loocv_grid_search_joint,
         bootstrap_trop_variance_joint as _rust_bootstrap_trop_variance_joint,
+        # SDID weights (Frank-Wolfe matching R's synthdid)
+        compute_sdid_unit_weights as _rust_sdid_unit_weights,
+        compute_time_weights as _rust_compute_time_weights,
+        compute_noise_level as _rust_compute_noise_level,
+        sc_weight_fw as _rust_sc_weight_fw,
     )
     _rust_available = True
 except ImportError:
@@ -46,6 +51,11 @@ except ImportError:
     # TROP estimator acceleration (joint method)
     _rust_loocv_grid_search_joint = None
     _rust_bootstrap_trop_variance_joint = None
+    # SDID weights (Frank-Wolfe matching R's synthdid)
+    _rust_sdid_unit_weights = None
+    _rust_compute_time_weights = None
+    _rust_compute_noise_level = None
+    _rust_sc_weight_fw = None
 
 # Determine final backend based on environment variable and availability
 if _backend_env == 'python':
@@ -63,6 +73,11 @@ if _backend_env == 'python':
     # TROP estimator acceleration (joint method)
     _rust_loocv_grid_search_joint = None
     _rust_bootstrap_trop_variance_joint = None
+    # SDID weights (Frank-Wolfe matching R's synthdid)
+    _rust_sdid_unit_weights = None
+    _rust_compute_time_weights = None
+    _rust_compute_noise_level = None
+    _rust_sc_weight_fw = None
 elif _backend_env == 'rust':
     # Force Rust mode - fail if not available
     if not _rust_available:
@@ -89,4 +104,9 @@ __all__ = [
     # TROP estimator acceleration (joint method)
     '_rust_loocv_grid_search_joint',
     '_rust_bootstrap_trop_variance_joint',
+    # SDID weights (Frank-Wolfe matching R's synthdid)
+    '_rust_sdid_unit_weights',
+    '_rust_compute_time_weights',
+    '_rust_compute_noise_level',
+    '_rust_sc_weight_fw',
 ]