diff-diff 3.5.2__tar.gz → 3.5.3__tar.gz

{diff_diff-3.5.2 → diff_diff-3.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.5.2
+Version: 3.5.3
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent

{diff_diff-3.5.2 → diff_diff-3.5.3}/diff_diff/__init__.py

@@ -133,6 +133,7 @@ from diff_diff.prep import (
     generate_staggered_data,
     generate_staggered_ddd_data,
     generate_survey_did_data,
+    generate_synthetic_control_data,
     make_post_indicator,
     make_treatment_indicator,
     rank_control_units,
@@ -298,7 +299,7 @@ ETWFE = WooldridgeDiD
 DCDH = ChaisemartinDHaultfoeuille
 HAD = HeterogeneousAdoptionDiD
 
-__version__ = "3.5.2"
+__version__ = "3.5.3"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -426,6 +427,7 @@ __all__ = [
     "generate_survey_did_data",
     "generate_continuous_did_data",
     "generate_reversible_did_data",
+    "generate_synthetic_control_data",
     "create_event_time",
     "aggregate_survey",
     "aggregate_to_cohorts",

{diff_diff-3.5.2 → diff_diff-3.5.3}/diff_diff/estimators.py

@@ -23,7 +23,6 @@ from diff_diff.linalg import (
     LinearRegression,
     _expand_vcov_with_nan,
     compute_r_squared,
-    compute_robust_vcov,
     solve_ols,
 )
 from diff_diff.results import DiDResults, MultiPeriodDiDResults, PeriodEffect
@@ -99,6 +98,12 @@ class DifferenceInDifferences:
     bootstrap_weights : str, default="rademacher"
         Type of bootstrap weights: "rademacher" (standard), "webb"
         (recommended for <10 clusters), or "mammen" (skewness correction).
+    p_val_type : str, default="two-tailed"
+        Shape of the wild cluster bootstrap test (mirrors
+        ``fwildclusterboot::boottest``): "two-tailed" (test on ``|t|``,
+        two-tailed inverted CI — which may be asymmetric) or "equal-tailed"
+        (each tail at ``alpha/2``, equal-tailed CI). Only used when
+        ``inference="wild_bootstrap"``.
     seed : int, optional
         Random seed for reproducibility when using bootstrap inference.
         If None (default), results will vary between runs.
@@ -181,6 +186,7 @@ class DifferenceInDifferences:
         inference: str = "analytical",
         n_bootstrap: int = 999,
         bootstrap_weights: str = "rademacher",
+        p_val_type: str = "two-tailed",
         seed: Optional[int] = None,
         rank_deficient_action: str = "warn",
         conley_coords: Optional[Tuple[str, str]] = None,
@@ -208,6 +214,9 @@ class DifferenceInDifferences:
         self.inference = inference
         self.n_bootstrap = n_bootstrap
         self.bootstrap_weights = bootstrap_weights
+        # Test shape for wild cluster bootstrap (mirrors fwildclusterboot's
+        # p_val_type): "two-tailed" (default) or "equal-tailed".
+        self.p_val_type = p_val_type
         self.seed = seed
         self.rank_deficient_action = rank_deficient_action
         # Conley spatial-HAC parameters; column names (NOT array values) for
@@ -698,10 +707,12 @@ class DifferenceInDifferences:
         inference_method = "analytical"
         n_bootstrap_used = None
         n_clusters_used = None
+        p_val_type_used = None
         if self._bootstrap_results is not None:
             inference_method = "wild_bootstrap"
             n_bootstrap_used = self._bootstrap_results.n_bootstrap
             n_clusters_used = self._bootstrap_results.n_clusters
+            p_val_type_used = self._bootstrap_results.p_val_type
 
         # Store results
         self.results_ = DiDResults(
@@ -722,6 +733,7 @@ class DifferenceInDifferences:
             inference_method=inference_method,
             n_bootstrap=n_bootstrap_used,
             n_clusters=n_clusters_used,
+            p_val_type=p_val_type_used,
             survey_metadata=survey_metadata,
             # Report the family that actually produced the SE, which may be
             # the remapped "hc1" (CR1) under the legacy alias path, not the
@@ -804,6 +816,7 @@ class DifferenceInDifferences:
             alpha=self.alpha,
             seed=self.seed,
             return_distribution=False,
+            p_val_type=self.p_val_type,
         )
         self._bootstrap_results = bootstrap_results
 
@@ -812,8 +825,25 @@ class DifferenceInDifferences:
         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_vcov(X, residuals, cluster_ids)
+        # Also compute the cluster-robust vcov for storage. Use the rank-aware
+        # solve_ols path (silently dropping collinear nuisance columns and
+        # NaN-expanding the vcov for them), matching how wild_bootstrap_se itself
+        # handles rank-deficient full-dummy designs — `compute_robust_vcov()`
+        # inverts the full X'X directly and would raise (or return garbage) on a
+        # rank-deficient design even though the ATT and bootstrap are identified.
+        # On a saturated design (degenerate bootstrap, NaN se) store a NaN vcov
+        # to keep the all-or-nothing NaN contract. (On a full-rank design this
+        # vcov is bit-identical to the prior compute_robust_vcov result.)
+        if np.isnan(se):
+            vcov = np.full((X.shape[1], X.shape[1]), np.nan)
+        else:
+            _, _, vcov = solve_ols(
+                X,
+                y,
+                cluster_ids=cluster_ids,
+                return_vcov=True,
+                rank_deficient_action="silent",
+            )
 
         return se, p_value, conf_int, t_stat, vcov, bootstrap_results
 
@@ -994,6 +1024,7 @@ class DifferenceInDifferences:
             "inference": self.inference,
             "n_bootstrap": self.n_bootstrap,
             "bootstrap_weights": self.bootstrap_weights,
+            "p_val_type": self.p_val_type,
             "seed": self.seed,
             "rank_deficient_action": self.rank_deficient_action,
             "conley_coords": self.conley_coords,
@@ -1319,6 +1350,9 @@ class MultiPeriodDiD(DifferenceInDifferences):
         # the analytical-fallback warning first would produce contradictory
         # guidance on the same call (warn "falling back" + raise "not
         # supported"). The Conley raise takes precedence. Codex CI R11 P3.
+        # NOTE: ``p_val_type`` is inherited from DifferenceInDifferences but is
+        # inert here — MultiPeriodDiD has no wild-bootstrap path (it falls back
+        # to analytical inference below), so the parameter has no effect.
         effective_inference = self.inference
         if self.inference == "wild_bootstrap" and self.vcov_type != "conley":
             warnings.warn(

{diff_diff-3.5.2 → diff_diff-3.5.3}/diff_diff/guides/llms-full.txt

@@ -2,7 +2,7 @@
 
 > A Python library for Difference-in-Differences causal inference analysis. Provides sklearn-like estimators with statsmodels-style output for econometric analysis.
 
-- Version: 3.5.2
+- Version: 3.5.3
 - Repository: https://github.com/igerber/diff-diff
 - License: MIT
 - Dependencies: numpy, pandas, scipy (no statsmodels dependency)
@@ -1956,6 +1956,7 @@ from diff_diff import (
     generate_factor_data,
     generate_ddd_data,
     generate_continuous_did_data,
+    generate_synthetic_control_data,
 )
 
 # Basic 2x2 DiD data
@@ -1985,6 +1986,11 @@ data = generate_ddd_data(n_per_cell=100, treatment_effect=2.0, seed=42)
 # Continuous dose data
 data = generate_continuous_did_data(n_units=500, n_periods=4,
                                     att_function="linear", att_slope=2.0, seed=42)
+
+# Single-treated-unit panel for synthetic control (noiseless treated path in the
+# donor convex hull; ramping or constant effect). Use with SyntheticControl.
+data = generate_synthetic_control_data(n_donors=20, n_pre=60, n_post=5,
+                                       effect_type="ramp", seed=0)
 ```
 
 ## Real-World Datasets

{diff_diff-3.5.2 → diff_diff-3.5.3}/diff_diff/linalg.py

@@ -2623,6 +2623,38 @@ def _compute_robust_vcov_numpy(
     # ------------------------------------------------------------------
     assert vcov_type == "hc1"
 
+    # Cluster-robust validity check FIRST: a cluster-robust request with fewer
+    # than 2 clusters is invalid and must raise the documented error — this has
+    # to precede the saturated-design guard below so a 1-cluster *saturated* fit
+    # still raises rather than being masked by the NaN return. (Mirrors the
+    # effective-cluster count computed in the cluster branch, including the
+    # zero-total-weight exclusion.)
+    if cluster_ids is not None:
+        # Normalize to an array first (as the cluster branch does) so the
+        # weighted groupby below cannot index-align a pandas Series grouper
+        # against the freshly-created Series(weights) and miscount clusters.
+        cluster_ids_arr = np.asarray(cluster_ids)
+        n_clusters_check = len(np.unique(cluster_ids_arr))
+        if weights is not None and weight_type != "fweight" and np.any(weights == 0):
+            cluster_weight_sums = pd.Series(weights).groupby(cluster_ids_arr).sum()
+            n_clusters_check = int((cluster_weight_sums > 0).sum())
+        if n_clusters_check < 2:
+            raise ValueError(
+                f"Need at least 2 clusters for cluster-robust SEs, got {n_clusters_check}"
+            )
+
+    # Saturated design (no residual degrees of freedom): both the HC1 adjustment
+    # n_eff/(n_eff-k) and the CR1 adjustment (n_eff-1)/(n_eff-k) divide by
+    # (n_eff - k), which is zero when the design exactly determines y. Return a
+    # NaN vcov so downstream inference is degenerate (NaN) rather than raising
+    # ZeroDivisionError — consistent with the library's all-or-nothing NaN
+    # convention for undefined inference.
+    if n_eff - k <= 0:
+        nan_vcov = np.full((k, k), np.nan)
+        if return_dof:
+            return nan_vcov, np.full(k, np.nan, dtype=np.float64)
+        return nan_vcov
+
     # Compute weighted scores for cluster-robust meat (outer product of sums).
     # pweight/fweight multiply by w; aweight and unweighted use raw residuals.
     _use_weighted_scores = weights is not None and weight_type not in ("aweight",)
@@ -3865,7 +3897,13 @@ class LinearRegression:
         """
         self._check_fitted()
         assert self.vcov_ is not None
-        return float(np.sqrt(self.vcov_[index, index]))
+        # Clamp a tiny-negative variance artifact at 0 before sqrt. A high-leverage
+        # / degenerate coefficient (e.g. an absorbed-FE dummy near-collinear with the
+        # treatment) can have a CR2/HC variance of ~0 that lands just below zero under
+        # BLAS-dependent float rounding; without the clamp `np.sqrt` returns NaN
+        # nondeterministically (passes single-threaded, fails under parallel test
+        # load). The SE is then finite — 0 for a genuinely-zero variance.
+        return float(np.sqrt(max(float(self.vcov_[index, index]), 0.0)))
 
     def get_inference(
         self,
@@ -3908,7 +3946,8 @@ class LinearRegression:
         assert self.vcov_ is not None
 
         coef = float(self.coefficients_[index])
-        se = float(np.sqrt(self.vcov_[index, index]))
+        # See get_se: clamp a tiny-negative variance artifact at 0 so SE is finite, not NaN.
+        se = float(np.sqrt(max(float(self.vcov_[index, index]), 0.0)))
 
         # Use instance alpha if not provided
         effective_alpha = alpha if alpha is not None else self.alpha

{diff_diff-3.5.2 → diff_diff-3.5.3}/diff_diff/power.py

@@ -267,6 +267,29 @@ def _ddd_dgp_kwargs(
     )
 
 
+def _ddd_panel_dgp_kwargs(
+    n_units: int,
+    n_periods: int,
+    treatment_effect: float,
+    treatment_fraction: float,
+    treatment_period: int,
+    sigma: float,
+) -> Dict[str, Any]:
+    # Panel DDD DGP (n_periods > 2). `n_units` maps directly (no 8-cell //8
+    # rounding). `treatment_fraction` is intentionally NOT mapped — DDD is a
+    # balanced factorial, so group_frac/partition_frac are left at the DGP
+    # default 0.5. Omitting group_frac/partition_frac here also keeps them out
+    # of the _PROTECTED_DGP_KEYS collision check, so a user can still override
+    # the group/partition split via data_generator_kwargs.
+    return dict(
+        n_units=n_units,
+        n_periods=n_periods,
+        treatment_period=treatment_period,
+        treatment_effect=treatment_effect,
+        noise_sd=sigma,
+    )
+
+
 # -- Fit kwargs builders ------------------------------------------------------
 
 
@@ -320,6 +343,19 @@ def _ddd_fit_kwargs(
     return dict(outcome="outcome", group="group", partition="partition", time="time")
 
 
+def _ddd_panel_fit_kwargs(
+    data: pd.DataFrame,
+    n_units: int,
+    n_periods: int,
+    treatment_period: int,
+) -> Dict[str, Any]:
+    # Panel DDD: time="post" is generate_ddd_panel_data's derived binary
+    # pre/post indicator (vs the cross-sectional "time"). Clustering is NOT a
+    # fit kwarg — it resolves from the estimator's cluster="unit" attribute
+    # against the DGP's "unit" column.
+    return dict(outcome="outcome", group="group", partition="partition", time="post")
+
+
 def _trop_fit_kwargs(
     data: pd.DataFrame,
     n_units: int,
@@ -636,6 +672,47 @@ def _ddd_effective_n(
     return eff if eff != n_units else None
 
 
+def _ddd_panel_cells_populated(n: int, group_frac: float, partition_frac: float) -> bool:
+    """Whether ``generate_ddd_panel_data`` would populate all 4 (group,partition)
+    cells at ``n`` units. Mirrors the rounded stratified allocation + non-empty
+    validation in ``prep_dgp.generate_ddd_panel_data`` (kept in lockstep)."""
+    if n < 4:
+        return False
+    n_g1 = int(round(n * group_frac))
+    n_g0 = n - n_g1
+    n_p1_g0 = int(round(n_g0 * partition_frac))
+    n_p1_g1 = int(round(n_g1 * partition_frac))
+    cells = (n_g0 - n_p1_g0, n_p1_g0, n_g1 - n_p1_g1, n_p1_g1)
+    return min(cells) >= 1
+
+
+def _ddd_panel_viable_min_n(
+    group_frac: float, partition_frac: float, floor: int = 16, search_max: int = 100000
+) -> int:
+    """Smallest ``n_units`` for which ``generate_ddd_panel_data`` populates all
+    four (group,partition) cells under the given split, floored at ``floor``.
+
+    For the balanced default (0.5/0.5) this is 4, so the result is ``floor``;
+    skewed splits (e.g. 0.1/0.1) need more units before every cell is non-empty,
+    so the sample-size search must bracket above this value (the registry
+    documents group_frac/partition_frac as data_generator_kwargs overrides)."""
+    # Validate up front (matching generate_ddd_panel_data) so an out-of-range
+    # split raises the same clear message here — before the bracketing logic can
+    # surface a misleading "n_range below the minimum" error downstream.
+    if not (0.0 < group_frac < 1.0):
+        raise ValueError(f"group_frac must be in (0, 1); got {group_frac}.")
+    if not (0.0 < partition_frac < 1.0):
+        raise ValueError(f"partition_frac must be in (0, 1); got {partition_frac}.")
+    for n in range(4, search_max + 1):
+        if _ddd_panel_cells_populated(n, group_frac, partition_frac):
+            return max(floor, n)
+    raise ValueError(
+        f"No panel-DDD sample size <= {search_max} populates all four "
+        f"(group, partition) cells for group_frac={group_frac}, "
+        f"partition_frac={partition_frac}; move the split closer to 0.5."
+    )
+
+
 def _check_ddd_dgp_compat(
     n_units: int,
     n_periods: int,
@@ -686,6 +763,55 @@ def _check_ddd_dgp_compat(
         )
 
 
+def _check_ddd_panel_dgp_compat(
+    estimator: Any,
+    treatment_fraction: float,
+    data_generator_kwargs: Optional[Dict[str, Any]],
+) -> None:
+    """Compat checks for the panel DDD power path (``n_periods > 2``).
+
+    Unlike the cross-sectional ``_check_ddd_dgp_compat``, ``n_periods`` and
+    ``treatment_period`` are honored here (no warning). ``treatment_fraction``
+    is still inert (the panel DGP is a balanced 2×2×2). The key addition is the
+    clustering caveat: ``generate_ddd_panel_data`` has within-unit serial
+    correlation, so unclustered SEs overstate power.
+    """
+    overrides = data_generator_kwargs or {}
+    if "n_per_cell" in overrides:
+        raise ValueError(
+            "data_generator_kwargs contains 'n_per_cell', a cross-sectional "
+            "generate_ddd_data parameter. The panel DDD power path "
+            "(n_periods > 2) uses generate_ddd_panel_data, which sizes the panel "
+            "by n_units directly. Control the design via n_units and the "
+            "group_frac / partition_frac data_generator_kwargs instead."
+        )
+
+    if treatment_fraction != 0.5:
+        warnings.warn(
+            f"treatment_fraction={treatment_fraction} is ignored for "
+            f"TripleDifference power: generate_ddd_panel_data uses a balanced "
+            f"2×2×2 design (group_frac=partition_frac=0.5). Pass group_frac / "
+            f"partition_frac via data_generator_kwargs to vary the split.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    # The panel DGP hard-names its unit column "unit", and TripleDifference
+    # resolves clustering from `self.cluster` against a same-named data column,
+    # so on this auto-DGP path the only correct value is the literal "unit" —
+    # this is NOT a general clustering check.
+    if getattr(estimator, "cluster", None) != "unit":
+        warnings.warn(
+            "TripleDifference power on the panel DGP (n_periods > 2) has "
+            "within-unit serial correlation, so unclustered standard errors are "
+            "anti-conservative and overstate power. Construct the estimator as "
+            'TripleDifference(cluster="unit") so the reported power reflects '
+            "cluster-robust (Liang-Zeger CR1) inference.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+
 def _check_sdid_placebo_data(
     data: pd.DataFrame,
     estimator: Any,
@@ -833,6 +959,28 @@ def _get_registry() -> Dict[str, _EstimatorProfile]:
     return _ESTIMATOR_REGISTRY
 
 
+def _ddd_panel_profile() -> "_EstimatorProfile":
+    """Profile for panel DDD power simulations (n_periods > 2).
+
+    Routes TripleDifference power analysis to ``generate_ddd_panel_data``
+    (which honors ``n_periods``/``treatment_period``) instead of the
+    cross-sectional 2x2x2 ``generate_ddd_data``. See ``simulate_power``.
+    """
+    from diff_diff.prep import generate_ddd_panel_data
+
+    # min_n=16 is intentionally lower than the cross-sectional DDD min_n=64
+    # (which counts 8 cells x n_per_cell); the panel DGP maps n_units directly
+    # and only requires n_units >= 4, so 16 gives >=1 unit per (group,partition)
+    # cell with margin.
+    return _EstimatorProfile(
+        default_dgp=generate_ddd_panel_data,
+        dgp_kwargs_builder=_ddd_panel_dgp_kwargs,
+        fit_kwargs_builder=_ddd_panel_fit_kwargs,
+        result_extractor=_extract_simple,
+        min_n=16,
+    )
+
+
 @dataclass
 class PowerResults:
     """
@@ -2007,6 +2155,21 @@ def simulate_power(
     use_custom_dgp = data_generator is not None
     use_survey_dgp = survey_config is not None
 
+    # Route DDD power to the panel DGP when n_periods > 2. The cross-sectional
+    # 2x2x2 generate_ddd_data ignores n_periods; generate_ddd_panel_data honors
+    # it. Swapping the profile here (before the collision check and the DDD
+    # compat warnings) makes every downstream consumer (dgp_kwargs_builder,
+    # default_dgp, fit_kwargs_builder, result_extractor, min_n) use the panel
+    # variant automatically.
+    use_ddd_panel = (
+        estimator_name == "TripleDifference"
+        and n_periods > 2
+        and not use_custom_dgp
+        and not use_survey_dgp
+    )
+    if use_ddd_panel:
+        profile = _ddd_panel_profile()
+
     # --- Survey config validation ---
     if use_survey_dgp:
         assert survey_config is not None  # for type narrowing
@@ -2161,7 +2324,13 @@ def simulate_power(
             )
 
     # Warn if DDD design inputs are silently ignored
-    if estimator_name == "TripleDifference" and not use_custom_dgp:
+    if use_ddd_panel:
+        # Panel path honors n_periods/treatment_period; n_units maps directly
+        # (no //8 rounding). Different compat surface than the cross-sectional
+        # 2x2x2 design.
+        _check_ddd_panel_dgp_compat(estimator, treatment_fraction, data_generator_kwargs)
+        effective_n_units = None
+    elif estimator_name == "TripleDifference" and not use_custom_dgp:
         _check_ddd_dgp_compat(
             n_units,
             n_periods,
@@ -2707,8 +2876,10 @@ def simulate_mde(
     estimator_name = type(estimator).__name__
     search_path: List[Dict[str, float]] = []
 
-    # Compute effective N for DDD (N is fixed throughout MDE search)
-    if estimator_name == "TripleDifference" and data_generator is None:
+    # Compute effective N for DDD (N is fixed throughout MDE search). Only the
+    # cross-sectional 2x2x2 DGP (n_periods <= 2) rounds n_units to a multiple of
+    # 8; the panel DGP (n_periods > 2) maps n_units directly, so report None.
+    if estimator_name == "TripleDifference" and data_generator is None and n_periods <= 2:
         effective_n_units = _ddd_effective_n(n_units, data_generator_kwargs)
     else:
         effective_n_units = None
@@ -2925,15 +3096,33 @@ def simulate_sample_size(
     estimator_name = type(estimator).__name__
     search_path: List[Dict[str, float]] = []
 
-    # Determine min_n from registry
+    # Determine min_n from registry. DDD splits cross-sectional (n_periods <= 2,
+    # 2x2x2 factorial) from panel (n_periods > 2, generate_ddd_panel_data).
     registry = _get_registry()
     profile = registry.get(estimator_name)
-    min_n = profile.min_n if profile is not None else 20
+    is_ddd = estimator_name == "TripleDifference" and data_generator is None
+    is_ddd_panel = is_ddd and n_periods > 2
+    if is_ddd_panel:
+        # The panel DGP requires every (group,partition) cell non-empty, which
+        # for a skewed group_frac/partition_frac override needs more than the
+        # default 16-unit floor. Bracket above the viable minimum so the search
+        # never probes an infeasible n (which would raise in the DGP).
+        _ddd_overrides = data_generator_kwargs or {}
+        min_n = _ddd_panel_viable_min_n(
+            _ddd_overrides.get("group_frac", 0.5),
+            _ddd_overrides.get("partition_frac", 0.5),
+            floor=_ddd_panel_profile().min_n,
+        )
+    else:
+        min_n = profile.min_n if profile is not None else 20
 
-    # DDD grid snapping: bisection candidates must be multiples of 8
-    is_ddd_grid = estimator_name == "TripleDifference" and data_generator is None
+    # Grid snapping: the cross-sectional 2x2x2 DDD DGP rounds n_units to a
+    # multiple of 8, so bisection candidates must snap to that grid. The panel
+    # DGP maps n_units directly → continuous (step-1) search like every other
+    # estimator.
+    is_ddd_grid = is_ddd and not is_ddd_panel
     grid_step = 8 if is_ddd_grid else 1
-    convergence_threshold = grid_step + 1  # 9 for DDD, 2 for others
+    convergence_threshold = grid_step + 1  # 9 for cross-sectional DDD, 2 otherwise
 
     if is_ddd_grid and data_generator_kwargs and "n_per_cell" in data_generator_kwargs:
         raise ValueError(
@@ -2991,9 +3180,25 @@ def simulate_sample_size(
             )
 
     # --- Bracket ---
-    abs_min = 16 if is_ddd_grid else 4
+    # Cross-sectional DDD wants a >=16 floor so the 8 G×P×T cells are populated;
+    # the panel path uses its split-aware viable floor (min_n above, which is
+    # >=16 and higher for skewed group_frac/partition_frac); everything else
+    # floors at 4.
+    if is_ddd_panel:
+        abs_min = min_n
+    elif is_ddd:
+        abs_min = 16
+    else:
+        abs_min = 4
     if survey_config is not None:
         abs_min = max(abs_min, survey_config.min_viable_n)
+    if is_ddd_panel and n_range is not None and n_range[1] < abs_min:
+        raise ValueError(
+            f"n_range upper bound ({n_range[1]}) is below the minimum panel-DDD "
+            f"sample size ({abs_min}) needed to populate all (group, partition) "
+            f"cells for group_frac/partition_frac. Raise the upper bound or move "
+            f"the split closer to 0.5."
+        )
     if n_range is not None:
         lo, hi = _snap_n(n_range[0], "up", floor=abs_min), _snap_n(
             n_range[1], "down", floor=abs_min

{diff_diff-3.5.2 → diff_diff-3.5.3}/diff_diff/prep.py

@@ -28,6 +28,7 @@ from diff_diff.prep_dgp import (  # noqa: F401
     generate_staggered_data,
     generate_staggered_ddd_data,
     generate_survey_did_data,
+    generate_synthetic_control_data,
 )
 from diff_diff.survey import (
     ResolvedSurveyDesign,