Merge pull request #42 from igerber/claude/implement-sun-abraham-estimator-GnbVC

Author: igerber

.github/workflows/claude-code-review.yml …orkflows/claude-code-review.yml.disabled.github/workflows/claude-code-review.yml renamed to .github/workflows/claude-code-review.yml.disabled .github/workflows/claude-code-review.yml renamed to .github/workflows/claude-code-review.yml.disabled

@@ -53,6 +53,13 @@ mypy diff_diff
   - `GroupTimeEffect` - Container for individual group-time effects
   - Multiplier bootstrap with Rademacher, Mammen, or Webb weights
 
+- **`diff_diff/sun_abraham.py`** - Sun-Abraham interaction-weighted estimator:
+  - `SunAbraham` - Sun & Abraham (2021) estimator using saturated regression
+  - `SunAbrahamResults` - Results with event study effects and cohort weights
+  - `SABootstrapResults` - Bootstrap inference results
+  - Alternative to Callaway-Sant'Anna with different weighting scheme
+  - Useful robustness check when both estimators agree
+
 - **`diff_diff/bacon.py`** - Goodman-Bacon decomposition for TWFE diagnostics:
   - `BaconDecomposition` - Decompose TWFE into weighted 2x2 comparisons (Goodman-Bacon 2021)
   - `BaconDecompositionResults` - Results with comparison weights and estimates by type
@@ -71,7 +78,7 @@ mypy diff_diff
   - `plot_honest_event_study` - Event study with honest confidence intervals
   - `plot_bacon` - Bacon decomposition scatter/bar plots (weights vs estimates by comparison type)
   - `plot_power_curve` - Power curve visualization (power vs effect size or sample size)
-  - Works with MultiPeriodDiD, CallawaySantAnna, HonestDiD, BaconDecomposition, PowerAnalysis, or DataFrames
+  - Works with MultiPeriodDiD, CallawaySantAnna, SunAbraham, HonestDiD, BaconDecomposition, PowerAnalysis, or DataFrames
 
 - **`diff_diff/utils.py`** - Statistical utilities:
   - Robust/cluster standard errors (`compute_robust_se`)
@@ -136,6 +143,7 @@ mypy diff_diff
 Tests mirror the source modules:
 - `tests/test_estimators.py` - Tests for DifferenceInDifferences, TWFE, MultiPeriodDiD, SyntheticDiD
 - `tests/test_staggered.py` - Tests for CallawaySantAnna
+- `tests/test_sun_abraham.py` - Tests for SunAbraham interaction-weighted estimator
 - `tests/test_bacon.py` - Tests for Goodman-Bacon decomposition
 - `tests/test_utils.py` - Tests for parallel trends, robust SE, synthetic weights
 - `tests/test_diagnostics.py` - Tests for placebo tests
@@ -148,3 +156,55 @@ Tests mirror the source modules:
 ### Dependencies
 
 Core dependencies are numpy, pandas, and scipy only (no statsmodels). The library implements its own OLS, robust standard errors, and inference.
+
+## Documentation Requirements
+
+When implementing new functionality, **always include accompanying documentation updates**:
+
+### For New Estimators or Major Features
+
+1. **README.md** - Add:
+   - Feature mention in the features list
+   - Full usage section with code examples
+   - Parameter documentation table
+   - API reference section (constructor params, fit() params, results attributes/methods)
+   - Scholarly references if applicable
+
+2. **docs/api/*.rst** - Add:
+   - RST documentation with `autoclass` directives
+   - Method summaries
+   - References to academic papers
+
+3. **docs/tutorials/*.ipynb** - Update relevant tutorial or create new one:
+   - Working code examples
+   - Explanation of when/why to use the feature
+   - Comparison with related functionality
+
+4. **CLAUDE.md** - Update:
+   - Module structure section
+   - Test structure section
+   - Any relevant design patterns
+
+5. **ROADMAP.md** - Update:
+   - Move implemented features from planned to current status
+   - Update version numbers
+
+### For Bug Fixes or Minor Enhancements
+
+- Update relevant docstrings
+- Add/update tests
+- Update CHANGELOG.md (if exists)
+
+### Scholarly References
+
+For methods based on academic papers, always include:
+- Full citation in README.md references section
+- Reference in RST docs with paper details
+- Citation in tutorial summary
+
+Example format:
+```
+Sun, L., & Abraham, S. (2021). Estimating dynamic treatment effects in
+event studies with heterogeneous treatment effects. *Journal of Econometrics*,
+225(2), 175-199.
+```

CLAUDE.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) 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
@@ -87,7 +87,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 |
@@ -762,12 +762,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()
@@ -779,7 +882,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({
@@ -1410,6 +1519,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

README.md

@@ -6,32 +6,22 @@ For past changes and release history, see [CHANGELOG.md](CHANGELOG.md).
 
 ---
 
-## Current Status (v1.0.2)
+## Current Status (v1.1.0)
 
 diff-diff is a **production-ready** DiD library with feature parity with R's `did` + `HonestDiD` ecosystem for core DiD analysis:
 
-- **Core estimators**: Basic DiD, TWFE, MultiPeriod, Callaway-Sant'Anna, Synthetic DiD
+- **Core estimators**: Basic DiD, TWFE, MultiPeriod, Callaway-Sant'Anna, Sun-Abraham, Synthetic DiD
 - **Valid inference**: Robust SEs, cluster SEs, wild bootstrap, multiplier bootstrap
 - **Assumption diagnostics**: Parallel trends tests, placebo tests, Goodman-Bacon decomposition
 - **Sensitivity analysis**: Honest DiD (Rambachan-Roth)
 - **Study design**: Power analysis tools
 
 ---
 
-## Near-Term Enhancements (v1.1–v1.2)
+## Near-Term Enhancements (v1.2)
 
 High-value additions building on our existing foundation.
 
-### Sun-Abraham Estimator
-
-Interaction-weighted estimator providing an alternative to Callaway-Sant'Anna. Many practitioners run both as a robustness check.
-
-- Event-study coefficients via saturated regression with cohort-time interactions
-- Different weighting scheme than CS; can give different results under heterogeneous effects
-- Useful robustness check when CS and SA agree
-
-**Reference**: Sun & Abraham (2021). *Journal of Econometrics*.
-
 ### Borusyak-Jaravel-Spiess Imputation Estimator
 
 More efficient than Callaway-Sant'Anna when treatment effects are homogeneous across groups/time. Uses imputation rather than aggregation.

ROADMAP.md

@@ -69,6 +69,11 @@
     CSBootstrapResults,
     GroupTimeEffect,
 )
+from diff_diff.sun_abraham import (
+    SABootstrapResults,
+    SunAbraham,
+    SunAbrahamResults,
+)
 from diff_diff.utils import (
     WildBootstrapResults,
     check_parallel_trends,
@@ -85,14 +90,15 @@
     plot_sensitivity,
 )
 
-__version__ = "1.0.2"
+__version__ = "1.1.0"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
     "TwoWayFixedEffects",
     "MultiPeriodDiD",
     "SyntheticDiD",
     "CallawaySantAnna",
+    "SunAbraham",
     # Bacon Decomposition
     "BaconDecomposition",
     "BaconDecompositionResults",
@@ -107,6 +113,8 @@
     "CallawaySantAnnaResults",
     "CSBootstrapResults",
     "GroupTimeEffect",
+    "SunAbrahamResults",
+    "SABootstrapResults",
     # Visualization
     "plot_event_study",
     "plot_group_effects",