diff-diff 1.1.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

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/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/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/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}"