fix(multi): honor storage options and validate explicit vcov data

`FixestMulti` stored the full input frame, the estimation config, and the
captured evaluation context on the container unconditionally, so
`store_data=False` and `lean=True` stripped every child result while the
container kept the very frame those options were asked to release. The
container now retains `_data`, `_config`, and `_context` only when the
options actually permit it; `_parsed` stays unconditional because the
container's formula accessors read it.

`FixestMulti.vcov()` gains the `data=` argument that child results already
accept, which is the only way to update a data-dependent covariance after
`store_data=False`. A forwarded frame must describe one estimation sample
shared by every child, and that has to be checked once, before any child is
touched: children are updated in a loop, so a mismatch discovered halfway
through would leave some results on the new covariance and the rest on the
old one. The preflight therefore rejects a row count that does not match
every child, and rejects children whose split sample or NA mask differ even
when their row counts agree, before the loop starts.

`QuantregMulti._clear_attributes` deleted `_within_data` from every child
after every fit, not only under the storage options, so a default
multi-quantile result had no design or response left and could neither
predict nor recompute its covariance. Fit state is now published through
`_publish_fit_state`, which also sets `_Y_hat_link` and `_Y_hat_response`
alongside `_beta_hat`, `_u_hat`, and `_hessian`, and the unconditional
deletion loop is gone; each child's own `_clear_attributes` still honors
`store_data=False` and `lean=True`.

Author: s3alfisc

docs/changelog.qmd

@@ -219,6 +219,13 @@ We also removed:
 
 - Removed `pf.dtable()`; use `maketables.DTable()` directly instead.
 
+Storage options:
+
+- `store_data=False` and `lean=True` now apply to multiple-estimation
+  containers; `FixestMulti.vcov()` accepts a common explicit estimation sample;
+  default multi-quantile results retain the arrays needed for prediction and
+  covariance updates.
+
 ### Bug Fixes
 
 - `lean=True` results keep the formula specification and evaluation context, so

pyfixest/estimation/FixestMulti_.py

@@ -13,6 +13,7 @@
 from pyfixest.estimation.models.feols_ import Feols
 from pyfixest.estimation.models.fepois_ import Fepois
 from pyfixest.estimation.plan_ import ParsedFormula
+from pyfixest.utils.dev_utils import DataFrameType, _narwhals_to_pandas
 
 
 class FixestMulti(TidyColumnAccessors):
@@ -67,10 +68,11 @@ def __init__(
         context : Mapping[str, Any]
             Captured evaluation scope (from `capture_context`).
         """
-        self._config = config
         self._parsed = parsed
-        self._data = data
-        self._context = context
+        if config.store_data and not config.lean:
+            self._config = config
+            self._data = data
+            self._context = context
 
         self.all_fitted_models: dict[str, Feols | Fepois | Feiv] = {}
 
@@ -119,7 +121,8 @@ def vcov(
         self,
         vcov: str | dict[str, str],
         vcov_kwargs: dict[str, str | int] | None = None,
-    ):
+        data: DataFrameType | None = None,
+    ) -> FixestMulti:
         """
         Update regression inference "on the fly".
 
@@ -137,13 +140,54 @@ def vcov(
             for CRV1 inference or {"CRV3": "clustervar"} for CRV3 inference.
         vcov_kwargs : Optional[dict[str, any]]
              Additional keyword arguments for the variance-covariance matrix.
+        data : DataFrameType, optional
+            The common, already-filtered estimation sample in its original order.
+            Required for data-dependent covariance updates when the fitted models
+            were created with `store_data=False`. Defaults to None.
 
         Returns
         -------
-            An instance of the "Fixest" class with updated inference.
+        FixestMulti
+            This result container with updated inference.
         """
+        data_to_forward = data
+        if data is not None:
+            try:
+                data_to_forward = _narwhals_to_pandas(data)
+            except TypeError as exc:
+                raise TypeError(
+                    f"The data set must be a DataFrame type. Received: {type(data)}"
+                ) from exc
+
+            models = list(self.all_fitted_models.values())
+            expected_rows = sorted({model._N_rows for model in models})
+            received_rows = len(data_to_forward)
+            if any(n_rows != received_rows for n_rows in expected_rows):
+                raise ValueError(
+                    "`data` passed to FixestMulti.vcov() must contain the common, "
+                    "already-filtered estimation sample in its original order for "
+                    "every child model; expected child row counts "
+                    f"{expected_rows}, received {received_rows}. Fetch each child "
+                    "model and call vcov(..., data=...) separately when estimation "
+                    "samples differ."
+                )
+
+            reference = models[0] if models else None
+            if reference is not None and any(
+                model._sample_split_var != reference._sample_split_var
+                or model._sample_split_value != reference._sample_split_value
+                or model._na_index != reference._na_index
+                for model in models[1:]
+            ):
+                raise ValueError(
+                    "`data` cannot be forwarded by FixestMulti.vcov() because its "
+                    "child models use different estimation samples. Fetch each "
+                    "child model and call vcov(..., data=...) with that model's "
+                    "already-filtered estimation sample instead."
+                )
+
         for fxst in self.all_fitted_models.values():
-            fxst.vcov(vcov=vcov, vcov_kwargs=vcov_kwargs)
+            fxst.vcov(vcov=vcov, vcov_kwargs=vcov_kwargs, data=data_to_forward)
         return self
 
     def tidy(self) -> pd.DataFrame:

pyfixest/estimation/quantreg/QuantregMulti.py

@@ -111,11 +111,11 @@ def get_fit(self) -> dict[float, Quantreg]:
             fit_kwargs["rng"] = rng
         beta_hat = self.all_quantregs[q[q_median_idx]]._fit(**fit_kwargs)[0]
 
-        self.all_quantregs[q[q_median_idx]]._beta_hat = beta_hat
-        self.all_quantregs[q[q_median_idx]]._u_hat = (
-            Y.flatten() - (X @ beta_hat).flatten()
+        self._publish_fit_state(
+            quantreg=self.all_quantregs[q[q_median_idx]],
+            beta_hat=beta_hat,
+            hessian=hessian,
         )
-        self.all_quantregs[q[q_median_idx]]._hessian = hessian
 
         def _direction_helper(i, direction):
             if direction == "left":
@@ -138,9 +138,11 @@ def _cfm1_fun(i, direction):
                 beta_hat = self.all_quantregs[q[i]].fit_qreg_pfn(
                     X=X, Y=Y, q=q[i], beta_init=beta_hat_prev, eta=0.5
                 )[0]
-                self.all_quantregs[q[i]]._beta_hat = beta_hat
-                self.all_quantregs[q[i]]._u_hat = Y.flatten() - (X @ beta_hat).flatten()
-                self.all_quantregs[q[i]]._hessian = hessian
+                self._publish_fit_state(
+                    quantreg=self.all_quantregs[q[i]],
+                    beta_hat=beta_hat,
+                    hessian=hessian,
+                )
 
             for i in range(q_median_idx - 1, -1, -1):
                 _cfm1_fun(i, "left")
@@ -164,12 +166,11 @@ def _cfm2_fun(i, direction):
                 M = X.T @ (q[i] - (u_hat_prev < 0))[:, None]
                 beta_new = beta_hat_prev + np.linalg.solve(J, M).flatten()
 
-                self.all_quantregs[q[i]]._beta_hat = beta_new
-                self.all_quantregs[q[i]]._u_hat = (
-                    self.all_quantregs[q[i]]._Y.flatten()
-                    - self.all_quantregs[q[i]]._X @ beta_new
+                self._publish_fit_state(
+                    quantreg=self.all_quantregs[q[i]],
+                    beta_hat=beta_new,
+                    hessian=hessian,
                 )
-                self.all_quantregs[q[i]]._hessian = hessian
 
             for i in range(q_median_idx - 1, -1, -1):
                 _cfm2_fun(i, "left")
@@ -188,6 +189,18 @@ def _cfm2_fun(i, direction):
         )
         return self.all_quantregs
 
+    @staticmethod
+    def _publish_fit_state(
+        *, quantreg: Quantreg, beta_hat: np.ndarray, hessian: np.ndarray
+    ) -> None:
+        """Publish canonical child state after a multi-quantile solver step."""
+        y_hat = quantreg._X @ beta_hat
+        quantreg._beta_hat = beta_hat
+        quantreg._Y_hat_link = y_hat
+        quantreg._Y_hat_response = y_hat
+        quantreg._u_hat = quantreg._Y.flatten() - y_hat
+        quantreg._hessian = hessian
+
     def vcov(
         self,
         vcov: str | dict[str, str],
@@ -221,9 +234,4 @@ def _clear_attributes(self) -> None:
         "Clear all large non-necessary attributes to free memory."
         for quantreg in self.all_quantregs.values():
             quantreg._clear_attributes()
-
-        # `_X` and `_Y` are read-only views, so their backing state is dropped.
-        for quantreg in self.all_quantregs.values():
-            if hasattr(quantreg, "_within_data"):
-                del quantreg._within_data
         gc.collect()

tests/test_estimator_state_lifecycle.py

@@ -478,6 +478,26 @@ def test_lean_iv_rejects_first_stage_diagnostics(
         getattr(fit, method)()
 
 
+@pytest.mark.parametrize("fit_kwargs", [{"store_data": False}, {"lean": True}])
+def test_multiple_estimation_respects_storage_options(
+    lifecycle_data: pd.DataFrame,
+    fit_kwargs: dict[str, bool],
+) -> None:
+    """The result container must not retain data cleared from all child fits."""
+    fit = pf.feols(
+        "y ~ sw(x, x2) | fe",
+        data=lifecycle_data,
+        vcov="iid",
+        **fit_kwargs,
+    )
+
+    assert isinstance(fit, FixestMulti)
+    assert not hasattr(fit, "_data")
+    assert not hasattr(fit, "_config")
+    assert not hasattr(fit, "_context")
+    assert all(not hasattr(model, "_data") for model in fit.to_list())
+
+
 def test_lean_results_predict_new_data_without_fixed_effects(
     lifecycle_data: pd.DataFrame,
 ) -> None:
@@ -556,6 +576,117 @@ def test_store_data_false_vcov_uses_explicit_estimation_sample(
     assert not hasattr(stripped, "_data")
 
 
+def test_fixest_multi_forwards_explicit_vcov_data(
+    lifecycle_data: pd.DataFrame,
+) -> None:
+    """Multiple-estimation covariance updates forward an explicit sample."""
+    stripped = pf.feols(
+        "y ~ sw(x, x2) | fe",
+        data=lifecycle_data,
+        vcov="iid",
+        store_data=False,
+    )
+    expected = pf.feols(
+        "y ~ sw(x, x2) | fe",
+        data=lifecycle_data,
+        vcov={"CRV1": "fe"},
+    )
+
+    stripped.vcov({"CRV1": "fe"}, data=lifecycle_data)
+
+    for stripped_model, expected_model in zip(
+        stripped.to_list(), expected.to_list(), strict=True
+    ):
+        np.testing.assert_allclose(stripped_model._vcov, expected_model._vcov)
+        assert not hasattr(stripped_model, "_data")
+
+
+def test_fixest_multi_vcov_preflights_different_estimation_samples(
+    lifecycle_data: pd.DataFrame,
+) -> None:
+    """A common-sample mismatch leaves every child model unchanged."""
+    data = lifecycle_data.copy()
+    data.loc[data.index[:3], "x2"] = np.nan
+    fit = pf.feols(
+        "y ~ sw(x, x2) | fe",
+        data=data,
+        vcov="iid",
+        store_data=False,
+    )
+    children = fit.to_list()
+    inference_before = [
+        (child._vcov_type_detail, child._vcov.copy()) for child in children
+    ]
+
+    with pytest.raises(
+        ValueError,
+        match=r"common, already-filtered estimation sample.*\[21, 24\], received 24",
+    ):
+        fit.vcov({"CRV1": "fe"}, data=data)
+
+    for child, (vcov_type_detail, vcov) in zip(children, inference_before, strict=True):
+        assert child._vcov_type_detail == vcov_type_detail
+        np.testing.assert_array_equal(child._vcov, vcov)
+
+
+def test_fixest_multi_vcov_rejects_equal_size_split_samples(
+    lifecycle_data: pd.DataFrame,
+) -> None:
+    """Equal row counts do not make distinct split samples interchangeable."""
+    data = lifecycle_data.assign(sample=np.tile(["left", "right"], 12))
+    fit = pf.feols(
+        "y ~ x | fe",
+        data=data,
+        split="sample",
+        vcov="iid",
+        store_data=False,
+    )
+    children = fit.to_list()
+    inference_before = [
+        (child._vcov_type_detail, child._vcov.copy()) for child in children
+    ]
+    left_sample = data.loc[data["sample"] == "left"]
+
+    with pytest.raises(
+        ValueError,
+        match=r"child models use different estimation samples.*Fetch each child",
+    ):
+        fit.vcov({"CRV1": "fe"}, data=left_sample)
+
+    for child, (vcov_type_detail, vcov) in zip(children, inference_before, strict=True):
+        assert child._vcov_type_detail == vcov_type_detail
+        np.testing.assert_array_equal(child._vcov, vcov)
+
+
+def test_fixest_multi_vcov_rejects_equal_size_distinct_na_masks(
+    lifecycle_data: pd.DataFrame,
+) -> None:
+    """Equal-sized formula expansions must retain the same source rows."""
+    data = lifecycle_data.copy()
+    data.loc[data.index[0], "x"] = np.nan
+    data.loc[data.index[1], "x2"] = np.nan
+    fit = pf.feols(
+        "y ~ sw(x, x2) | fe",
+        data=data,
+        vcov="iid",
+        store_data=False,
+    )
+    children = fit.to_list()
+    inference_before = [
+        (child._vcov_type_detail, child._vcov.copy()) for child in children
+    ]
+
+    with pytest.raises(
+        ValueError,
+        match=r"child models use different estimation samples.*Fetch each child",
+    ):
+        fit.vcov({"CRV1": "fe"}, data=data.drop(index=0))
+
+    for child, (vcov_type_detail, vcov) in zip(children, inference_before, strict=True):
+        assert child._vcov_type_detail == vcov_type_detail
+        np.testing.assert_array_equal(child._vcov, vcov)
+
+
 def test_vcov_rejects_unfiltered_explicit_data(
     lifecycle_data: pd.DataFrame,
 ) -> None:
@@ -758,3 +889,23 @@ def test_quantreg_lean_discards_solver_arrays() -> None:
     solver_arrays = ("_x_final", "_s_final", "_z_final", "_w_final", "_y_final")
     assert all(not hasattr(fit, attr) for attr in solver_arrays)
     assert np.isfinite(fit.coef()).all()
+
+
+def test_quantreg_multi_retains_default_post_estimation_state() -> None:
+    """Default multi-quantile results support prediction and vcov updates."""
+    rng = np.random.default_rng(20260901)
+    x = rng.normal(size=200)
+    data = pd.DataFrame({"y": 1 + 2 * x + rng.normal(size=200), "x": x})
+    with pytest.warns(FutureWarning, match="experimental"):
+        multi = pf.quantreg("y ~ x", data=data, quantile=[0.25, 0.75], vcov="iid")
+        single = pf.quantreg("y ~ x", data=data, quantile=0.25, vcov="hetero")
+
+    multi.vcov("hetero")
+
+    for model in multi.to_list():
+        assert np.isfinite(model.predict()).all()
+        assert np.isfinite(model.se()).all()
+
+    first_quantile = multi.fetch_model(0, print_fml=False)
+    np.testing.assert_allclose(first_quantile.predict(), single.predict())
+    np.testing.assert_allclose(first_quantile.se(), single.se())