Address PR #389 R7 P3: clustered weighted mass-point combinations rejected outright

The R6 wording said `cluster=` + `aggregate="event_study"` + `cband=True`
on mass-point could be made to work via `vcov_type="hc1"` / `robust=True`.
Per `had.py:4059-4095` and `had.py:3399-3447` (also documented in
REGISTRY:2380-2382) that path is rejected outright regardless of `vcov_type`,
and `survey_design=` + `cluster=` on weighted mass-point is similarly
rejected. The error is about variance-family mixing in the sup-t
bootstrap / Binder-TSL composition, not about the classical-default trap.

- `docs/api/had.rst` inline weights= shortcut summary: narrowed the CR1
  qualifier - "rejected outright regardless of `vcov_type`" + cross-link
  to a new sibling deviation note.
- `docs/api/had.rst` new "Mass-point cluster-combination deviation" note
  beside the existing classical-default note: enumerates the two rejected
  combinations (survey_design= + cluster= static and event-study;
  weights= + cluster= + cband=True event-study) with the implementation's
  own workaround language (cband=False / drop cluster= / cluster= alone /
  weights= + cluster=).
- `docs/choosing_estimator.rst` SE Methods row: dropped the misleading
  "requires explicit hc1/robust=True" implication; says rejected outright
  for both the weighted shortcut + cluster= + event_study cband and the
  survey_design= + cluster= mass-point combination.

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

Author: igerber

docs/api/had.rst

@@ -49,14 +49,12 @@ Unit Remains Untreated" (arXiv:2405.04465v6), which:
    - **``weights=np.ndarray`` shortcut (deprecated)** - continuous paths
      reuse the CCT-2014 SE; the mass-point path uses an analytical
      weighted 2SLS sandwich (``classical`` / ``hc1``; CR1 when
-     ``cluster=`` is supplied; ``hc2`` / ``hc2_bm`` raise
-     ``NotImplementedError`` pending a 2SLS-specific leverage
-     derivation). The mass-point + ``aggregate="event_study"`` +
-     ``cband=True`` sub-path additionally rejects an effective
-     ``classical`` vcov (so plain ``cluster=`` with the default
-     ``robust=False`` triggers the classical-default trap below;
-     pass ``vcov_type="hc1"`` or ``robust=True`` to use CR1 there).
-     Yields ``variance_formula="pweight"`` / ``"pweight_2sls"``.
+     ``cluster=`` is supplied, except ``cluster=`` +
+     ``aggregate="event_study"`` + ``cband=True`` is rejected outright
+     regardless of ``vcov_type`` per the cluster-combination deviation
+     below; ``hc2`` / ``hc2_bm`` raise ``NotImplementedError`` pending a
+     2SLS-specific leverage derivation). Yields
+     ``variance_formula="pweight"`` / ``"pweight_2sls"``.
    - **``survey_design=SurveyDesign(weights="col", ...)``** (canonical;
      accepts strata / PSU / FPC) - both paths compose Binder (1983)
      Taylor-series linearization with ``df_survey`` threaded into
@@ -100,6 +98,24 @@ Unit Remains Untreated" (arXiv:2405.04465v6), which:
    ``vcov_type="classical"``, which triggers the guard); a
    classical-aligned IF derivation is queued for a follow-up PR.
 
+   **Mass-point cluster-combination deviation.** On
+   ``design="mass_point"``, two clustered weighted paths are rejected
+   outright regardless of ``vcov_type``:
+
+   - ``survey_design=SurveyDesign(...)`` + ``cluster=`` (static and
+     event-study): the survey path composes Binder-TSL variance, which
+     would silently override the CR1 cluster-robust sandwich.
+     Workarounds: ``cluster=`` alone (unweighted CR1), or ``weights=``
+     + ``cluster=`` (weighted-CR1 pweight sandwich), or
+     ``survey_design=`` alone (Binder-TSL). Combined cluster-robust +
+     survey inference is queued for a follow-up PR.
+   - Deprecated ``weights=`` shortcut + ``cluster=`` +
+     ``aggregate="event_study"`` + ``cband=True``: the sup-t bootstrap
+     normalizes HC1-scale perturbations by the CR1 analytical SE,
+     mixing variance families. Workarounds: pass ``cband=False`` (keeps
+     weighted-CR1 per-horizon), or drop ``cluster=`` (keeps
+     weighted-HC1 sup-t).
+
 HeterogeneousAdoptionDiD
 ------------------------
 

docs/choosing_estimator.rst

@@ -664,7 +664,7 @@ differences helps interpret results and choose appropriate inference.
      - Uses influence-function-based SEs by default. Use ``n_bootstrap=199`` (or higher) for multiplier bootstrap inference with proper CIs.
    * - ``HeterogeneousAdoptionDiD``
      - Path-dependent (CCT-2014 / 2SLS / Binder TSL)
-     - Three SE regimes per :doc:`api/had`. **Unweighted**: continuous-dose paths use the CCT-2014 weighted-robust SE from the in-house ``lprobust`` port; mass-point uses a 2SLS sandwich. **Deprecated ``weights=`` shortcut**: continuous reuses CCT-2014; mass-point uses analytical weighted 2SLS (``classical`` / ``hc1``; CR1 when ``cluster=`` is supplied, except mass-point + ``aggregate="event_study"`` + ``cband=True`` requires explicit ``vcov_type="hc1"`` or ``robust=True`` per the classical-default exception in :doc:`api/had`); yields ``variance_formula="pweight"`` / ``"pweight_2sls"``. **``survey_design=SurveyDesign(weights="col", ...)``**: both paths compose Binder (1983) Taylor-series linearization (``"survey_binder_tsl"`` / ``"survey_binder_tsl_2sls"``). The two weighted families differ on this estimator until the next-minor unification lands. Per-horizon CIs are pointwise; sup-t bands available only on the weighted event-study path via ``cband=True``.
+     - Three SE regimes per :doc:`api/had`. **Unweighted**: continuous-dose paths use the CCT-2014 weighted-robust SE from the in-house ``lprobust`` port; mass-point uses a 2SLS sandwich. **Deprecated ``weights=`` shortcut**: continuous reuses CCT-2014; mass-point uses analytical weighted 2SLS (``classical`` / ``hc1``; CR1 when ``cluster=`` is supplied, except mass-point + ``cluster=`` + ``aggregate="event_study"`` + ``cband=True`` is rejected outright - see :doc:`api/had` for the cluster-combination deviation note); yields ``variance_formula="pweight"`` / ``"pweight_2sls"``. **``survey_design=SurveyDesign(weights="col", ...)``**: both paths compose Binder (1983) Taylor-series linearization (``"survey_binder_tsl"`` / ``"survey_binder_tsl_2sls"``); mass-point + ``survey_design=`` + ``cluster=`` is also rejected outright (combined survey + cluster inference is deferred). The two weighted families differ on this estimator until the next-minor unification lands. Per-horizon CIs are pointwise; sup-t bands available only on the weighted event-study path via ``cband=True``.
    * - ``SunAbraham``
      - Cluster-robust (unit level)
      - Clusters at unit level by default. Specify ``cluster`` to override. Use ``n_bootstrap`` for pairs bootstrap inference.