diff-diff 1.1.0__tar.gz → 1.2.1__tar.gz

{diff_diff-1.1.0 → diff_diff-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 1.1.0
+Version: 1.2.1
 Summary: A library for Difference-in-Differences causal inference analysis
 Author: diff-diff contributors
 License-Expression: MIT
@@ -112,6 +112,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
 
@@ -1256,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).
@@ -1680,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

{diff_diff-1.1.0 → diff_diff-1.2.1}/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

{diff_diff-1.1.0 → diff_diff-1.2.1}/diff_diff/__init__.py

@@ -45,6 +45,13 @@ from diff_diff.power import (
     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 @@ from diff_diff.visualization import (
     plot_group_effects,
     plot_honest_event_study,
     plot_power_curve,
+    plot_pretrends_power,
     plot_sensitivity,
 )
 
-__version__ = "1.1.0"
+__version__ = "1.2.1"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -164,4 +172,11 @@ __all__ = [
     "compute_sample_size",
     "simulate_power",
     "plot_power_curve",
+    # Pre-trends power analysis
+    "PreTrendsPower",
+    "PreTrendsPowerResults",
+    "PreTrendsPowerCurve",
+    "compute_pretrends_power",
+    "compute_mdv",
+    "plot_pretrends_power",
 ]

{diff_diff-1.1.0 → diff_diff-1.2.1}/diff_diff/diagnostics.py

@@ -625,11 +625,30 @@ def permutation_test(
             # Handle edge cases where fitting fails
             permuted_effects[i] = np.nan
 
-    # Remove any NaN values
+    # Remove any NaN values and track failure rate
     valid_effects = permuted_effects[~np.isnan(permuted_effects)]
+    n_failed = n_permutations - len(valid_effects)
 
     if len(valid_effects) == 0:
-        raise RuntimeError("All permutations failed - check your data")
+        raise RuntimeError(
+            f"All {n_permutations} permutations failed. This typically occurs when:\n"
+            f"  - Treatment/control groups are too small for valid permutation\n"
+            f"  - Data contains collinearity or singular matrices after permutation\n"
+            f"  - There are too few observations per time period\n"
+            f"Consider checking data quality with validate_did_data() from diff_diff.prep."
+        )
+
+    # Warn if significant number of permutations failed
+    if n_failed > 0:
+        failure_rate = n_failed / n_permutations
+        if failure_rate > 0.1:
+            import warnings
+            warnings.warn(
+                f"{n_failed}/{n_permutations} permutations failed ({failure_rate:.1%}). "
+                f"Results based on {len(valid_effects)} successful permutations.",
+                UserWarning,
+                stacklevel=2
+            )
 
     # Compute p-value: proportion of |permuted| >= |original|
     p_value = np.mean(np.abs(valid_effects) >= np.abs(original_att))
@@ -736,11 +755,30 @@ def leave_one_out_test(
             # Skip units that cause fitting issues
             loo_effects[u] = np.nan
 
-    # Remove NaN values for statistics
+    # Remove NaN values for statistics and track failures
     valid_effects = [v for v in loo_effects.values() if not np.isnan(v)]
+    n_total = len(loo_effects)
+    n_failed = n_total - len(valid_effects)
 
     if len(valid_effects) == 0:
-        raise RuntimeError("All leave-one-out estimates failed")
+        raise RuntimeError(
+            f"All {n_total} leave-one-out estimates failed. This typically occurs when:\n"
+            f"  - Removing any single treated unit causes model fitting to fail\n"
+            f"  - Very few treated units (need at least 2 for LOO)\n"
+            f"  - Data has collinearity issues that manifest when units are removed\n"
+            f"Consider checking data quality and ensuring sufficient treated units."
+        )
+
+    # Warn if significant number of LOO iterations failed
+    if n_failed > 0:
+        import warnings
+        failed_units = [u for u, v in loo_effects.items() if np.isnan(v)]
+        warnings.warn(
+            f"{n_failed}/{n_total} leave-one-out estimates failed for units: {failed_units}. "
+            f"Results based on {len(valid_effects)} successful iterations.",
+            UserWarning,
+            stacklevel=2
+        )
 
     # Statistics of LOO distribution
     mean_effect = np.mean(valid_effects)
@@ -838,8 +876,13 @@ def run_all_placebo_tests(
             )
             results[f"fake_timing_{period}"] = test_result
         except Exception as e:
-            # Store error info
-            results[f"fake_timing_{period}"] = {"error": str(e)}
+            # Store structured error info for debugging
+            results[f"fake_timing_{period}"] = {
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "test_type": "fake_timing",
+                "period": period
+            }
 
     # Permutation test
     try:
@@ -856,7 +899,11 @@ def run_all_placebo_tests(
         )
         results["permutation"] = perm_result
     except Exception as e:
-        results["permutation"] = {"error": str(e)}
+        results["permutation"] = {
+            "error": str(e),
+            "error_type": type(e).__name__,
+            "test_type": "permutation"
+        }
 
     # Leave-one-out test
     try:
@@ -871,6 +918,10 @@ def run_all_placebo_tests(
         )
         results["leave_one_out"] = loo_result
     except Exception as e:
-        results["leave_one_out"] = {"error": str(e)}
+        results["leave_one_out"] = {
+            "error": str(e),
+            "error_type": type(e).__name__,
+            "test_type": "leave_one_out"
+        }
 
     return results

{diff_diff-1.1.0 → diff_diff-1.2.1}/diff_diff/estimators.py

@@ -19,6 +19,7 @@ import pandas as pd
 
 from diff_diff.results import DiDResults, MultiPeriodDiDResults, PeriodEffect
 from diff_diff.utils import (
+    WildBootstrapResults,
     compute_confidence_interval,
     compute_p_value,
     compute_robust_se,
@@ -279,22 +280,9 @@ class DifferenceInDifferences:
         if self.inference == "wild_bootstrap" and self.cluster is not None:
             # Wild cluster bootstrap for few-cluster inference
             cluster_ids = data[self.cluster].values
-            bootstrap_results = wild_bootstrap_se(
-                X, y, residuals, cluster_ids,
-                coefficient_index=att_idx,
-                n_bootstrap=self.n_bootstrap,
-                weight_type=self.bootstrap_weights,
-                alpha=self.alpha,
-                seed=self.seed,
-                return_distribution=False
+            se, p_value, conf_int, t_stat, vcov, _ = self._run_wild_bootstrap_inference(
+                X, y, residuals, cluster_ids, att_idx
             )
-            self._bootstrap_results = bootstrap_results
-            se = bootstrap_results.se
-            p_value = bootstrap_results.p_value
-            conf_int = (bootstrap_results.ci_lower, bootstrap_results.ci_upper)
-            t_stat = bootstrap_results.t_stat_original
-            # Also compute vcov for storage (using cluster-robust for consistency)
-            vcov = compute_robust_se(X, residuals, cluster_ids)
         elif self.cluster is not None:
             cluster_ids = data[self.cluster].values
             vcov = compute_robust_se(X, residuals, cluster_ids)
@@ -408,6 +396,56 @@ class DifferenceInDifferences:
 
         return coefficients, residuals, fitted, r_squared
 
+    def _run_wild_bootstrap_inference(
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        residuals: np.ndarray,
+        cluster_ids: np.ndarray,
+        coefficient_index: int,
+    ) -> Tuple[float, float, Tuple[float, float], float, np.ndarray, WildBootstrapResults]:
+        """
+        Run wild cluster bootstrap inference.
+
+        Parameters
+        ----------
+        X : np.ndarray
+            Design matrix.
+        y : np.ndarray
+            Outcome vector.
+        residuals : np.ndarray
+            OLS residuals.
+        cluster_ids : np.ndarray
+            Cluster identifiers for each observation.
+        coefficient_index : int
+            Index of the coefficient to compute inference for.
+
+        Returns
+        -------
+        tuple
+            (se, p_value, conf_int, t_stat, vcov, bootstrap_results)
+        """
+        bootstrap_results = wild_bootstrap_se(
+            X, y, residuals, cluster_ids,
+            coefficient_index=coefficient_index,
+            n_bootstrap=self.n_bootstrap,
+            weight_type=self.bootstrap_weights,
+            alpha=self.alpha,
+            seed=self.seed,
+            return_distribution=False
+        )
+        self._bootstrap_results = bootstrap_results
+
+        se = bootstrap_results.se
+        p_value = bootstrap_results.p_value
+        conf_int = (bootstrap_results.ci_lower, bootstrap_results.ci_upper)
+        t_stat = bootstrap_results.t_stat_original
+
+        # Also compute vcov for storage (using cluster-robust for consistency)
+        vcov = compute_robust_se(X, residuals, cluster_ids)
+
+        return se, p_value, conf_int, t_stat, vcov, bootstrap_results
+
     def _parse_formula(
         self, formula: str, data: pd.DataFrame
     ) -> Tuple[str, str, str, Optional[List[str]]]:

{diff_diff-1.1.0 → diff_diff-1.2.1}/diff_diff/prep.py

@@ -601,7 +601,7 @@ def summarize_did_data(
     if len(time_vals) == 2:
         pre_val, post_val = time_vals[0], time_vals[1]
 
-        def format_label(x):
+        def format_label(x: tuple) -> str:
             treatment_label = 'Treated' if x[0] == 1 else 'Control'
             time_label = 'Post' if x[1] == post_val else 'Pre'
             return f"{treatment_label} - {time_label}"