diff-diff 0.6.0__tar.gz → 1.0.0__tar.gz

{diff_diff-0.6.0/diff_diff.egg-info → diff_diff-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 0.6.0
+Version: 1.0.0
 Summary: A library for Difference-in-Differences causal inference analysis
 Author: diff-diff contributors
 License-Expression: MIT
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://diff-diff.readthedocs.io
 Project-URL: Repository, https://github.com/igerber/diff-diff
 Project-URL: Issues, https://github.com/igerber/diff-diff/issues
 Keywords: causal-inference,difference-in-differences,econometrics,statistics,treatment-effects
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -109,8 +109,10 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 - **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
+- **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
 
 ## Tutorials
@@ -120,10 +122,11 @@ 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 |
+| `02_staggered_did.ipynb` | Staggered adoption with Callaway-Sant'Anna, 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 |
+| `06_power_analysis.ipynb` | Power analysis, MDE, sample size calculations, simulation-based power |
 
 ## Data Preparation
 
@@ -734,10 +737,48 @@ CallawaySantAnna(
     alpha=0.05,                      # Significance level
     cluster=None,                    # Column for cluster SEs
     n_bootstrap=0,                   # Bootstrap iterations (0 = analytical SEs)
+    bootstrap_weight_type='rademacher',  # 'rademacher', 'mammen', or 'webb'
     seed=None                        # Random seed
 )
 ```
 
+**Multiplier bootstrap for inference:**
+
+With few clusters or when analytical standard errors may be unreliable, use the multiplier bootstrap for valid inference. This implements the approach from Callaway & Sant'Anna (2021).
+
+```python
+# Bootstrap inference with 999 iterations
+cs = CallawaySantAnna(
+    n_bootstrap=999,
+    bootstrap_weight_type='rademacher',  # or 'mammen', 'webb'
+    seed=42
+)
+results = cs.fit(
+    data,
+    outcome='sales',
+    unit='firm_id',
+    time='year',
+    first_treat='first_treat',
+    aggregate='event_study'
+)
+
+# 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}")
+
+# Event study bootstrap inference
+for rel_time, se in results.bootstrap_results.event_study_ses.items():
+    ci = results.bootstrap_results.event_study_cis[rel_time]
+    print(f"e={rel_time}: SE={se:.3f}, 95% CI=[{ci[0]:.3f}, {ci[1]:.3f}]")
+```
+
+**Bootstrap weight types:**
+- `'rademacher'` - Default, ±1 with p=0.5, good for most cases
+- `'mammen'` - Two-point distribution matching first 3 moments
+- `'webb'` - Six-point distribution, recommended for very few clusters (<10)
+
 **Covariate adjustment for conditional parallel trends:**
 
 When parallel trends only holds conditional on covariates, use the `covariates` parameter:
@@ -756,9 +797,6 @@ results = cs.fit(
 )
 ```
 
-**Current limitations:**
-- Bootstrap inference (`n_bootstrap > 0`) is not yet fully implemented
-
 ### Event Study Visualization
 
 Create publication-ready event study plots:
@@ -1729,6 +1767,16 @@ The `HonestDiD` module implements sensitivity analysis methods for relaxing the
 
 - **Goodman-Bacon, A. (2021).** "Difference-in-Differences with Variation in Treatment Timing." *Journal of Econometrics*, 225(2), 254-277. [https://doi.org/10.1016/j.jeconom.2021.03.014](https://doi.org/10.1016/j.jeconom.2021.03.014)
 
+### Power Analysis
+
+- **Bloom, H. S. (1995).** "Minimum Detectable Effects: A Simple Way to Report the Statistical Power of Experimental Designs." *Evaluation Review*, 19(5), 547-556. [https://doi.org/10.1177/0193841X9501900504](https://doi.org/10.1177/0193841X9501900504)
+
+- **Burlig, F., Preonas, L., & Woerman, M. (2020).** "Panel Data and Experimental Design." *Journal of Development Economics*, 144, 102458. [https://doi.org/10.1016/j.jdeveco.2020.102458](https://doi.org/10.1016/j.jdeveco.2020.102458)
+
+  Essential reference for power analysis in panel DiD designs. Discusses how serial correlation (ICC) affects power and provides formulas for panel data settings.
+
+- **Djimeu, E. W., & Houndolo, D.-G. (2016).** "Power Calculation for Causal Inference in Social Science: Sample Size and Minimum Detectable Effect Determination." *Journal of Development Effectiveness*, 8(4), 508-527. [https://doi.org/10.1080/19439342.2016.1244555](https://doi.org/10.1080/19439342.2016.1244555)
+
 ### General Causal Inference
 
 - **Imbens, G. W., & Rubin, D. B. (2015).** *Causal Inference for Statistics, Social, and Biomedical Sciences: An Introduction*. Cambridge University Press.

diff_diff-0.6.0/PKG-INFO → diff_diff-1.0.0/README.md

@@ -1,38 +1,3 @@
-Metadata-Version: 2.4
-Name: diff-diff
-Version: 0.6.0
-Summary: A library for Difference-in-Differences causal inference analysis
-Author: diff-diff contributors
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/igerber/diff-diff
-Project-URL: Documentation, https://diff-diff.readthedocs.io
-Project-URL: Repository, https://github.com/igerber/diff-diff
-Project-URL: Issues, https://github.com/igerber/diff-diff/issues
-Keywords: causal-inference,difference-in-differences,econometrics,statistics,treatment-effects
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Science/Research
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Scientific/Engineering :: Mathematics
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: numpy>=1.20.0
-Requires-Dist: pandas>=1.3.0
-Requires-Dist: scipy>=1.7.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.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"
-Requires-Dist: mypy>=1.0; extra == "dev"
-Provides-Extra: docs
-Requires-Dist: sphinx>=6.0; extra == "docs"
-Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
-
 # diff-diff
 
 A Python library for Difference-in-Differences (DiD) causal inference analysis with an sklearn-like API and statsmodels-style outputs.
@@ -109,8 +74,10 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 - **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
+- **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
 
 ## Tutorials
@@ -120,10 +87,11 @@ 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 |
+| `02_staggered_did.ipynb` | Staggered adoption with Callaway-Sant'Anna, 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 |
+| `06_power_analysis.ipynb` | Power analysis, MDE, sample size calculations, simulation-based power |
 
 ## Data Preparation
 
@@ -734,10 +702,48 @@ CallawaySantAnna(
     alpha=0.05,                      # Significance level
     cluster=None,                    # Column for cluster SEs
     n_bootstrap=0,                   # Bootstrap iterations (0 = analytical SEs)
+    bootstrap_weight_type='rademacher',  # 'rademacher', 'mammen', or 'webb'
     seed=None                        # Random seed
 )
 ```
 
+**Multiplier bootstrap for inference:**
+
+With few clusters or when analytical standard errors may be unreliable, use the multiplier bootstrap for valid inference. This implements the approach from Callaway & Sant'Anna (2021).
+
+```python
+# Bootstrap inference with 999 iterations
+cs = CallawaySantAnna(
+    n_bootstrap=999,
+    bootstrap_weight_type='rademacher',  # or 'mammen', 'webb'
+    seed=42
+)
+results = cs.fit(
+    data,
+    outcome='sales',
+    unit='firm_id',
+    time='year',
+    first_treat='first_treat',
+    aggregate='event_study'
+)
+
+# 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}")
+
+# Event study bootstrap inference
+for rel_time, se in results.bootstrap_results.event_study_ses.items():
+    ci = results.bootstrap_results.event_study_cis[rel_time]
+    print(f"e={rel_time}: SE={se:.3f}, 95% CI=[{ci[0]:.3f}, {ci[1]:.3f}]")
+```
+
+**Bootstrap weight types:**
+- `'rademacher'` - Default, ±1 with p=0.5, good for most cases
+- `'mammen'` - Two-point distribution matching first 3 moments
+- `'webb'` - Six-point distribution, recommended for very few clusters (<10)
+
 **Covariate adjustment for conditional parallel trends:**
 
 When parallel trends only holds conditional on covariates, use the `covariates` parameter:
@@ -756,9 +762,6 @@ results = cs.fit(
 )
 ```
 
-**Current limitations:**
-- Bootstrap inference (`n_bootstrap > 0`) is not yet fully implemented
-
 ### Event Study Visualization
 
 Create publication-ready event study plots:
@@ -1729,6 +1732,16 @@ The `HonestDiD` module implements sensitivity analysis methods for relaxing the
 
 - **Goodman-Bacon, A. (2021).** "Difference-in-Differences with Variation in Treatment Timing." *Journal of Econometrics*, 225(2), 254-277. [https://doi.org/10.1016/j.jeconom.2021.03.014](https://doi.org/10.1016/j.jeconom.2021.03.014)
 
+### Power Analysis
+
+- **Bloom, H. S. (1995).** "Minimum Detectable Effects: A Simple Way to Report the Statistical Power of Experimental Designs." *Evaluation Review*, 19(5), 547-556. [https://doi.org/10.1177/0193841X9501900504](https://doi.org/10.1177/0193841X9501900504)
+
+- **Burlig, F., Preonas, L., & Woerman, M. (2020).** "Panel Data and Experimental Design." *Journal of Development Economics*, 144, 102458. [https://doi.org/10.1016/j.jdeveco.2020.102458](https://doi.org/10.1016/j.jdeveco.2020.102458)
+
+  Essential reference for power analysis in panel DiD designs. Discusses how serial correlation (ICC) affects power and provides formulas for panel data settings.
+
+- **Djimeu, E. W., & Houndolo, D.-G. (2016).** "Power Calculation for Causal Inference in Social Science: Sample Size and Minimum Detectable Effect Determination." *Journal of Development Effectiveness*, 8(4), 508-527. [https://doi.org/10.1080/19439342.2016.1244555](https://doi.org/10.1080/19439342.2016.1244555)
+
 ### General Causal Inference
 
 - **Imbens, G. W., & Rubin, D. B. (2015).** *Causal Inference for Statistics, Social, and Biomedical Sciences: An Introduction*. Cambridge University Press.

{diff_diff-0.6.0 → diff_diff-1.0.0}/diff_diff/__init__.py

@@ -5,6 +5,12 @@ This library provides sklearn-like estimators for causal inference
 using the difference-in-differences methodology.
 """
 
+from diff_diff.bacon import (
+    BaconDecomposition,
+    BaconDecompositionResults,
+    Comparison2x2,
+    bacon_decompose,
+)
 from diff_diff.diagnostics import (
     PlaceboTestResults,
     leave_one_out_test,
@@ -30,6 +36,15 @@ from diff_diff.honest_did import (
     compute_honest_did,
     sensitivity_plot,
 )
+from diff_diff.power import (
+    PowerAnalysis,
+    PowerResults,
+    SimulationPowerResults,
+    compute_mde,
+    compute_power,
+    compute_sample_size,
+    simulate_power,
+)
 from diff_diff.prep import (
     aggregate_to_cohorts,
     balance_panel,
@@ -51,6 +66,7 @@ from diff_diff.results import (
 from diff_diff.staggered import (
     CallawaySantAnna,
     CallawaySantAnnaResults,
+    CSBootstrapResults,
     GroupTimeEffect,
 )
 from diff_diff.utils import (
@@ -61,13 +77,15 @@ from diff_diff.utils import (
     wild_bootstrap_se,
 )
 from diff_diff.visualization import (
+    plot_bacon,
     plot_event_study,
     plot_group_effects,
     plot_honest_event_study,
+    plot_power_curve,
     plot_sensitivity,
 )
 
-__version__ = "0.6.0"
+__version__ = "1.0.0"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -75,12 +93,19 @@ __all__ = [
     "MultiPeriodDiD",
     "SyntheticDiD",
     "CallawaySantAnna",
+    # Bacon Decomposition
+    "BaconDecomposition",
+    "BaconDecompositionResults",
+    "Comparison2x2",
+    "bacon_decompose",
+    "plot_bacon",
     # Results
     "DiDResults",
     "MultiPeriodDiDResults",
     "SyntheticDiDResults",
     "PeriodEffect",
     "CallawaySantAnnaResults",
+    "CSBootstrapResults",
     "GroupTimeEffect",
     # Visualization
     "plot_event_study",
@@ -122,4 +147,13 @@ __all__ = [
     "DeltaSDRM",
     "compute_honest_did",
     "sensitivity_plot",
+    # Power analysis
+    "PowerAnalysis",
+    "PowerResults",
+    "SimulationPowerResults",
+    "compute_mde",
+    "compute_power",
+    "compute_sample_size",
+    "simulate_power",
+    "plot_power_curve",
 ]