diff-diff 1.0.0__tar.gz → 1.2.0__tar.gz

{diff_diff-1.0.0 → diff_diff-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 1.0.0
+Version: 1.2.0
 Summary: A library for Difference-in-Differences causal inference analysis
 Author: diff-diff contributors
 License-Expression: MIT
@@ -105,13 +105,14 @@ 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) estimator for heterogeneous treatment timing
+- **Staggered adoption**: Callaway-Sant'Anna (2021) and Sun-Abraham (2021) estimators for heterogeneous treatment timing
 - **Synthetic DiD**: Combined DiD with synthetic control for improved robustness
 - **Event study plots**: Publication-ready visualization of treatment effects
 - **Parallel trends testing**: Multiple methods including equivalence tests
 - **Goodman-Bacon decomposition**: Diagnose TWFE bias by decomposing into 2x2 comparisons
 - **Placebo tests**: Comprehensive diagnostics including fake timing, fake group, permutation, and leave-one-out tests
 - **Honest DiD sensitivity analysis**: Rambachan-Roth (2023) bounds and breakdown analysis for parallel trends violations
+- **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
 
@@ -122,7 +123,7 @@ We provide Jupyter notebook tutorials in `docs/tutorials/`:
 | Notebook | Description |
 |----------|-------------|
 | `01_basic_did.ipynb` | Basic 2x2 DiD, formula interface, covariates, fixed effects, cluster-robust SE, wild bootstrap |
-| `02_staggered_did.ipynb` | Staggered adoption with Callaway-Sant'Anna, group-time effects, aggregation methods, Bacon decomposition |
+| `02_staggered_did.ipynb` | Staggered adoption with Callaway-Sant'Anna and Sun-Abraham, group-time effects, aggregation methods, Bacon decomposition |
 | `03_synthetic_did.ipynb` | Synthetic DiD, unit/time weights, inference methods, regularization |
 | `04_parallel_trends.ipynb` | Testing parallel trends, equivalence tests, placebo tests, diagnostics |
 | `05_honest_did.ipynb` | Honest DiD sensitivity analysis, bounds, breakdown values, visualization |
@@ -574,7 +575,7 @@ Works with `DifferenceInDifferences` and `TwoWayFixedEffects` estimators.
 ### Two-Way Fixed Effects (Panel Data)
 
 ```python
-from diff_diff.estimators import TwoWayFixedEffects
+from diff_diff import TwoWayFixedEffects
 
 twfe = TwoWayFixedEffects()
 results = twfe.fit(
@@ -797,12 +798,115 @@ results = cs.fit(
 )
 ```
 
+### Sun-Abraham Interaction-Weighted Estimator
+
+The Sun-Abraham (2021) estimator provides an alternative to Callaway-Sant'Anna using an interaction-weighted (IW) regression approach. Running both estimators serves as a useful robustness check—when they agree, results are more credible.
+
+```python
+from diff_diff import SunAbraham
+
+# Basic usage
+sa = SunAbraham()
+results = sa.fit(
+    panel_data,
+    outcome='sales',
+    unit='firm_id',
+    time='year',
+    first_treat='first_treat'  # 0 for never-treated, else first treatment year
+)
+
+# View results
+results.print_summary()
+
+# Event study effects (by relative time to treatment)
+for rel_time, effect in results.event_study_effects.items():
+    print(f"e={rel_time}: {effect['effect']:.3f} (SE: {effect['se']:.3f})")
+
+# Overall ATT
+print(f"Overall ATT: {results.overall_att:.3f} (SE: {results.overall_se:.3f})")
+
+# Cohort weights (how each cohort contributes to each event-time estimate)
+for rel_time, weights in results.cohort_weights.items():
+    print(f"e={rel_time}: {weights}")
+```
+
+**Parameters:**
+
+```python
+SunAbraham(
+    control_group='never_treated',  # or 'not_yet_treated'
+    anticipation=0,                  # Periods before treatment with effects
+    alpha=0.05,                      # Significance level
+    cluster=None,                    # Column for cluster SEs
+    n_bootstrap=0,                   # Bootstrap iterations (0 = analytical SEs)
+    bootstrap_weights='rademacher',  # 'rademacher', 'mammen', or 'webb'
+    seed=None                        # Random seed
+)
+```
+
+**Bootstrap inference:**
+
+```python
+# Bootstrap inference with 999 iterations
+sa = SunAbraham(
+    n_bootstrap=999,
+    bootstrap_weights='rademacher',
+    seed=42
+)
+results = sa.fit(
+    data,
+    outcome='sales',
+    unit='firm_id',
+    time='year',
+    first_treat='first_treat'
+)
+
+# Access bootstrap results
+print(f"Overall ATT: {results.overall_att:.3f}")
+print(f"Bootstrap SE: {results.bootstrap_results.overall_att_se:.3f}")
+print(f"Bootstrap 95% CI: {results.bootstrap_results.overall_att_ci}")
+print(f"Bootstrap p-value: {results.bootstrap_results.overall_att_p_value:.4f}")
+```
+
+**When to use Sun-Abraham vs Callaway-Sant'Anna:**
+
+| Aspect | Sun-Abraham | Callaway-Sant'Anna |
+|--------|-------------|-------------------|
+| Approach | Interaction-weighted regression | 2x2 DiD aggregation |
+| Efficiency | More efficient under homogeneous effects | More robust to heterogeneity |
+| Weighting | Weights by cohort share at each relative time | Weights by sample size |
+| Use case | Robustness check, regression-based inference | Primary staggered DiD estimator |
+
+**Both estimators should give similar results when:**
+- Treatment effects are relatively homogeneous across cohorts
+- Parallel trends holds
+
+**Running both as robustness check:**
+
+```python
+from diff_diff import CallawaySantAnna, SunAbraham
+
+# Callaway-Sant'Anna
+cs = CallawaySantAnna()
+cs_results = cs.fit(data, outcome='y', unit='unit', time='time', first_treat='first_treat')
+
+# Sun-Abraham
+sa = SunAbraham()
+sa_results = sa.fit(data, outcome='y', unit='unit', time='time', first_treat='first_treat')
+
+# Compare
+print(f"Callaway-Sant'Anna ATT: {cs_results.overall_att:.3f}")
+print(f"Sun-Abraham ATT: {sa_results.overall_att:.3f}")
+
+# If results differ substantially, investigate heterogeneity
+```
+
 ### Event Study Visualization
 
 Create publication-ready event study plots:
 
 ```python
-from diff_diff import plot_event_study, MultiPeriodDiD, CallawaySantAnna
+from diff_diff import plot_event_study, MultiPeriodDiD, CallawaySantAnna, SunAbraham
 
 # From MultiPeriodDiD
 did = MultiPeriodDiD()
@@ -814,7 +918,13 @@ plot_event_study(results, title="Treatment Effects Over Time")
 cs = CallawaySantAnna()
 results = cs.fit(data, outcome='y', unit='unit', time='period',
                  first_treat='first_treat', aggregate='event_study')
-plot_event_study(results, title="Staggered DiD Event Study")
+plot_event_study(results, title="Staggered DiD Event Study (CS)")
+
+# From SunAbraham
+sa = SunAbraham()
+results = sa.fit(data, outcome='y', unit='unit', time='period',
+                 first_treat='first_treat')
+plot_event_study(results, title="Staggered DiD Event Study (SA)")
 
 # From a DataFrame
 df = pd.DataFrame({
@@ -1147,6 +1257,90 @@ plot_sensitivity(sensitivity, title="Sensitivity to Parallel Trends Violations")
 plot_honest_event_study(event_results, honest_results)
 ```
 
+### Pre-Trends Power Analysis (Roth 2022)
+
+A passing pre-trends test doesn't mean parallel trends holds—it may just mean the test has low power. **Pre-Trends Power Analysis** (Roth 2022) answers: "What violations could my pre-trends test have detected?"
+
+```python
+from diff_diff import PreTrendsPower, MultiPeriodDiD
+
+# First, fit an event study
+did = MultiPeriodDiD()
+event_results = did.fit(
+    data,
+    outcome='outcome',
+    treatment='treated',
+    time='period',
+    post_periods=[5, 6, 7, 8, 9]
+)
+
+# Analyze pre-trends test power
+pt = PreTrendsPower(alpha=0.05, power=0.80)
+power_results = pt.fit(event_results)
+
+print(power_results.summary())
+print(f"Minimum Detectable Violation (MDV): {power_results.mdv:.4f}")
+print(f"Power to detect violations of size MDV: {power_results.power:.1%}")
+```
+
+**Key concepts:**
+
+- **Minimum Detectable Violation (MDV)**: Smallest violation magnitude that would be detected with your target power (e.g., 80%). Passing the pre-trends test does NOT rule out violations up to this size.
+- **Power**: Probability of detecting a violation of given size if it exists.
+- **Violation types**: Linear trend, constant violation, last-period only, or custom patterns.
+
+**Power curve visualization:**
+
+```python
+from diff_diff import plot_pretrends_power
+
+# Generate power curve across violation magnitudes
+curve = pt.power_curve(event_results)
+
+# Plot the power curve
+plot_pretrends_power(curve, title="Pre-Trends Test Power Curve")
+
+# Or from the curve object directly
+curve.plot()
+```
+
+**Different violation patterns:**
+
+```python
+# Linear trend violations (default) - most common assumption
+pt_linear = PreTrendsPower(violation_type='linear')
+
+# Constant violation in all pre-periods
+pt_constant = PreTrendsPower(violation_type='constant')
+
+# Violation only in the last pre-period (sharp break)
+pt_last = PreTrendsPower(violation_type='last_period')
+
+# Custom violation pattern
+custom_weights = np.array([0.1, 0.3, 0.6])  # Increasing violations
+pt_custom = PreTrendsPower(violation_type='custom', violation_weights=custom_weights)
+```
+
+**Combining with HonestDiD:**
+
+Pre-trends power analysis and HonestDiD are complementary:
+1. **Pre-trends power** tells you what the test could have detected
+2. **HonestDiD** tells you how robust your results are to violations
+
+```python
+from diff_diff import HonestDiD, PreTrendsPower
+
+# If MDV is large relative to your estimated effect, be cautious
+pt = PreTrendsPower()
+power_results = pt.fit(event_results)
+sensitivity = pt.sensitivity_to_honest_did(event_results)
+print(sensitivity['interpretation'])
+
+# Use HonestDiD for robust inference
+honest = HonestDiD(method='relative_magnitude', M=1.0)
+honest_results = honest.fit(event_results)
+```
+
 ### Placebo Tests
 
 Placebo tests help validate the parallel trends assumption by checking whether effects appear where they shouldn't (before treatment or in untreated groups).
@@ -1445,6 +1639,63 @@ SyntheticDiD(
 | `get_unit_weights_df()` | Get unit weights as DataFrame |
 | `get_time_weights_df()` | Get time weights as DataFrame |
 
+### SunAbraham
+
+```python
+SunAbraham(
+    control_group='never_treated',  # or 'not_yet_treated'
+    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 SEs)
+    bootstrap_weights='rademacher',  # 'rademacher', 'mammen', or 'webb'
+    seed=None                 # Random seed
+)
+```
+
+**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 | Column with first treatment period (0 for never-treated) |
+| `covariates` | list | Covariate column names |
+| `min_pre_periods` | int | Minimum pre-treatment periods to include |
+| `min_post_periods` | int | Minimum post-treatment periods to include |
+
+### SunAbrahamResults
+
+**Attributes:**
+
+| Attribute | Description |
+|-----------|-------------|
+| `event_study_effects` | Dict mapping relative time to effect info |
+| `overall_att` | Overall average treatment effect |
+| `overall_se` | Standard error of overall ATT |
+| `overall_t_stat` | T-statistic for overall ATT |
+| `overall_p_value` | P-value for overall ATT |
+| `overall_conf_int` | Confidence interval for overall ATT |
+| `cohort_weights` | Dict mapping relative time to cohort weights |
+| `groups` | List of treatment cohorts |
+| `time_periods` | List of all time periods |
+| `n_obs` | Total number of observations |
+| `n_treated_units` | Number of ever-treated units |
+| `n_control_units` | Number of never-treated units |
+| `is_significant` | Boolean for significance at alpha |
+| `significance_stars` | String of significance stars |
+| `bootstrap_results` | SABootstrapResults (if bootstrap enabled) |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `summary(alpha)` | Get formatted summary string |
+| `print_summary(alpha)` | Print summary to stdout |
+| `to_dataframe(level)` | Convert to DataFrame ('event_study' or 'cohort') |
+
 ### HonestDiD
 
 ```python
@@ -1514,6 +1765,81 @@ HonestDiD(
 | `plot(ax)` | Plot sensitivity analysis |
 | `to_dataframe()` | Convert to pandas DataFrame |
 
+### PreTrendsPower
+
+```python
+PreTrendsPower(
+    alpha=0.05,           # Significance level for pre-trends test
+    power=0.80,           # Target power for MDV calculation
+    violation_type='linear',  # 'linear', 'constant', 'last_period', 'custom'
+    violation_weights=None    # Custom weights (required if violation_type='custom')
+)
+```
+
+**fit() Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `results` | MultiPeriodDiDResults | Results from event study |
+| `M` | float | Specific violation magnitude to evaluate |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `fit(results, M)` | Compute power analysis for given event study |
+| `power_at(results, M)` | Compute power for specific violation magnitude |
+| `power_curve(results, M_grid, n_points)` | Compute power across range of M values |
+| `sensitivity_to_honest_did(results)` | Compare with HonestDiD analysis |
+
+### PreTrendsPowerResults
+
+**Attributes:**
+
+| Attribute | Description |
+|-----------|-------------|
+| `power` | Power to detect the specified violation |
+| `mdv` | Minimum detectable violation at target power |
+| `violation_magnitude` | Violation magnitude (M) tested |
+| `violation_type` | Type of violation pattern |
+| `alpha` | Significance level |
+| `target_power` | Target power level |
+| `n_pre_periods` | Number of pre-treatment periods |
+| `test_statistic` | Expected test statistic under violation |
+| `critical_value` | Critical value for pre-trends test |
+| `noncentrality` | Non-centrality parameter |
+| `is_informative` | Heuristic check if test is informative |
+| `power_adequate` | Whether power meets target |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `summary()` | Get formatted summary string |
+| `print_summary()` | Print summary to stdout |
+| `to_dict()` | Convert to dictionary |
+| `to_dataframe()` | Convert to pandas DataFrame |
+
+### PreTrendsPowerCurve
+
+**Attributes:**
+
+| Attribute | Description |
+|-----------|-------------|
+| `M_values` | Array of violation magnitudes |
+| `powers` | Array of power values |
+| `mdv` | Minimum detectable violation |
+| `alpha` | Significance level |
+| `target_power` | Target power level |
+| `violation_type` | Type of violation pattern |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `plot(ax, show_mdv, show_target)` | Plot power curve |
+| `to_dataframe()` | Convert to DataFrame with M and power columns |
+
 ### Data Preparation Functions
 
 #### generate_did_data