diff-diff 2.7.6__tar.gz → 2.8.0__tar.gz

{diff_diff-2.7.6 → diff_diff-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 2.7.6
+Version: 2.8.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -45,6 +45,7 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Documentation, https://diff-diff.readthedocs.io
 Project-URL: Homepage, https://github.com/igerber/diff-diff
 Project-URL: Issues, https://github.com/igerber/diff-diff/issues
+Project-URL: Practitioner Guide, https://github.com/igerber/diff-diff/blob/main/docs/llms-practitioner.txt
 Project-URL: Repository, https://github.com/igerber/diff-diff
 
 # diff-diff
@@ -116,6 +117,14 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 ======================================================================
 ```
 
+## For AI Agents
+
+If you are an AI agent or LLM using this library, read [`docs/llms.txt`](docs/llms.txt) for a concise API reference with an 8-step practitioner workflow (based on Baker et al. 2025). The workflow ensures rigorous DiD analysis — not just calling `fit()`, but testing assumptions, running sensitivity analysis, and checking robustness.
+
+After estimation, call `practitioner_next_steps(results)` for context-aware guidance on remaining diagnostic steps.
+
+Detailed guide: [`docs/llms-practitioner.txt`](docs/llms-practitioner.txt)
+
 ## Features
 
 - **sklearn-like API**: Familiar `fit()` interface with `get_params()` and `set_params()`

{diff_diff-2.7.6 → diff_diff-2.8.0}/README.md

@@ -67,6 +67,14 @@ Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
 ======================================================================
 ```
 
+## For AI Agents
+
+If you are an AI agent or LLM using this library, read [`docs/llms.txt`](docs/llms.txt) for a concise API reference with an 8-step practitioner workflow (based on Baker et al. 2025). The workflow ensures rigorous DiD analysis — not just calling `fit()`, but testing assumptions, running sensitivity analysis, and checking robustness.
+
+After estimation, call `practitioner_next_steps(results)` for context-aware guidance on remaining diagnostic steps.
+
+Detailed guide: [`docs/llms-practitioner.txt`](docs/llms-practitioner.txt)
+
 ## Features
 
 - **sklearn-like API**: Familiar `fit()` interface with `get_params()` and `set_params()`

{diff_diff-2.7.6 → diff_diff-2.8.0}/diff_diff/__init__.py

@@ -3,6 +3,13 @@ diff-diff: A library for Difference-in-Differences analysis.
 
 This library provides sklearn-like estimators for causal inference
 using the difference-in-differences methodology.
+
+For rigorous analysis, follow the 8-step practitioner workflow in
+docs/llms-practitioner.txt (based on Baker et al. 2025). After
+estimation, call ``practitioner_next_steps(results)`` for context-aware
+guidance on remaining diagnostic steps.
+
+AI agent reference: docs/llms.txt
 """
 
 # Import backend detection from dedicated module (avoids circular imports)
@@ -81,6 +88,7 @@ from diff_diff.prep import (
     generate_factor_data,
     generate_panel_data,
     generate_staggered_data,
+    generate_staggered_ddd_data,
     make_post_indicator,
     make_treatment_indicator,
     rank_control_units,
@@ -133,6 +141,12 @@ from diff_diff.triple_diff import (
     TripleDifferenceResults,
     triple_difference,
 )
+from diff_diff.staggered_triple_diff import (
+    StaggeredTripleDifference,
+)
+from diff_diff.staggered_triple_diff_results import (
+    StaggeredTripleDiffResults,
+)
 from diff_diff.continuous_did import (
     ContinuousDiD,
     ContinuousDiDResults,
@@ -190,11 +204,12 @@ SA = SunAbraham
 BJS = ImputationDiD
 Gardner = TwoStageDiD
 DDD = TripleDifference
+SDDD = StaggeredTripleDifference
 Stacked = StackedDiD
 Bacon = BaconDecomposition
 EDiD = EfficientDiD
 
-__version__ = "2.7.6"
+__version__ = "2.8.0"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -220,6 +235,7 @@ __all__ = [
     "BJS",
     "Gardner",
     "DDD",
+    "SDDD",
     "Stacked",
     "Bacon",
     # Bacon Decomposition
@@ -247,6 +263,8 @@ __all__ = [
     "two_stage_did",
     "TripleDifferenceResults",
     "triple_difference",
+    "StaggeredTripleDifference",
+    "StaggeredTripleDiffResults",
     "TROPResults",
     "trop",
     "StackedDiDResults",
@@ -296,6 +314,7 @@ __all__ = [
     "generate_ddd_data",
     "generate_panel_data",
     "generate_event_study_data",
+    "generate_staggered_ddd_data",
     "generate_continuous_did_data",
     "create_event_time",
     "aggregate_to_cohorts",

{diff_diff-2.7.6 → diff_diff-2.8.0}/diff_diff/honest_did.py

@@ -22,11 +22,12 @@ from typing import Any, Dict, List, Literal, Optional, Tuple, Union
 
 import numpy as np
 import pandas as pd
-from scipy import optimize, stats
+from scipy import optimize
 
 from diff_diff.results import (
     MultiPeriodDiDResults,
 )
+from diff_diff.utils import _get_critical_value
 
 # =============================================================================
 # Delta Restriction Classes
@@ -193,6 +194,9 @@ class HonestDiDResults:
     original_results: Optional[Any] = field(default=None, repr=False)
     # Event study bounds (optional)
     event_study_bounds: Optional[Dict[Any, Dict[str, float]]] = field(default=None, repr=False)
+    # Survey design metadata (Phase 7d)
+    survey_metadata: Optional[Any] = field(default=None, repr=False)
+    df_survey: Optional[int] = field(default=None, repr=False)
 
     def __repr__(self) -> str:
         sig = "" if self.ci_lb <= 0 <= self.ci_ub else "*"
@@ -534,7 +538,7 @@ class SensitivityResults:
 
 def _extract_event_study_params(
     results: Union[MultiPeriodDiDResults, Any],
-) -> Tuple[np.ndarray, np.ndarray, int, int, List[Any], List[Any]]:
+) -> Tuple[np.ndarray, np.ndarray, int, int, List[Any], List[Any], Optional[int]]:
     """
     Extract event study parameters from results objects.
 
@@ -557,6 +561,8 @@ def _extract_event_study_params(
         Pre-period identifiers.
     post_periods : list
         Post-period identifiers.
+    df_survey : int or None
+        Survey degrees of freedom for t-distribution inference.
     """
     if isinstance(results, MultiPeriodDiDResults):
         # Extract from MultiPeriodDiD
@@ -606,7 +612,23 @@ def _extract_event_study_params(
             # Fallback: diagonal from SEs
             sigma = np.diag(np.array(ses) ** 2)
 
-        return beta_hat, sigma, num_pre_periods, num_post_periods, pre_periods, post_periods
+        # Extract survey df. Replicate designs with undefined df → sentinel 0.
+        df_survey = None
+        if hasattr(results, "survey_metadata") and results.survey_metadata is not None:
+            sm = results.survey_metadata
+            df_survey = getattr(sm, "df_survey", None)
+            if df_survey is None and getattr(sm, "replicate_method", None) is not None:
+                df_survey = 0
+
+        return (
+            beta_hat,
+            sigma,
+            num_pre_periods,
+            num_post_periods,
+            pre_periods,
+            post_periods,
+            df_survey,
+        )
 
     else:
         # Try CallawaySantAnnaResults
@@ -621,6 +643,22 @@ def _extract_event_study_params(
                         "event study effects."
                     )
 
+                # Warn if not using universal base period (R's HonestDiD requires it)
+                if getattr(results, "base_period", "universal") != "universal":
+                    import warnings
+
+                    warnings.warn(
+                        "HonestDiD sensitivity analysis on CallawaySantAnna results "
+                        "requires base_period='universal' for valid interpretation. "
+                        "With base_period='varying', pre-treatment coefficients use "
+                        "consecutive comparisons (not a common reference period), "
+                        "which changes the meaning of the parallel trends restriction. "
+                        "Re-run with CallawaySantAnna(base_period='universal') for "
+                        "methodologically valid HonestDiD bounds.",
+                        UserWarning,
+                        stacklevel=3,
+                    )
+
                 # Extract event study effects by relative time
                 # Filter out normalization constraints (n_groups=0) and non-finite SEs
                 event_effects = {
@@ -630,9 +668,35 @@ def _extract_event_study_params(
                 }
                 rel_times = sorted(event_effects.keys())
 
-                # Split into pre and post
-                pre_times = [t for t in rel_times if t < 0]
-                post_times = [t for t in rel_times if t >= 0]
+                # Infer the omitted reference period from the normalization
+                # marker injected by _aggregate_event_study for universal base.
+                # The reference has the exact signature: effect=0.0, se=NaN, n_groups=0.
+                # Other empty bins may also have n_groups=0 but with NaN effect.
+                ref_period = None
+                for t, data in results.event_study_effects.items():
+                    if (
+                        data.get("n_groups", 1) == 0
+                        and data.get("effect", None) == 0.0
+                        and not np.isfinite(data.get("se", 0.0))
+                    ):
+                        ref_period = t
+                        break
+
+                if ref_period is not None:
+                    # Universal base: split relative to the reference period
+                    pre_times = [t for t in rel_times if t < ref_period]
+                    post_times = [t for t in rel_times if t > ref_period]
+                else:
+                    # Varying base or no reference marker: split at t < 0 / t >= 0
+                    pre_times = [t for t in rel_times if t < 0]
+                    post_times = [t for t in rel_times if t >= 0]
+
+                if len(pre_times) == 0:
+                    raise ValueError(
+                        "No pre-period effects with finite estimates found in "
+                        "CallawaySantAnna event study. HonestDiD requires at "
+                        "least one identified pre-period coefficient."
+                    )
 
                 effects = []
                 ses = []
@@ -641,9 +705,100 @@ def _extract_event_study_params(
                     ses.append(event_effects[t]["se"])
 
                 beta_hat = np.array(effects)
-                sigma = np.diag(np.array(ses) ** 2)
 
-                return (beta_hat, sigma, len(pre_times), len(post_times), pre_times, post_times)
+                # Use full event-study VCV if available (Phase 7d),
+                # otherwise fall back to diagonal from SEs
+                if hasattr(results, "event_study_vcov") and results.event_study_vcov is not None:
+                    vcov = results.event_study_vcov
+                    # VCV is indexed by the aggregated event times (stored in
+                    # event_study_vcov_index), NOT by event_study_effects keys
+                    # (which may include an injected reference period).
+                    # Subset to match the surviving rel_times.
+                    vcov_index = getattr(results, "event_study_vcov_index", None)
+                    if vcov_index is not None and len(rel_times) < len(vcov_index):
+                        idx = [vcov_index.index(t) for t in rel_times if t in vcov_index]
+                        if len(idx) == len(rel_times):
+                            sigma = vcov[np.ix_(idx, idx)]
+                        else:
+                            sigma = np.diag(np.array(ses) ** 2)
+                    elif vcov.shape[0] == len(rel_times):
+                        sigma = vcov
+                    else:
+                        sigma = np.diag(np.array(ses) ** 2)
+                else:
+                    # No full VCV available. Check if this is a bootstrap fit
+                    # (VCV was cleared to prevent mixing analytical/bootstrap).
+                    if (
+                        hasattr(results, "bootstrap_results")
+                        and results.bootstrap_results is not None
+                    ):
+                        import warnings
+
+                        warnings.warn(
+                            "HonestDiD on bootstrap-fitted CallawaySantAnna results "
+                            "uses a diagonal covariance matrix (cross-event-time "
+                            "covariance is not available from bootstrap). For full "
+                            "covariance structure, use analytical SEs (n_bootstrap=0).",
+                            UserWarning,
+                            stacklevel=4,
+                        )
+                    sigma = np.diag(np.array(ses) ** 2)
+
+                # Validate the full event-time grid is consecutive.
+                # For universal base: exactly one gap for the omitted reference.
+                # For varying base: no gap expected (pre ends at -1, post starts at 0).
+                if pre_times and post_times:
+                    if ref_period is not None:
+                        # Universal: pre[-1]+1 = ref, ref+1 = post[0] → gap of 2
+                        ref_gap = post_times[0] - pre_times[-1]
+                        has_gap = ref_gap != 2
+                    else:
+                        # Varying: pre ends at -1, post starts at 0 → gap of 1
+                        ref_gap = post_times[0] - pre_times[-1]
+                        has_gap = ref_gap != 1
+                elif pre_times:
+                    has_gap = False  # only pre, no ref gap to check
+                elif post_times:
+                    has_gap = False  # only post, no ref gap to check
+                else:
+                    has_gap = False
+                # Also check within-block consecutiveness
+                for block in [pre_times, post_times]:
+                    if len(block) >= 2:
+                        for i in range(len(block) - 1):
+                            if block[i + 1] - block[i] != 1:
+                                has_gap = True
+                                break
+                if has_gap:
+                    raise ValueError(
+                        "HonestDiD requires a consecutive event-time grid "
+                        "around the omitted reference period. Retained "
+                        f"pre-periods {pre_times} and post-periods "
+                        f"{post_times} have gaps. This can happen when "
+                        "some event-study horizons have non-finite SEs. "
+                        "Ensure all event-study periods have valid estimates, "
+                        "or use balance_e to restrict to a balanced subset."
+                    )
+
+                # Extract survey df. For replicate designs with undefined df
+                # (rank <= 1), use sentinel df=0 so _get_critical_value returns
+                # NaN, matching the safe_inference contract.
+                df_survey = None
+                if hasattr(results, "survey_metadata") and results.survey_metadata is not None:
+                    sm = results.survey_metadata
+                    df_survey = getattr(sm, "df_survey", None)
+                    if df_survey is None and getattr(sm, "replicate_method", None) is not None:
+                        df_survey = 0  # undefined replicate df → NaN inference
+
+                return (
+                    beta_hat,
+                    sigma,
+                    len(pre_times),
+                    len(post_times),
+                    pre_times,
+                    post_times,
+                    df_survey,
+                )
         except ImportError:
             pass
 
@@ -860,7 +1015,13 @@ def _solve_bounds_lp(
     return lb, ub
 
 
-def _compute_flci(lb: float, ub: float, se: float, alpha: float = 0.05) -> Tuple[float, float]:
+def _compute_flci(
+    lb: float,
+    ub: float,
+    se: float,
+    alpha: float = 0.05,
+    df: Optional[int] = None,
+) -> Tuple[float, float]:
     """
     Compute Fixed Length Confidence Interval (FLCI).
 
@@ -877,6 +1038,9 @@ def _compute_flci(lb: float, ub: float, se: float, alpha: float = 0.05) -> Tuple
         Standard error of the estimator.
     alpha : float
         Significance level.
+    df : int, optional
+        Degrees of freedom. If provided, uses t-distribution critical value
+        instead of normal (for survey designs with df = n_PSU - n_strata).
 
     Returns
     -------
@@ -895,7 +1059,7 @@ def _compute_flci(lb: float, ub: float, se: float, alpha: float = 0.05) -> Tuple
     if not (0 < alpha < 1):
         raise ValueError(f"alpha must be between 0 and 1, got alpha={alpha}")
 
-    z = stats.norm.ppf(1 - alpha / 2)
+    z = _get_critical_value(alpha, df)
     ci_lb = lb - z * se
     ci_ub = ub + z * se
     return ci_lb, ci_ub
@@ -909,6 +1073,7 @@ def _compute_clf_ci(
     max_pre_violation: float,
     alpha: float = 0.05,
     n_draws: int = 1000,
+    df: Optional[int] = None,
 ) -> Tuple[float, float, float, float]:
     """
     Compute Conditional Least Favorable (C-LF) confidence interval.
@@ -931,6 +1096,8 @@ def _compute_clf_ci(
         Significance level.
     n_draws : int
         Number of Monte Carlo draws for conditional CI.
+    df : int, optional
+        Degrees of freedom for t-distribution critical value.
 
     Returns
     -------
@@ -956,7 +1123,7 @@ def _compute_clf_ci(
     ub = theta + bound
 
     # CI with estimation uncertainty
-    z = stats.norm.ppf(1 - alpha / 2)
+    z = _get_critical_value(alpha, df)
     ci_lb = lb - z * se
     ci_ub = ub + z * se
 
@@ -1086,7 +1253,7 @@ class HonestDiD:
         M = M if M is not None else self.M
 
         # Extract event study parameters
-        (beta_hat, sigma, num_pre, num_post, pre_periods, post_periods) = (
+        (beta_hat, sigma, num_pre, num_post, pre_periods, post_periods, df_survey) = (
             _extract_event_study_params(results)
         )
 
@@ -1137,22 +1304,41 @@ class HonestDiD:
         # Compute bounds based on method
         if self.method == "smoothness":
             lb, ub, ci_lb, ci_ub = self._compute_smoothness_bounds(
-                beta_post, sigma_post, l_vec, num_pre, num_post, M
+                beta_post, sigma_post, l_vec, num_pre, num_post, M, df=df_survey
             )
             ci_method = "FLCI"
 
         elif self.method == "relative_magnitude":
             lb, ub, ci_lb, ci_ub = self._compute_rm_bounds(
-                beta_post, sigma_post, l_vec, num_pre, num_post, M, pre_periods, results
+                beta_post,
+                sigma_post,
+                l_vec,
+                num_pre,
+                num_post,
+                M,
+                pre_periods,
+                results,
+                df=df_survey,
             )
             ci_method = "C-LF"
 
         else:  # combined
             lb, ub, ci_lb, ci_ub = self._compute_combined_bounds(
-                beta_post, sigma_post, l_vec, num_pre, num_post, M, pre_periods, results
+                beta_post,
+                sigma_post,
+                l_vec,
+                num_pre,
+                num_post,
+                M,
+                pre_periods,
+                results,
+                df=df_survey,
             )
             ci_method = "FLCI"
 
+        # Extract survey_metadata for storage on results
+        survey_metadata = getattr(results, "survey_metadata", None)
+
         return HonestDiDResults(
             lb=lb,
             ub=ub,
@@ -1165,6 +1351,8 @@ class HonestDiD:
             alpha=self.alpha,
             ci_method=ci_method,
             original_results=results,
+            survey_metadata=survey_metadata,
+            df_survey=df_survey,
         )
 
     def _compute_smoothness_bounds(
@@ -1175,6 +1363,7 @@ class HonestDiD:
         num_pre: int,
         num_post: int,
         M: float,
+        df: Optional[int] = None,
     ) -> Tuple[float, float, float, float]:
         """Compute bounds under smoothness restriction."""
         # Construct constraints
@@ -1185,7 +1374,7 @@ class HonestDiD:
 
         # Compute FLCI
         se = np.sqrt(l_vec @ sigma_post @ l_vec)
-        ci_lb, ci_ub = _compute_flci(lb, ub, se, self.alpha)
+        ci_lb, ci_ub = _compute_flci(lb, ub, se, self.alpha, df=df)
 
         return lb, ub, ci_lb, ci_ub
 
@@ -1199,6 +1388,7 @@ class HonestDiD:
         Mbar: float,
         pre_periods: List,
         results: Any,
+        df: Optional[int] = None,
     ) -> Tuple[float, float, float, float]:
         """Compute bounds under relative magnitudes restriction."""
         # Estimate max pre-period violation from pre-trends
@@ -1209,12 +1399,18 @@ class HonestDiD:
             # No pre-period violations detected - use point estimate
             theta = np.dot(l_vec, beta_post)
             se = np.sqrt(l_vec @ sigma_post @ l_vec)
-            z = stats.norm.ppf(1 - self.alpha / 2)
+            z = _get_critical_value(self.alpha, df)
             return theta, theta, theta - z * se, theta + z * se
 
         # Compute bounds
         lb, ub, ci_lb, ci_ub = _compute_clf_ci(
-            beta_post, sigma_post, l_vec, Mbar, max_pre_violation, self.alpha
+            beta_post,
+            sigma_post,
+            l_vec,
+            Mbar,
+            max_pre_violation,
+            self.alpha,
+            df=df,
         )
 
         return lb, ub, ci_lb, ci_ub
@@ -1229,16 +1425,17 @@ class HonestDiD:
         M: float,
         pre_periods: List,
         results: Any,
+        df: Optional[int] = None,
     ) -> Tuple[float, float, float, float]:
         """Compute bounds under combined smoothness + RM restriction."""
         # Get smoothness bounds
         lb_sd, ub_sd, _, _ = self._compute_smoothness_bounds(
-            beta_post, sigma_post, l_vec, num_pre, num_post, M
+            beta_post, sigma_post, l_vec, num_pre, num_post, M, df=df
         )
 
         # Get RM bounds (use M as Mbar for combined)
         lb_rm, ub_rm, _, _ = self._compute_rm_bounds(
-            beta_post, sigma_post, l_vec, num_pre, num_post, M, pre_periods, results
+            beta_post, sigma_post, l_vec, num_pre, num_post, M, pre_periods, results, df=df
         )
 
         # Combined bounds are intersection
@@ -1252,7 +1449,7 @@ class HonestDiD:
 
         # Compute FLCI on combined bounds
         se = np.sqrt(l_vec @ sigma_post @ l_vec)
-        ci_lb, ci_ub = _compute_flci(lb, ub, se, self.alpha)
+        ci_lb, ci_ub = _compute_flci(lb, ub, se, self.alpha, df=df)
 
         return lb, ub, ci_lb, ci_ub
 
@@ -1283,15 +1480,18 @@ class HonestDiD:
 
             if isinstance(results, CallawaySantAnnaResults):
                 if results.event_study_effects:
-                    # Filter out normalization constraints (n_groups=0, e.g. reference period)
+                    # Use the reference-aware pre_periods from _extract_event_study_params
+                    pre_set = set(pre_periods) if pre_periods else set()
                     pre_effects = [
                         abs(results.event_study_effects[t]["effect"])
                         for t in results.event_study_effects
-                        if t < 0 and results.event_study_effects[t].get("n_groups", 1) > 0
+                        if t in pre_set and results.event_study_effects[t].get("n_groups", 1) > 0
                     ]
                     if pre_effects:
                         return max(pre_effects)
-                return results.overall_se
+                # No valid pre-effects — should have been caught by
+                # _extract_event_study_params pre-period validation
+                return 0.0
         except ImportError:
             pass
 

{diff_diff-2.7.6 → diff_diff-2.8.0}/diff_diff/prep.py

@@ -25,6 +25,7 @@ from diff_diff.prep_dgp import (
     generate_ddd_data,
     generate_panel_data,
     generate_event_study_data,
+    generate_staggered_ddd_data,
 )
 
 # Constants for rank_control_units