Polish: document vcov_type on DifferenceInDifferences and MultiPeriodDiD

Class-level docstrings now fully describe the vcov_type enum (classical,
hc1, hc2, hc2_bm) on DifferenceInDifferences and MultiPeriodDiD, and
clarify that robust is a legacy alias. Renamed
test_set_params_rejects_conflict_on_robust_only to
test_set_params_robust_only_rederives_vcov_type so the name matches the
asserted behavior (robust-only mutation re-derives vcov_type from the
alias rather than raising).

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

Author: igerber

diff_diff/estimators.py

@@ -48,9 +48,25 @@ class DifferenceInDifferences:
         R-style formula for the model (e.g., "outcome ~ treated * post").
         If provided, overrides column name parameters.
     robust : bool, default=True
-        Whether to use heteroskedasticity-robust standard errors (HC1).
+        Legacy alias for ``vcov_type``. ``robust=True`` maps to
+        ``vcov_type="hc1"``; ``robust=False`` maps to ``vcov_type="classical"``.
+        Explicit ``vcov_type`` overrides ``robust`` unless the pair is
+        contradictory (e.g. ``robust=False, vcov_type="hc2"`` raises).
     cluster : str, optional
-        Column name for cluster-robust standard errors.
+        Column name for cluster-robust standard errors. Combined with
+        ``vcov_type``: with ``"hc1"`` dispatches to CR1 (Liang-Zeger); with
+        ``"hc2_bm"`` dispatches to CR2 Bell-McCaffrey (Pustejovsky-Tipton 2018
+        symmetric-sqrt + Satterthwaite DOF).
+    vcov_type : {"classical", "hc1", "hc2", "hc2_bm"}, optional
+        Variance-covariance family. Defaults to the ``robust`` alias.
+
+        - ``"classical"``: non-robust OLS SEs, ``sigma_hat^2 * (X'X)^{-1}``.
+        - ``"hc1"``: heteroskedasticity-robust HC1 with ``n/(n-k)`` adjustment
+          (library default). With ``cluster=``, uses CR1 (Liang-Zeger).
+        - ``"hc2"``: leverage-corrected meat (one-way only). Errors with
+          ``cluster=``; use ``"hc2_bm"`` for clustered Bell-McCaffrey.
+        - ``"hc2_bm"``: one-way HC2 + Imbens-Kolesar (2016) Satterthwaite DOF;
+          with ``cluster=``, Pustejovsky-Tipton (2018) CR2 cluster-robust.
     alpha : float, default=0.05
         Significance level for confidence intervals.
     inference : str, default="analytical"
@@ -833,9 +849,25 @@ class MultiPeriodDiD(DifferenceInDifferences):
     Parameters
     ----------
     robust : bool, default=True
-        Whether to use heteroskedasticity-robust standard errors (HC1).
+        Legacy alias for ``vcov_type``. ``robust=True`` maps to
+        ``vcov_type="hc1"``; ``robust=False`` maps to ``vcov_type="classical"``.
+        Explicit ``vcov_type`` overrides ``robust`` unless the pair is
+        contradictory (e.g. ``robust=False, vcov_type="hc2"`` raises).
     cluster : str, optional
-        Column name for cluster-robust standard errors.
+        Column name for cluster-robust standard errors. Combined with
+        ``vcov_type``: with ``"hc1"`` dispatches to CR1 (Liang-Zeger); with
+        ``"hc2_bm"`` dispatches to CR2 Bell-McCaffrey (Pustejovsky-Tipton 2018
+        symmetric-sqrt + Satterthwaite DOF).
+    vcov_type : {"classical", "hc1", "hc2", "hc2_bm"}, optional
+        Variance-covariance family. Defaults to the ``robust`` alias.
+
+        - ``"classical"``: non-robust OLS SEs, ``sigma_hat^2 * (X'X)^{-1}``.
+        - ``"hc1"``: heteroskedasticity-robust HC1 with ``n/(n-k)`` adjustment
+          (library default). With ``cluster=``, uses CR1 (Liang-Zeger).
+        - ``"hc2"``: leverage-corrected meat (one-way only). Errors with
+          ``cluster=``; use ``"hc2_bm"`` for clustered Bell-McCaffrey.
+        - ``"hc2_bm"``: one-way HC2 + Imbens-Kolesar (2016) Satterthwaite DOF;
+          with ``cluster=``, Pustejovsky-Tipton (2018) CR2 cluster-robust.
     alpha : float, default=0.05
         Significance level for confidence intervals.
 

tests/test_estimators_vcov_type.py

@@ -105,12 +105,16 @@ def test_set_params_rejects_conflict_robust_false_hc2(self):
         with pytest.raises(ValueError, match="robust=False conflicts with vcov_type"):
             est.set_params(robust=False, vcov_type="hc2")
 
-    def test_set_params_rejects_conflict_on_robust_only(self):
-        """Setting robust=False on an estimator with vcov_type='hc2_bm' raises."""
+    def test_set_params_robust_only_rederives_vcov_type(self):
+        """Setting robust= alone after init re-derives vcov_type from the alias.
+
+        When only ``robust`` is passed to ``set_params``, the new ``robust`` value
+        overrides the previously-set ``vcov_type`` via the alias rule:
+        ``robust=False`` -> ``"classical"``. This keeps the pair internally
+        consistent rather than leaving the estimator with ``robust=False,
+        vcov_type="hc2_bm"`` (a state that ``__init__`` forbids).
+        """
         est = DifferenceInDifferences(vcov_type="hc2_bm")
-        # The user is asking for non-robust SEs on an explicitly-HC2-BM estimator.
-        # set_params re-derives vcov_type to "classical" since only `robust` changed;
-        # this is a coherent override of the prior vcov_type, not a silent mismatch.
         est.set_params(robust=False)
         assert est.vcov_type == "classical"