Address thirty-seventh round of CI review findings on PR #318

P1 methodology (StaggeredTripleDiff never_treated surfaced
composite total as control). ``_extract_sample`` swapped to
``n_never_enabled`` only inside the dynamic ``notyettreated``
branch; under ``control_group="never_treated"`` it left
``n_control = n_control_units``. But
``staggered_triple_diff.py:384`` and REGISTRY.md §StaggeredTriple-
Difference (line 1730) define ``n_control_units`` as a composite
total that also includes eligibility-denied / larger-cohort
cells — the valid fixed comparison is only the never-enabled
cohort. BR's schema / ``summary()`` / ``full_report()`` therefore
misrepresented the comparison count on the ``nevertreated`` path.

Added a dedicated branch that fires whenever the canonical
control is ``nevertreated`` on ``StaggeredTripleDiffResults`` and
surfaces ``n_never_enabled`` as the fixed comparison tally
(``n_control`` set to None), regardless of whether the
``is_dynamic_control`` branch runs.

P1 code quality (broken CI clause on undefined inference).
``_render_headline_sentence`` gated CI rendering on
``isinstance(lo, (int, float))`` — which accepts ``NaN`` because
``NaN`` is a float — so a fit with a finite point estimate but
undefined CI endpoints (survey-df collapse, zero effective
clusters, ...) rendered
``(... 95% CI: undefined to undefined)`` in both ``summary()`` and
``full_report()``. DR's own headline renderer already gated on
``np.isfinite`` (round-36 fix); BR now mirrors that:

  * both CI bounds finite -> usual ``(ci_level% CI: lo to hi)``;
  * at least one bound supplied but not finite -> explicit
    ``(inference unavailable: confidence interval is undefined for
    this fit)`` trailer;
  * bounds absent -> no trailer.

Tests: 5 new regressions across two classes.

  * ``TestStaggeredTripleDiffNeverTreatedFixedComparison``
    (2 tests): schema-level ``n_control is None`` /
    ``n_never_enabled == 300`` on the ``never_treated`` mode, plus
    a prose assertion that the composite 500 does not appear as
    "500 control" in ``summary()``;
  * ``TestBRHeadlineOmitsBrokenCIOnUndefinedInference`` (2 tests):
    NaN-CI stub renders ``summary()`` and ``full_report()``
    without "undefined to undefined" / "CI: nan" fragments and
    with explicit "inference unavailable" language.

278 BR / DR / practitioner tests pass.

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

Author: igerber

diff_diff/business_report.py

@@ -568,6 +568,20 @@ def _extract_sample(self) -> Dict[str, Any]:
         is_dynamic_control = (
             _canonical_control == "notyettreated" or is_stacked_dynamic
         )
+        # StaggeredTripleDiff comparison-group contract:
+        # ``n_control_units`` is a composite total that also includes
+        # the eligibility-denied / larger-cohort cells. Regardless of
+        # the ``control_group`` mode the valid fixed comparison is the
+        # never-enabled cohort (``staggered_triple_diff.py:384``,
+        # REGISTRY.md §StaggeredTripleDifference line 1730). Round-37
+        # P1 CI review on PR #318: under ``control_group="never_treated"``
+        # (i.e., ``_canonical_control == "nevertreated"``) the composite
+        # total was being narrated as "control". Surface
+        # ``n_never_enabled`` instead on both the ``nevertreated`` and
+        # the dynamic ``notyettreated`` modes.
+        if name == "StaggeredTripleDiffResults" and _canonical_control == "nevertreated":
+            n_never_enabled = _safe_int(getattr(r, "n_never_enabled", None))
+            n_control = None
         if is_dynamic_control:
             if name == "StaggeredTripleDiffResults":
                 n_never_enabled = _safe_int(getattr(r, "n_never_enabled", None))
@@ -1661,11 +1675,31 @@ def _render_headline_sentence(schema: Dict[str, Any]) -> str:
     magnitude = _format_value(abs(effect), unit, unit_kind)
     lo = h.get("ci_lower")
     hi = h.get("ci_upper")
+    # Round-37 P1 CI review on PR #318: on a finite point estimate
+    # whose CI bounds are NaN (undefined inference — survey-df
+    # collapse, zero effective clusters, etc.), the previous isinstance
+    # check passed because ``NaN`` is a ``float`` and the sentence
+    # rendered ``(... 95% CI: undefined to undefined)``. Gate on
+    # ``np.isfinite`` like DR's own headline renderer already does;
+    # add an explicit inference-unavailable trailer instead of the
+    # broken CI clause.
     ci_str = ""
-    if isinstance(lo, (int, float)) and isinstance(hi, (int, float)):
+    ci_finite = (
+        isinstance(lo, (int, float))
+        and isinstance(hi, (int, float))
+        and np.isfinite(lo)
+        and np.isfinite(hi)
+    )
+    if ci_finite:
         lo_s = _format_value(lo, unit, unit_kind)
         hi_s = _format_value(hi, unit, unit_kind)
         ci_str = f" ({h.get('ci_level', 95)}% CI: {lo_s} to {hi_s})"
+    elif isinstance(lo, (int, float)) or isinstance(hi, (int, float)):
+        # At least one bound was supplied but not finite -> inference
+        # undefined. Replace the CI clause with an explicit marker so
+        # downstream prose does not claim a confidence interval that
+        # is not actually available.
+        ci_str = " (inference unavailable: confidence interval is undefined for this fit)"
     by_clause = f" by {magnitude}" if effect != 0 else ""
     return f"{treatment.capitalize()} {verb} {outcome}{by_clause}{ci_str}."
 

tests/test_business_report.py

@@ -1288,6 +1288,116 @@ def test_stacked_fit_persists_anticipation(self):
         assert a["anticipation_periods"] == 1
 
 
+class TestStaggeredTripleDiffNeverTreatedFixedComparison:
+    """Round-37 P1 CI review on PR #318: ``StaggeredTripleDiffResults``
+    stores ``n_control_units`` as a composite total that also includes
+    the eligibility-denied cohorts. The valid fixed comparison under
+    ``control_group="never_treated"`` is the never-enabled cohort
+    (``staggered_triple_diff.py:384``, REGISTRY.md §StaggeredTripleDifference
+    line 1730). BR was previously narrating the composite total as
+    "control" on the ``nevertreated`` mode; the fix surfaces
+    ``n_never_enabled`` as the fixed comparison count on that path
+    too (the dynamic ``notyettreated`` path was already correct).
+    """
+
+    @staticmethod
+    def _stub(control_group: str):
+        class StaggeredTripleDiffResults:
+            pass
+
+        stub = StaggeredTripleDiffResults()
+        stub.overall_att = 1.0
+        stub.overall_se = 0.2
+        stub.overall_p_value = 0.001
+        stub.overall_conf_int = (0.6, 1.4)
+        stub.alpha = 0.05
+        stub.n_obs = 800
+        stub.n_treated = 100
+        stub.n_control_units = 500  # composite total
+        stub.n_never_enabled = 300  # fixed never-enabled subset
+        stub.event_study_effects = None
+        stub.survey_metadata = None
+        stub.control_group = control_group
+        return stub
+
+    def test_never_treated_mode_surfaces_never_enabled_not_composite_total(self):
+        sample = BusinessReport(
+            self._stub("never_treated"), auto_diagnostics=False
+        ).to_dict()["sample"]
+        # Composite total must not be surfaced as the fixed control
+        # count on the ``nevertreated`` path.
+        assert sample["n_control"] is None, (
+            f"n_control must not carry the composite n_control_units "
+            f"total on StaggeredTripleDiff(control_group='never_treated'); "
+            f"got sample={sample!r}"
+        )
+        assert sample["n_never_enabled"] == 300
+
+    def test_never_treated_mode_summary_does_not_narrate_composite_as_control(self):
+        summary = BusinessReport(
+            self._stub("never_treated"), auto_diagnostics=False
+        ).summary()
+        # The composite total must not appear as "500 control" in prose.
+        import re
+
+        assert not re.search(r"\b500\s+control", summary), (
+            f"BR summary must not narrate the composite n_control_units "
+            f"total as 'control' on StaggeredTripleDiff(control_group="
+            f"'never_treated'); got: {summary!r}"
+        )
+
+
+class TestBRHeadlineOmitsBrokenCIOnUndefinedInference:
+    """Round-37 P1 CI review on PR #318: ``_extract_headline`` preserves
+    the fit's native CI even when it is undefined (e.g., survey-df
+    collapse produces finite ATT but NaN CI endpoints). The renderer
+    previously gated on ``isinstance(lo, (int, float))``, which accepts
+    ``NaN`` (a float) and rendered ``95% CI: undefined to undefined``.
+    Gate on ``np.isfinite`` instead, and emit an explicit
+    "inference unavailable" trailer when at least one bound is
+    non-finite. DR's own headline renderer already handled this
+    correctly (round-36 fix).
+    """
+
+    @staticmethod
+    def _stub_nan_ci():
+        class DiDResults:
+            pass
+
+        stub = DiDResults()
+        stub.att = 1.0
+        stub.se = float("nan")
+        stub.t_stat = float("nan")
+        stub.p_value = float("nan")
+        stub.conf_int = (float("nan"), float("nan"))
+        stub.alpha = 0.05
+        stub.n_obs = 200
+        stub.n_treated = 100
+        stub.n_control = 100
+        stub.survey_metadata = None
+        return stub
+
+    def test_summary_does_not_render_undefined_ci_interval(self):
+        summary = BusinessReport(
+            self._stub_nan_ci(), auto_diagnostics=False
+        ).summary()
+        lower = summary.lower()
+        # Must not render the broken CI interval fragment.
+        assert "undefined to undefined" not in lower, summary
+        assert "95% ci: nan" not in lower
+        # Must explicitly flag that inference is unavailable.
+        assert "inference unavailable" in lower
+
+    def test_full_report_does_not_render_undefined_ci_interval(self):
+        md = BusinessReport(
+            self._stub_nan_ci(), auto_diagnostics=False
+        ).full_report()
+        lower = md.lower()
+        assert "undefined to undefined" not in lower
+        assert "95% ci: nan" not in lower
+        assert "inference unavailable" in lower
+
+
 class TestStackedCleanControlSurfacesInSampleBlock:
     """Pre-emptive audit regression: ``StackedDiD`` exposes its control-
     group choice as ``clean_control`` (the public Wing-Freedman-