Merge pull request #45 from igerber/claude/brainstorm-next-project-YjI2n

Author: igerber

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-01-07
+
+### Added
+- **Pre-Trends Power Analysis** (Roth 2022) for assessing informativeness of pre-trends tests
+  - `PreTrendsPower` class for computing power and minimum detectable violation (MDV)
+  - `PreTrendsPowerResults` dataclass with power, MDV, and test statistics
+  - `PreTrendsPowerCurve` for power curves across violation magnitudes
+  - `compute_pretrends_power()` and `compute_mdv()` convenience functions
+  - Multiple violation types: `linear`, `constant`, `last_period`, `custom`
+  - Integration with Honest DiD via `sensitivity_to_honest_did()` method
+  - `plot_pretrends_power()` visualization for power curves
+  - Tutorial notebook: `docs/tutorials/07_pretrends_power.ipynb`
+  - Full API documentation: `docs/api/pretrends.rst`
+
+**Reference**: Roth, J. (2022). "Pretest with Caution: Event-Study Estimates after Testing for Parallel Trends." *American Economic Review: Insights*, 4(3), 305-322.
+
+### Fixed
+- **Reference period handling in pre-trends analysis**: Fixed bug where reference period was incorrectly assigned `avg_se` instead of being excluded from power calculations. Now properly excludes the omitted reference period from the joint Wald test.
+
 ## [1.1.1] - 2026-01-06
 
 ### Fixed
@@ -215,6 +234,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `to_dict()` and `to_dataframe()` export methods
   - `is_significant` and `significance_stars` properties
 
+[1.2.0]: https://github.com/igerber/diff-diff/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/igerber/diff-diff/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/igerber/diff-diff/compare/v1.0.2...v1.1.0
 [1.0.2]: https://github.com/igerber/diff-diff/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/igerber/diff-diff/compare/v1.0.0...v1.0.1

CLAUDE.md

@@ -78,7 +78,8 @@ 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, SunAbraham, HonestDiD, BaconDecomposition, PowerAnalysis, or DataFrames
+  - `plot_pretrends_power` - Pre-trends test power curve (power vs violation magnitude)
+  - Works with MultiPeriodDiD, CallawaySantAnna, SunAbraham, HonestDiD, BaconDecomposition, PowerAnalysis, PreTrendsPower, or DataFrames
 
 - **`diff_diff/utils.py`** - Statistical utilities:
   - Robust/cluster standard errors (`compute_robust_se`)
@@ -110,6 +111,15 @@ mypy diff_diff
   - `simulate_power()` - Simulation-based power for any DiD estimator
   - `compute_mde()`, `compute_power()`, `compute_sample_size()` - Convenience functions
 
+- **`diff_diff/pretrends.py`** - Pre-trends power analysis (Roth 2022):
+  - `PreTrendsPower` - Main class for assessing informativeness of pre-trends tests
+  - `PreTrendsPowerResults` - Results with power and minimum detectable violation (MDV)
+  - `PreTrendsPowerCurve` - Power curve across violation magnitudes with plot method
+  - `compute_pretrends_power()` - Convenience function for quick power computation
+  - `compute_mdv()` - Convenience function for minimum detectable violation
+  - Violation types: 'linear', 'constant', 'last_period', 'custom'
+  - Integrates with HonestDiD for comprehensive sensitivity analysis
+
 - **`diff_diff/prep.py`** - Data preparation utilities:
   - `generate_did_data` - Create synthetic data with known treatment effect
   - `make_treatment_indicator`, `make_post_indicator` - Create binary indicators
@@ -137,6 +147,7 @@ mypy diff_diff
   - `04_parallel_trends.ipynb` - Parallel trends testing and diagnostics
   - `05_honest_did.ipynb` - Honest DiD sensitivity analysis for parallel trends violations
   - `06_power_analysis.ipynb` - Power analysis for study design, MDE, simulation-based power
+  - `07_pretrends_power.ipynb` - Pre-trends power analysis (Roth 2022), MDV, power curves
 
 ### Test Structure
 
@@ -152,6 +163,7 @@ Tests mirror the source modules:
 - `tests/test_visualization.py` - Tests for plotting functions
 - `tests/test_honest_did.py` - Tests for Honest DiD sensitivity analysis
 - `tests/test_power.py` - Tests for power analysis
+- `tests/test_pretrends.py` - Tests for pre-trends power analysis
 
 ### Dependencies
 

README.md

@@ -77,6 +77,7 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 - **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
 
@@ -1221,6 +1222,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).
@@ -1645,6 +1730,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

ROADMAP.md

@@ -6,19 +6,19 @@ For past changes and release history, see [CHANGELOG.md](CHANGELOG.md).
 
 ---
 
-## Current Status (v1.1.0)
+## Current Status (v1.2.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, 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)
+- **Sensitivity analysis**: Honest DiD (Rambachan-Roth), Pre-trends power analysis (Roth 2022)
 - **Study design**: Power analysis tools
 
 ---
 
-## Near-Term Enhancements (v1.2)
+## Near-Term Enhancements (v1.3)
 
 High-value additions building on our existing foundation.
 
@@ -53,16 +53,6 @@ Extends DiD to settings requiring a third differencing dimension. Common DDD imp
 
 **Reference**: [Ortiz-Villavicencio & Sant'Anna (2025)](https://arxiv.org/abs/2505.09942). *Working Paper*. R package: `triplediff`.
 
-### Pre-Trends Power Analysis
-
-Assess whether pre-trends tests have adequate power to detect meaningful parallel trends violations. Complements our Honest DiD implementation.
-
-- Minimum detectable violation size for pre-trends tests
-- Visualization of power against various violation magnitudes
-- Integration with existing parallel trends diagnostics
-
-**Reference**: [Roth (2022)](https://www.aeaweb.org/articles?id=10.1257/aeri.20210236). *AER: Insights*. R package: `pretrends`.
-
 ### Enhanced Visualization
 
 - Synthetic control weight visualization (bar chart of unit weights)
@@ -71,7 +61,7 @@ Assess whether pre-trends tests have adequate power to detect meaningful paralle
 
 ---
 
-## Medium-Term Enhancements (v1.3+)
+## Medium-Term Enhancements (v1.4+)
 
 Extending diff-diff to handle more complex settings.
 

diff_diff/__init__.py

@@ -45,6 +45,13 @@
     compute_sample_size,
     simulate_power,
 )
+from diff_diff.pretrends import (
+    PreTrendsPower,
+    PreTrendsPowerCurve,
+    PreTrendsPowerResults,
+    compute_mdv,
+    compute_pretrends_power,
+)
 from diff_diff.prep import (
     aggregate_to_cohorts,
     balance_panel,
@@ -87,10 +94,11 @@
     plot_group_effects,
     plot_honest_event_study,
     plot_power_curve,
+    plot_pretrends_power,
     plot_sensitivity,
 )
 
-__version__ = "1.1.1"
+__version__ = "1.2.0"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -164,4 +172,11 @@
     "compute_sample_size",
     "simulate_power",
     "plot_power_curve",
+    # Pre-trends power analysis
+    "PreTrendsPower",
+    "PreTrendsPowerResults",
+    "PreTrendsPowerCurve",
+    "compute_pretrends_power",
+    "compute_mdv",
+    "plot_pretrends_power",
 ]