stacked_did: address CI codex R2 P2 — clustered variance label

R2 verdict was ✅ + 1 P2: the summary's Variance: line (added in R1)
mislabelled clustered StackedDiD fits as one-way ("HC1
heteroskedasticity-robust" / "HC2 + Bell-McCaffrey DOF (one-way, n=N)")
because I passed cluster_name=None to _format_vcov_label. StackedDiD
is intrinsically clustered.

Fix:
- Added `cluster_name` and `n_clusters` fields to StackedDiDResults
  dataclass.
- Populated both at fit() time: cluster_name=self.cluster, n_clusters=
  np.unique(cluster_ids).size (matches the actual realized count, not
  config).
- summary() now passes cluster_name + n_clusters into
  _format_vcov_label, rendering "CR1 cluster-robust at unit, G=50"
  for hc1 and "CR2 Bell-McCaffrey cluster-robust at unit, G=50" for
  hc2_bm.

New regression test test_summary_renders_clustered_variance_label
verifies:
- hc1 → label contains "CR1 cluster-robust at unit"
- hc2_bm → label contains "CR2 Bell-McCaffrey cluster-robust at unit"
- Neither contains "(one-way" (catches the R2 regression directly)
- G= cluster count present
- cluster="unit_subexp" → label contains "at unit_subexp"

90 tests pass.

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

Author: igerber

diff_diff/stacked_did.py

@@ -835,6 +835,8 @@ def _refit_stacked(w_r):
             alpha=self.alpha,
             anticipation=self.anticipation,
             vcov_type=self.vcov_type,
+            cluster_name=self.cluster,
+            n_clusters=int(np.unique(cluster_ids).size),
             survey_metadata=survey_metadata,
         )
 

diff_diff/stacked_did_results.py

@@ -98,6 +98,13 @@ class StackedDiDResults:
     # survey_design= is supplied the survey TSL/replicate variance overrides
     # the analytical family; this field still records the configured value.
     vcov_type: str = "hc1"
+    # Cluster identity ("unit" or "unit_subexp") and realized cluster count
+    # at fit time. Used by summary() to render the correct CR1/CR2-BM label
+    # via `_format_vcov_label(cluster_name=, n_clusters=)`. Per CI codex R2
+    # P2: passing cluster_name=None mislabelled clustered StackedDiD fits
+    # as one-way HC1/HC2-BM. StackedDiD is intrinsically clustered.
+    cluster_name: Optional[str] = None
+    n_clusters: Optional[int] = None
     # Survey design metadata (SurveyMetadata instance from diff_diff.survey)
     survey_metadata: Optional[Any] = field(default=None)
 
@@ -177,21 +184,17 @@ def summary(self, alpha: Optional[float] = None) -> str:
         ]
 
         # Variance family label (per CI codex R1 P2): surface the analytical
-        # vcov_type when the survey path didn't override. Mirrors the shared
-        # `_format_vcov_label` helper from results.py used by DiD/MPD/TWFE.
-        # Suppress under survey_metadata since the survey block above already
-        # reports the inference source.
+        # vcov_type when the survey path didn't override. Per R2 P2: pass
+        # cluster_name + n_clusters so the label renders as "CR1 cluster-
+        # robust at unit, G=N" rather than the one-way "HC1 heteroskedasticity-
+        # robust" — StackedDiD is intrinsically clustered.
         if self.survey_metadata is None and self.vcov_type:
             from diff_diff.results import _format_vcov_label
 
-            # StackedDiD is intrinsically clustered; the cluster name is
-            # either "unit" or "unit_subexp" (config-time, not stored
-            # explicitly on results — derive from the stacked data if
-            # available, else fall back to generic label).
             label = _format_vcov_label(
                 self.vcov_type,
-                cluster_name=None,  # cluster identity is config; print plain label
-                n_clusters=None,
+                cluster_name=self.cluster_name,
+                n_clusters=self.n_clusters,
                 n_obs=self.n_stacked_obs,
             )
             if label is not None:

tests/test_stacked_did.py

@@ -1678,3 +1678,40 @@ def test_hc1_vs_hc2_bm_differ_under_anticipation(self, staggered_data):
             "Under anticipation=1, hc1 vs hc2_bm SEs must differ — "
             "leverage/DOF adjustment didn't fire"
         )
+
+    def test_summary_renders_clustered_variance_label(self, staggered_data):
+        """Per CI codex R2 P2: summary() must render the clustered CR1/CR2-BM
+        label ('CR1 cluster-robust at unit, G=N' / 'CR2 Bell-McCaffrey
+        cluster-robust at unit, G=N'), NOT the one-way label ('HC1
+        heteroskedasticity-robust' / 'HC2 + Bell-McCaffrey DOF (one-way)').
+        StackedDiD is intrinsically clustered."""
+        kwargs = dict(outcome="outcome", unit="unit", time="period", first_treat="first_treat")
+        for vcov, expected_substr in [
+            ("hc1", "CR1 cluster-robust at unit"),
+            ("hc2_bm", "CR2 Bell-McCaffrey cluster-robust at unit"),
+        ]:
+            est = StackedDiD(kappa_pre=2, kappa_post=2, vcov_type=vcov, cluster="unit")
+            res = est.fit(staggered_data, **kwargs)
+            s = res.summary()
+            assert "Variance:" in s, f"summary() missing Variance: line for {vcov}"
+            variance_lines = [line for line in s.split("\n") if "Variance:" in line]
+            assert any(expected_substr in line for line in variance_lines), (
+                f"summary() variance label for vcov_type={vcov} should contain "
+                f"'{expected_substr}', got: {variance_lines}"
+            )
+            # MUST NOT render as one-way (would mislead users)
+            assert not any(
+                "(one-way" in line for line in variance_lines
+            ), f"vcov_type={vcov} mislabeled as one-way: {variance_lines}"
+            # G count present
+            assert any(
+                "G=" in line for line in variance_lines
+            ), f"summary() should include cluster count G= for {vcov}: {variance_lines}"
+        # Also test unit_subexp cluster level
+        est = StackedDiD(kappa_pre=2, kappa_post=2, vcov_type="hc2_bm", cluster="unit_subexp")
+        res = est.fit(staggered_data, **kwargs)
+        s = res.summary()
+        variance_lines = [line for line in s.split("\n") if "Variance:" in line]
+        assert any(
+            "at unit_subexp" in line for line in variance_lines
+        ), f"cluster='unit_subexp' should render in label: {variance_lines}"