Address PR #376 R9 (2 P3)

R9 P3 #1 (helper error message canonical-kwarg consistency):
`_resolve_pretest_unit_weights`'s TypeError on non-`SurveyDesign`-like
input still said `survey=` must be a SurveyDesign — but on the data-in
wrappers (workflow / joint_pretrends_test / joint_homogeneity_test) the
canonical kwarg is now `survey_design=`. Updated the message to name
`survey_design=` (with `survey=` flagged as the deprecated alias) and
to point pre-resolved-design users to the array-in pretest helpers,
mirroring HAD.fit's data-in guard.

R9 P3 #2 (legacy-vs-canonical parity coverage on data-in pretests):
Added 3 parity tests (test_legacy_alias_parity_survey on
joint_pretrends_test + joint_homogeneity_test, plus
test_legacy_alias_parity_survey_overall on did_had_pretest_workflow
overall path). Locks the rebinding contract on the data-in surfaces
that previously only had smoke / warning / mutex coverage.

558 tests pass (was 555 + 3 new R9 P3 parity tests).

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

Author: igerber

diff_diff/had_pretests.py

@@ -3262,9 +3262,22 @@ def _resolve_pretest_unit_weights(
         return weights_unit, None
     # survey is not None
     if not hasattr(survey, "resolve"):
+        # PR #376 R9 P3: error message names the canonical kwarg
+        # `survey_design=` (with the deprecated `survey=` alias mentioned
+        # for back-compat), and points pre-resolved-design users to the
+        # array-in pretest helpers where ResolvedSurveyDesign /
+        # make_pweight_design(arr) belong.
         raise TypeError(
-            f"{caller_name}: survey= must be a SurveyDesign instance "
-            f"(with .resolve()); got {type(survey).__name__}."
+            f"{caller_name}: `survey_design=` (or the deprecated `survey=` "
+            f"alias) accepts a SurveyDesign instance (column-referencing, "
+            f"gets `.resolve(data)`'d at fit time) on data-in surfaces; "
+            f"got {type(survey).__name__} (no `.resolve()` method). "
+            "If you have a pre-resolved ResolvedSurveyDesign or used "
+            "`make_pweight_design(arr)`, that pattern is for the array-in "
+            "pretest helpers (`stute_test`, `yatchew_hr_test`, "
+            "`stute_joint_pretest`). On data-in surfaces, add the weights "
+            "as a column on `data` and pass "
+            "`survey_design=SurveyDesign(weights='col_name', ...)`."
         )
     resolved_full = survey.resolve(data)
     if getattr(resolved_full, "replicate_weights", None) is not None:

tests/test_had_dual_knob_deprecation.py

@@ -605,6 +605,41 @@ def test_three_way_mutex_design_plus_survey(self, event_study_panel):
                 seed=0,
             )
 
+    def test_legacy_alias_parity_survey(self, event_study_panel):
+        """PR #376 R9 P3: deprecated `survey=SurveyDesign(...)` ≡ canonical
+        `survey_design=SurveyDesign(...)` on joint_pretrends_test (locks
+        rebinding parity)."""
+        df = event_study_panel
+        sd = SurveyDesign(weights="w")
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            r_legacy = joint_pretrends_test(
+                df,
+                "y",
+                "d",
+                "time",
+                "unit",
+                pre_periods=[0],
+                base_period=1,
+                survey=sd,
+                n_bootstrap=199,
+                seed=0,
+            )
+        r_new = joint_pretrends_test(
+            df,
+            "y",
+            "d",
+            "time",
+            "unit",
+            pre_periods=[0],
+            base_period=1,
+            survey_design=sd,
+            n_bootstrap=199,
+            seed=0,
+        )
+        assert r_legacy.cvm_stat_joint == r_new.cvm_stat_joint
+        assert r_legacy.p_value == r_new.p_value
+
 
 class TestJointHomogeneityTestDeprecation:
     def test_survey_design_kwarg_smoke(self, event_study_panel):
@@ -656,6 +691,40 @@ def test_survey_emits_deprecation_warning(self, event_study_panel):
                 seed=0,
             )
 
+    def test_legacy_alias_parity_survey(self, event_study_panel):
+        """PR #376 R9 P3: deprecated `survey=SurveyDesign(...)` ≡ canonical
+        `survey_design=SurveyDesign(...)` on joint_homogeneity_test."""
+        df = event_study_panel
+        sd = SurveyDesign(weights="w")
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            r_legacy = joint_homogeneity_test(
+                df,
+                "y",
+                "d",
+                "time",
+                "unit",
+                post_periods=[2, 3],
+                base_period=1,
+                survey=sd,
+                n_bootstrap=199,
+                seed=0,
+            )
+        r_new = joint_homogeneity_test(
+            df,
+            "y",
+            "d",
+            "time",
+            "unit",
+            post_periods=[2, 3],
+            base_period=1,
+            survey_design=sd,
+            n_bootstrap=199,
+            seed=0,
+        )
+        assert r_legacy.cvm_stat_joint == r_new.cvm_stat_joint
+        assert r_legacy.p_value == r_new.p_value
+
 
 class TestHADFitDeprecation:
     def test_survey_design_kwarg_smoke(self, two_period_panel):
@@ -864,6 +933,40 @@ def test_three_way_mutex_all_three(self, two_period_panel):
                 seed=0,
             )
 
+    def test_legacy_alias_parity_survey_overall(self, two_period_panel):
+        """PR #376 R9 P3: deprecated `survey=SurveyDesign(...)` ≡ canonical
+        `survey_design=SurveyDesign(...)` on
+        did_had_pretest_workflow(aggregate='overall'). Locks rebinding
+        parity on the workflow's overall-path data-in surface."""
+        df = two_period_panel
+        sd = SurveyDesign(weights="w")
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)  # QUG-skip warning
+            warnings.simplefilter("ignore", DeprecationWarning)
+            r_legacy = did_had_pretest_workflow(
+                df,
+                "y",
+                "d",
+                "time",
+                "unit",
+                survey=sd,
+                n_bootstrap=199,
+                seed=0,
+            )
+            r_new = did_had_pretest_workflow(
+                df,
+                "y",
+                "d",
+                "time",
+                "unit",
+                survey_design=sd,
+                n_bootstrap=199,
+                seed=0,
+            )
+        assert r_legacy.stute.cvm_stat == r_new.stute.cvm_stat
+        assert r_legacy.stute.p_value == r_new.stute.p_value
+        assert r_legacy.yatchew.t_stat_hr == r_new.yatchew.t_stat_hr
+
 
 # =============================================================================
 # 3. PR #376 R2 P1: extended dispatch-matrix coverage on the new front door