Round-12 CI P3s: suppress warning on varying-PSU + drop bootstrap psu= workaround text

**P3 #1 (warning predicate inconsistent with "strictly coarser PSU"
contract):** the new bootstrap warning block's comment said the
warning fires only on strictly-coarser PSU designs, but the
predicate `n_psu_eff_warn < n_groups_eff_warn` could also fire on
supported varying-PSU designs whose eligible groups happened to
share PSU labels across groups. Detect within-group-varying PSU
explicitly (`.groupby("g")["p"].nunique().gt(1).any()`) and
suppress the warning in that regime. Under auto-inject PSU=group
and under within-group-varying PSU the warning now stays silent,
matching the stated contract.

**P3 #2 (`_unroll_target_to_cells` suggested `psu=<group_col>` as a
bootstrap workaround):** the Registry / CHANGELOG already clarified
that `psu=<group_col>` is ONLY a Binder TSL workaround; the cell-
level wild PSU bootstrap has no allocator fallback. The helper's
docstring and `ValueError` message still advertised it as a
bootstrap-path workaround. Dropped that suggestion and explicitly
clarified: the varying-PSU bootstrap IS the cell-level path, so
there is no legacy-allocator alternative to fall back to —
pre-processing the panel is the only workaround on the bootstrap
side.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

diff_diff/chaisemartin_dhaultfoeuille.py

@@ -2125,32 +2125,34 @@ def fit(
                         "instead of replicate weights."
                     )
 
-                # Warning fires only when PSU is strictly coarser than
-                # group (multiple eligible groups share a PSU label).
-                # Under auto-inject psu=group or PSU that varies within
-                # group (each group contributes to >= 1 PSU), the
-                # warning should NOT fire because the Hall-Mammen
-                # wild PSU bootstrap is either identical to a group-
-                # level multiplier bootstrap (PSU=group) or finer-than-
-                # group (varying PSU; the cell-level allocator honors
-                # the per-cell PSU structure). Count unique PSUs
-                # across ALL positive-weight obs of eligible groups,
-                # not just the first label per group — under varying
-                # PSU a group spans multiple PSUs.
+                # Warning fires only when PSU is **strictly coarser
+                # than group** on an otherwise within-group-constant
+                # design (multiple eligible groups share a PSU label
+                # but no group spans more than one PSU). Two regimes
+                # are explicitly excluded:
+                # - PSU=group (auto-inject default): identity-map
+                #   fast path — no warning needed.
+                # - Within-group-varying PSU: the cell-level
+                #   allocator honors the per-cell PSU structure;
+                #   "n_psu < n_groups" is expected whenever cells
+                #   of a group share a PSU with cells of another
+                #   group, which does not indicate coarser-than-group
+                #   clustering in the Hall-Mammen sense.
+                # Count unique PSUs across ALL positive-weight obs of
+                # eligible groups AND detect within-group-varying
+                # PSU; suppress the warning in that regime.
                 psu_arr_warn = getattr(resolved_survey, "psu", None)
                 if psu_arr_warn is None or _obs_survey_info is None:
                     # No PSU info — can't compare to group count.
                     n_psu_eff_warn, n_groups_eff_warn = -1, -1
+                    psu_varies_within_warn = False
                 else:
                     obs_gids_warn = np.asarray(_obs_survey_info["group_ids"])
                     obs_ws_warn = np.asarray(
                         _obs_survey_info["weights"], dtype=np.float64
                     )
                     pos_mask_warn = obs_ws_warn > 0
                     psu_codes_warn = np.asarray(psu_arr_warn)
-                    # Restrict to positive-weight obs whose group is
-                    # variance-eligible, then count unique PSU labels
-                    # across that full set (not first-per-group).
                     eligible_gid_set = set(_eligible_group_ids)
                     elig_obs_mask_warn = pos_mask_warn & np.array(
                         [g in eligible_gid_set for g in obs_gids_warn],
@@ -2162,9 +2164,26 @@ def fit(
                             len(np.unique(elig_psu_labels_arr))
                         )
                         n_groups_eff_warn = len(_eligible_group_ids)
+                        # Detect within-group-varying PSU on the
+                        # eligible subset so we can suppress the
+                        # "strictly coarser PSU" warning there.
+                        psu_varies_within_warn = bool(
+                            pd.DataFrame({
+                                "g": obs_gids_warn[elig_obs_mask_warn],
+                                "p": elig_psu_labels_arr,
+                            })
+                            .groupby("g")["p"]
+                            .nunique()
+                            .gt(1)
+                            .any()
+                        )
                     else:
                         n_psu_eff_warn, n_groups_eff_warn = -1, -1
-                if 0 <= n_psu_eff_warn < n_groups_eff_warn:
+                        psu_varies_within_warn = False
+                if (
+                    0 <= n_psu_eff_warn < n_groups_eff_warn
+                    and not psu_varies_within_warn
+                ):
                     warnings.warn(
                         f"Bootstrap with survey_design uses Hall-Mammen "
                         f"wild multiplier weights at the PSU level "

diff_diff/chaisemartin_dhaultfoeuille_bootstrap.py

@@ -687,10 +687,14 @@ def _unroll_target_to_cells(
     bootstrap contribution. The analytical TSL path shares the same
     cell-period allocator and fires a matching guard in
     ``_survey_se_from_group_if``, so both paths reject this regime
-    consistently. Documented workarounds: pre-process the panel
-    (drop late-exit groups or trim to a balanced sub-panel), or use
-    an explicit ``psu=<group_col>`` so both analytical and bootstrap
-    paths route through the legacy group-level allocator.
+    consistently. **Documented workaround (bootstrap path):**
+    pre-process the panel to remove terminal missingness (drop
+    late-exit groups or trim to a balanced sub-panel). The within-
+    group-varying-PSU bootstrap has no allocator fallback — unlike
+    Binder TSL, where using an explicit ``psu=<group_col>`` routes
+    the analytical path through the legacy group-level allocator;
+    that fallback is not available on the bootstrap side because
+    the cell-level wild PSU bootstrap IS the varying-PSU regime.
 
     Returns ``(u_cell, psu_cell)`` of shape
     ``(n_valid_cells_in_target,)`` each.
@@ -738,8 +742,11 @@ def _unroll_target_to_cells(
             "the same regime, so both paths reject this panel "
             "consistently. Pre-process the panel to remove terminal "
             "missingness (drop late-exit groups or trim to a balanced "
-            "sub-panel), or use an explicit `psu=<group_col>` so both "
-            "paths route through the legacy group-level allocator."
+            "sub-panel). The within-group-varying-PSU bootstrap has "
+            "no allocator fallback — unlike Binder TSL, switching to "
+            "`psu=<group_col>` does not help here because the varying-"
+            "PSU bootstrap IS the cell-level path, not an analytical "
+            "surface with a legacy-allocator alternative."
         )
     return flat_u[mask], flat_psu[mask].astype(np.int64, copy=False)