Address PR #365 R8 P1: drop FPC from placebo dispatch + document FPC no-op contract

P1 (Methodology — placebo dispatch flipped on FPC alone, but FPC
plays no role in placebo math):
The dispatcher gated placebo's survey-path routing on
``_full_design_survey = strata is not None OR psu is not None OR fpc
is not None``. Adding an ``fpc=`` column to a SurveyDesign therefore
silently switched dispatch from the non-survey placebo path
(unweighted-FW + post-hoc ω composition) to the weighted-FW survey
placebo path — different numerics — even though permutation tests are
conditional on the observed sample (Pesarin 2001 §1.5) and the
sampling fraction never enters Algorithm 4 or its stratified-
permutation survey extension. The reviewer correctly flagged this
as an undocumented methodology mismatch on a public variance method.

Fix:
* Gate ``_placebo_use_survey_path`` on ``strata is not None OR psu
  is not None`` (FPC dropped from the trigger). FPC alone now keeps
  placebo on the non-survey path with no numerical drift relative to
  the no-FPC fit.
* Emit a ``UserWarning`` whenever ``fpc`` is set with
  ``variance_method="placebo"``, regardless of whether ``strata`` or
  ``psu`` are also set, so users get an explicit signal that the
  FPC column is preserved in design metadata but does not enter
  placebo math. Recommends ``variance_method="bootstrap"`` or
  ``"jackknife"`` for FPC participation.
* REGISTRY §SyntheticDiD "Note (survey support matrix)" placebo
  bullet rewritten to spell out the contract: "for designs with
  explicit ``strata`` and/or ``psu`` … FPC is a documented no-op for
  placebo — permutation tests are conditional on the observed sample
  (Pesarin 2001 §1.5)."
* survey-theory.md placebo bullet picks up the same FPC no-op
  language plus the Case B/C/D guard enumeration from R5.

New regression
``test_placebo_fpc_alone_no_op_warns_and_matches_pweight_only``
asserts both contracts: (a) ``UserWarning`` fires when fpc is set
on placebo, (b) SE under ``SurveyDesign(weights, fpc)`` matches SE
under ``SurveyDesign(weights)`` at ``rel=1e-12`` (true no-op, not a
silent dispatch flip introducing weighted-FW drift).

Bootstrap and jackknife paths unchanged — they use FPC legitimately
(Rao-Wu rescaling for bootstrap, ``(1 - f_h)`` factor in the Rust &
Rao 1996 jackknife formula). Only placebo's contract narrows.

Verification: 95 passed (1 new FPC no-op regression).

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

Author: igerber

diff_diff/synthetic_did.py

@@ -789,15 +789,49 @@ def fit(  # type: ignore[override]
             _fpc_control = None
             _fpc_treated = None
 
-        # Placebo routes to the survey allocator whenever strata or PSU
-        # or FPC is declared. For PSU/FPC-without-strata designs, the
-        # whole panel is synthesized as a single stratum (stratified
-        # permutation degenerates to global within-stratum permutation,
-        # still dispatched through the weighted-FW path for methodology
-        # consistency with the documented full-design contract).
+        # Placebo routes to the survey allocator whenever **strata or
+        # PSU** is declared (FPC alone does NOT flip dispatch). For
+        # PSU-without-strata designs, the whole panel is synthesized
+        # as a single stratum (stratified permutation degenerates to
+        # global within-stratum permutation, still dispatched through
+        # the weighted-FW path).
+        #
+        # FPC handling on placebo (R8 P1 fix): permutation tests are
+        # conditional on the observed sample (Pesarin 2001 §1.5), so
+        # the sampling fraction does not enter Algorithm 4 or its
+        # stratified-permutation extension. Including FPC in the
+        # dispatch trigger would silently switch numerics (weighted-FW
+        # vs unweighted-FW + post-hoc composition) on a survey design
+        # element that has no place in the placebo math. Drop FPC from
+        # the dispatch condition; emit a ``UserWarning`` below if FPC
+        # is set with placebo to surface the no-op contract.
         _placebo_use_survey_path = (
-            _full_design_survey and self.variance_method == "placebo"
+            self.variance_method == "placebo"
+            and resolved_survey_unit is not None
+            and (
+                resolved_survey_unit.strata is not None
+                or resolved_survey_unit.psu is not None
+            )
         )
+        if (
+            self.variance_method == "placebo"
+            and resolved_survey_unit is not None
+            and resolved_survey_unit.fpc is not None
+        ):
+            warnings.warn(
+                "SurveyDesign(fpc=...) is a no-op on "
+                "variance_method='placebo': permutation tests are "
+                "conditional on the observed sample (Pesarin 2001 §1.5), "
+                "so the sampling fraction does not enter Algorithm 4 or "
+                "its stratified-permutation survey extension. The FPC "
+                "column is preserved in the design metadata for other "
+                "purposes but the placebo SE is computed as if FPC were "
+                "absent. Use variance_method='bootstrap' or 'jackknife' "
+                "if you need FPC to participate in the variance "
+                "computation.",
+                UserWarning,
+                stacklevel=2,
+            )
 
         # Jackknife routes to the survey allocator whenever PSU or FPC or
         # strata is declared. PSU-without-strata is treated as a single

docs/methodology/REGISTRY.md

@@ -1561,7 +1561,7 @@ Convergence criterion: stop when objective decrease < min_decrease² (default mi
 
   **Bootstrap survey path** (PR #355): for pweight-only the per-draw FW uses constant `rw = w_control`; for full design (strata/PSU/FPC) the per-draw `rw = generate_rao_wu_weights(resolved_survey, rng)` rescaling is composed with the same weighted-FW kernel. See "Note (survey + bootstrap composition)" below for the full objective and the argmin-set caveat.
 
-  **Placebo survey path**: for pweight-only the existing Algorithm 4 flow applies with survey-weighted pseudo-treated means + post-hoc ω_eff composition. For full design (strata/PSU/FPC) the allocator switches to **stratified permutation** (Pesarin 2001): pseudo-treated indices are drawn within each stratum containing actual treated units; weighted-FW re-estimates ω and λ per draw with per-control survey weights threaded into both loss and regularization. See "Note (survey + placebo composition)" below.
+  **Placebo survey path**: for pweight-only the existing Algorithm 4 flow applies with survey-weighted pseudo-treated means + post-hoc ω_eff composition. For designs with explicit `strata` and/or `psu` the allocator switches to **stratified permutation** (Pesarin 2001): pseudo-treated indices are drawn within each stratum containing actual treated units; weighted-FW re-estimates ω and λ per draw with per-control survey weights threaded into both loss and regularization. See "Note (survey + placebo composition)" below. **FPC is a documented no-op for placebo** — permutation tests are conditional on the observed sample (Pesarin 2001 §1.5), so the sampling fraction does not enter Algorithm 4 or its survey extension; an `fpc=` column on a placebo fit emits a `UserWarning` and is preserved in the design metadata but never enters the variance computation. Routing is gated on `strata` / `psu` only — FPC alone does not flip dispatch from the non-survey to the survey placebo path.
 
   **Jackknife survey path**: for pweight-only the existing Algorithm 3 flow applies (unit-level LOO with subset + rw-composed-renormalized ω; λ fixed). For full design the allocator switches to **PSU-level LOO with stratum aggregation** (Rust & Rao 1996): leave out one PSU at a time within each stratum, aggregate as `SE² = Σ_h (1-f_h)·(n_h-1)/n_h·Σ_{j∈h}(τ̂_{(h,j)} - τ̄_h)²`. See "Note (survey + jackknife composition)" below.
 

docs/methodology/survey-theory.md

@@ -749,20 +749,27 @@ Two bootstrap strategies interact with survey designs:
   for the full objective and the argmin-set caveat.
 
 - **Stratified permutation placebo** (SyntheticDiD): SDID's full-design
-  placebo variance allocator. For each placebo draw, pseudo-treated
-  indices are sampled uniformly without replacement from controls
-  *within each stratum containing actual treated units* (classical
-  stratified permutation test — Pesarin 2001). Pseudo-treated means
-  are survey-weighted; weighted-FW re-estimates ω and λ per draw with
-  ``rw_control`` threaded into both loss and regularization. Post-
-  optimization composition ``ω_eff = rw · ω / Σ(rw · ω)`` with zero-
-  mass retry. SE follows Arkhangelsky Algorithm 4:
+  placebo variance allocator (triggered when ``strata`` and/or ``psu``
+  is declared on the ``SurveyDesign``). For each placebo draw,
+  pseudo-treated indices are sampled uniformly without replacement
+  from controls *within each stratum containing actual treated units*
+  (classical stratified permutation test — Pesarin 2001).
+  Pseudo-treated means are survey-weighted; weighted-FW re-estimates
+  ω and λ per draw with ``rw_control`` threaded into both loss and
+  regularization. Post-optimization composition
+  ``ω_eff = rw · ω / Σ(rw · ω)`` with zero-mass retry. SE follows
+  Arkhangelsky Algorithm 4:
   ``sqrt((r-1)/r) · std(placebo_estimates, ddof=1)``. Fit-time
-  feasibility guards raise ``ValueError`` when a treated-containing
-  stratum has 0 controls or fewer controls than treated units (the
-  permutation allocator requires ``n_controls_h ≥ n_treated_h`` by
-  construction). See REGISTRY.md §SyntheticDiD ``Note (survey +
-  placebo composition)``.
+  feasibility guards raise ``ValueError`` on three failure cases:
+  Case B (treated stratum has 0 controls), Case C (fewer controls
+  than treated in a treated stratum), and Case D (every treated
+  stratum is exact-count ``n_c == n_t`` → permutation support = 1).
+  ``SurveyDesign(fpc=...)`` is a documented no-op for placebo —
+  permutation tests are conditional on the observed sample (Pesarin
+  2001 §1.5), so the sampling fraction does not enter Algorithm 4 or
+  its survey extension. An ``fpc=`` column emits a ``UserWarning`` and
+  is not part of the placebo dispatch trigger. See REGISTRY.md
+  §SyntheticDiD ``Note (survey + placebo composition)``.
 
 - **PSU-level leave-one-out with stratum aggregation** (SyntheticDiD):
   SDID's full-design jackknife variance allocator, matching the

tests/test_survey_phase5.py

@@ -894,6 +894,64 @@ def test_placebo_full_design_se_differs_from_pweight_only(
         assert result_pw.att == pytest.approx(result_full.att, abs=1e-10)
         assert result_pw.se != pytest.approx(result_full.se, abs=1e-6)
 
+    def test_placebo_fpc_alone_no_op_warns_and_matches_pweight_only(
+        self, sdid_survey_data_full_design
+    ):
+        """R8 P1 fix: ``fpc=`` alone does not flip placebo dispatch.
+
+        Permutation tests condition on the observed sample (Pesarin 2001
+        §1.5), so FPC's sampling-fraction adjustment doesn't enter
+        Algorithm 4 or its stratified-permutation survey extension. The
+        previous dispatcher routed any ``fpc is not None`` design through
+        ``_placebo_variance_se_survey`` (weighted-FW per draw), silently
+        changing numerics relative to the no-FPC fit even though FPC
+        played no role in the math.
+
+        The fix gates placebo's survey-path dispatch on
+        ``strata is not None OR psu is not None`` only, and emits a
+        ``UserWarning`` whenever FPC is set on a placebo fit. This test
+        asserts both: (a) the warning fires and (b) ``SE`` matches the
+        pweight-only-no-FPC fit at ``rel=1e-12`` (FPC truly is a no-op).
+        """
+        df = sdid_survey_data_full_design.copy()
+        df["fpc_col"] = 1000.0  # any positive value — no-op on placebo
+
+        sd_fpc_only = SurveyDesign(weights="weight", fpc="fpc_col")
+        sd_pweight_only = SurveyDesign(weights="weight")
+
+        est_fpc = SyntheticDiD(variance_method="placebo", n_bootstrap=50, seed=42)
+        with pytest.warns(
+            UserWarning,
+            match=r"SurveyDesign\(fpc=\.\.\.\) is a no-op on variance_method='placebo'",
+        ):
+            r_fpc = est_fpc.fit(
+                df,
+                outcome="outcome",
+                treatment="treated",
+                unit="unit",
+                time="time",
+                post_periods=[6, 7, 8, 9],
+                survey_design=sd_fpc_only,
+            )
+
+        est_pw = SyntheticDiD(variance_method="placebo", n_bootstrap=50, seed=42)
+        r_pw = est_pw.fit(
+            df,
+            outcome="outcome",
+            treatment="treated",
+            unit="unit",
+            time="time",
+            post_periods=[6, 7, 8, 9],
+            survey_design=sd_pweight_only,
+        )
+
+        # FPC is documented as no-op for placebo: the SE under FPC must
+        # exactly match the SE without FPC (same dispatch path, no
+        # numerical drift from the routing flip the dispatcher used to
+        # introduce on `fpc is not None`).
+        assert r_fpc.se == pytest.approx(r_pw.se, rel=1e-12)
+        assert r_fpc.att == pytest.approx(r_pw.att, abs=1e-12)
+
     def test_placebo_full_design_psu_only_routes_through_survey_path(
         self, sdid_survey_data_jk_well_formed
     ):