BUG: Validate the method of AbsorbingLS.fit

linearmodels/iv/absorbing.py

@@ -136,6 +136,33 @@ def _options_key(options: dict[str, Any]) -> tuple[Any, ...]:
     return tuple(key)
 
 
+def _check_method(method: str) -> str:
+    """
+    Check the method used to absorb the variables
+
+    Parameters
+    ----------
+    method : str
+        The method that was passed to fit
+
+    Returns
+    -------
+    str
+        The method in lower case
+
+    Raises
+    ------
+    ValueError
+        If method is not "auto", "hdfe" or "lsmr", whatever its case
+    """
+    if isinstance(method, str) and method.lower() in ("auto", "hdfe", "lsmr"):
+        return method.lower()
+    raise ValueError(
+        'method must be one of "auto", "hdfe" or "lsmr", whatever its case. '
+        f"Got {method!r}."
+    )
+
+
 def _absorb_args(
     method: str, use_cache: bool, absorb_options: dict[str, Any] | None
 ) -> tuple[Any, ...]:
@@ -448,6 +475,7 @@ def __init__(
 
     @property
     def nobs(self) -> int:
+        """Number of observations, which drop reduces."""
         assert self._nobs is not None
         return self._nobs
 
@@ -502,8 +530,24 @@ def isnull(self) -> Series:
         return Series(cat_null.to_numpy() | cont_null.to_numpy(), index=index)
 
     def drop(self, locs: linearmodels.typing.data.BoolArray) -> None:
+        """
+        Drop observations.
+
+        Parameters
+        ----------
+        locs : ndarray
+            Boolean array with one element for each observation, which is True
+            for the observations to drop.
+
+        Notes
+        -----
+        The instance is modified in place and nothing is returned. Afterwards
+        ``nobs``, ``cat``, ``cont``, ``sparse`` and ``hash`` use only the
+        remaining observations.
+        """
         self._cat_data.drop(locs)
         self._cont_data.drop(locs)
+        self._nobs = self._cat_data.shape[0]
 
     @property
     def sparse(self) -> csc_array:
@@ -1198,8 +1242,9 @@ def fit(
         debiased : bool
             Flag indicating whether to debiased the covariance estimator using
             a degree of freedom adjustment.
-        method : str
-            One of:
+        method : {"auto", "hdfe", "lsmr"}, optional
+            The algorithm that absorbs the variables. The name is not case
+            sensitive, and a ValueError is raised for any other value. One of:
 
             * "auto" - (Default). Use HDFE when applicable and fallback to LSMR.
             * "lsmr" - Force LSMR.
@@ -1228,8 +1273,8 @@ def fit(
 
             .. deprecated:: 4.17
 
-               Use absorb_options to pass options. ``lsmr_options`` will be
-               removed in linearmodels 8.0.
+               Use absorb_options with method="lsmr" to pass options.
+               ``lsmr_options`` will be removed in linearmodels 8.0.
 
         cov_config
             Additional parameters to pass to covariance estimator. The list
@@ -1276,6 +1321,7 @@ def fit(
         linearmodels.iv.covariance.KernelCovariance
         linearmodels.iv.covariance.ClusteredCovariance
         """
+        method = _check_method(method)
         if lsmr_options and absorb_options is None:
             # The options are options of LSMR, so they can not be passed to HDFE
             if method == "hdfe":
@@ -1291,7 +1337,8 @@ def fit(
                 raise ValueError("absorb_options cannot be used with lsmr_options")
             warnings.warn(
                 "lsmr_options is deprecated and will be removed in linearmodels "
-                "8.0. Use absorb_options.",
+                '8.0. Use absorb_options with method="lsmr", which passes the options '
+                "to scipy.sparse.linalg.lsmr.",
                 FutureWarning,
                 stacklevel=2,
             )

linearmodels/iv/covariance.py

@@ -37,11 +37,11 @@
 ]
 
 CLUSTER_ERR = """\
-clusters has the wrong nobs. Expected {0}, got {1}.  Any missing observation
-in the regression variables have have been dropped.  When using a clustered
-covariance estimator, drop missing data before estimating the model. The model
-property `notnull` contains the locations of the observations that have no
-missing values."""
+clusters has the wrong nobs. Expected {0}, got {1}. Observations with a missing
+value in the regression variables are dropped when the model is created, so
+clusters must have one row for each of the remaining observations. When using a
+clustered covariance estimator, drop the observations with missing values from
+the data and from clusters before estimating the model."""
 
 
 def kernel_weight_bartlett(

linearmodels/iv/model.py

@@ -709,7 +709,7 @@ def fit(
             liml_kappa = nan
             if kappa is None:
                 raise ValueError(
-                    "Unable to estimate kappa. This is most likely occurs if the "
+                    "Unable to estimate kappa. This most likely occurs if the "
                     f"instrument matrix is rank deficient. The error raised when "
                     f"computing kappa was:\n\n{exc}"
                 ) from exc