Merge pull request #808 from bashtage/lm71-unknown-cov-type-error

ENH: Add UnknownOptionError for a name that is not supported

Author: bashtage

doc/source/utility.rst

@@ -31,6 +31,20 @@ Hypothesis Testing
    InapplicableTestStatistic
 
 
+Errors
+------
+
+.. currentmodule:: linearmodels.shared.exceptions
+
+The name of a covariance estimator (``cov_type``), of a weight matrix estimator
+(``weight_type``) or of a kernel (``kernel``) that is not supported raises an
+:class:`UnknownOptionError`, which lists the supported names. It is a ``ValueError``
+and a ``KeyError``.
+
+.. autoclass:: linearmodels.shared.exceptions.UnknownOptionError
+   :show-inheritance:
+
+
 Covariance Estimation
 ---------------------
 

linearmodels/asset_pricing/covariance.py

@@ -12,6 +12,7 @@
     cov_kernel,
     kernel_optimal_bandwidth,
 )
+from linearmodels.shared.exceptions import unknown_option_error
 import linearmodels.typing.data
 
 
@@ -47,7 +48,7 @@ def _check_kernel(self, kernel: str) -> None:
             raise TypeError("kernel must be the name of a kernel")
         self._kernel = kernel.lower()
         if self._kernel not in KERNEL_LOOKUP:
-            raise ValueError("Unknown kernel")
+            raise unknown_option_error("kernel", kernel, KERNEL_LOOKUP)
 
     def _check_bandwidth(self, bandwidth: float | None) -> None:
         self._bandwidth = bandwidth

linearmodels/asset_pricing/model.py

@@ -28,13 +28,16 @@
 from linearmodels.iv.data import IVData, IVDataLike
 from linearmodels.shared import hypotheses
 from linearmodels.shared.alignment import check_alignment, row_labels
-from linearmodels.shared.exceptions import missing_warning
+from linearmodels.shared.exceptions import missing_warning, unknown_option_error
 from linearmodels.shared.hypotheses import WaldTestStatistic
 from linearmodels.shared.linalg import has_constant
 from linearmodels.shared.typed_getters import get_float, get_string
 from linearmodels.shared.utility import AttrDict
 import linearmodels.typing.data
 
+# The names of the covariance estimators of the models
+COV_TYPES = ("heteroskedastic", "kernel", "robust")
+
 
 def callback_factory(
     obj: (
@@ -506,7 +509,7 @@ def fit(
                 kernel=kernel,
             )
         else:
-            raise ValueError(f"Unknown cov_type: {cov_type}")
+            raise unknown_option_error("cov_type", cov_type, COV_TYPES)
         full_vcv = cov_est.cov
         rp_cov = rp_cov_est.cov
         if debiased:
@@ -930,8 +933,8 @@ def fit(
         # Jacobian
         jacobian = self._jacobian(betas, lam, alphas)
 
-        if cov_type not in ("robust", "heteroskedastic", "kernel"):
-            raise ValueError(f"Unknown weight: {cov_type}")
+        if cov_type not in COV_TYPES:
+            raise unknown_option_error("cov_type", cov_type, COV_TYPES)
         if cov_type in ("robust", "heteroskedastic"):
             cov_est_inst = HeteroskedasticCovariance(
                 moments,
@@ -1347,8 +1350,8 @@ def fit(
         g -= g.mean(0)[None, :] if center else 0
         kernel: str | None = None
         bandwidth: float | None = None
-        if cov_type not in ("robust", "heteroskedastic", "kernel"):
-            raise ValueError(f"Unknown weight: {cov_type}")
+        if cov_type not in COV_TYPES:
+            raise unknown_option_error("cov_type", cov_type, COV_TYPES)
         if cov_type in ("robust", "heteroskedastic"):
             weight_est_instance = HeteroskedasticWeight(g, center=center)
             cov_est = HeteroskedasticCovariance

linearmodels/iv/absorbing.py

@@ -65,7 +65,7 @@
     reference_labels,
     row_labels,
 )
-from linearmodels.shared.exceptions import missing_warning
+from linearmodels.shared.exceptions import lookup_option, missing_warning
 from linearmodels.shared.hypotheses import InvalidTestStatistic, WaldTestStatistic
 from linearmodels.shared.inputs import as_array_like
 from linearmodels.shared.utility import DataFrameWrapper, SeriesWrapper
@@ -1471,7 +1471,7 @@ def fit(
         else:
             params = lstsq(exog_resid, dep_resid, rcond=None)[0]
 
-        cov_estimator = COVARIANCE_ESTIMATORS[cov_type]
+        cov_estimator = lookup_option(COVARIANCE_ESTIMATORS, cov_type, "cov_type")
         cov_config["debiased"] = debiased
         cov_config["kappa"] = 0.0
         cov_config_copy = dict(cov_config.items())

linearmodels/iv/common.py

@@ -26,6 +26,7 @@
     KernelWeightMatrix,
     OneWayClusteredWeightMatrix,
 )
+from linearmodels.shared.exceptions import unknown_option_error
 from linearmodels.shared.hypotheses import InvalidTestStatistic, WaldTestStatistic
 import linearmodels.typing.data
 
@@ -54,7 +55,8 @@ def _cov_family(cov_type: str) -> str:
     for family, aliases in _COV_FAMILIES.items():
         if name in aliases:
             return family
-    raise ValueError(f"Unsupported cov_type: {cov_type}")
+    supported = [alias for aliases in _COV_FAMILIES.values() for alias in aliases]
+    raise unknown_option_error("cov_type", cov_type, supported)
 
 
 def find_constant(x: linearmodels.typing.data.Float64Array) -> int | None:

linearmodels/iv/covariance.py

@@ -26,6 +26,7 @@
 from numpy.linalg import inv, pinv
 
 from linearmodels.shared.covariance import cov_cluster, cov_kernel
+from linearmodels.shared.exceptions import unknown_option_error
 from linearmodels.shared.inputs import as_ndarray
 from linearmodels.shared.linalg import has_constant
 import linearmodels.typing
@@ -258,7 +259,7 @@ def kernel_optimal_bandwidth(
         q, c = 2, 2.6614
         m_star = int(ceil(4 * (t / 100) ** (4 / 25)))
     else:
-        raise ValueError(f"Unknown kernel: {kernel}")
+        raise unknown_option_error("kernel", kernel, KERNEL_LOOKUP)
     sigma = empty(m_star + 1)
     sigma[0] = x.T @ x / t
     for i in range(1, m_star + 1):
@@ -597,7 +598,7 @@ def __init__(
         self._name = "Kernel Covariance (HAC)"
 
         if kernel not in KERNEL_LOOKUP:
-            raise ValueError(f"Unknown kernel: {kernel}")
+            raise unknown_option_error("kernel", kernel, KERNEL_LOOKUP)
 
     def __str__(self) -> str:
         out = super().__str__()

linearmodels/iv/gmm.py

@@ -18,7 +18,11 @@
     kernel_optimal_bandwidth,
 )
 from linearmodels.shared.covariance import cov_cluster, cov_kernel
-from linearmodels.shared.exceptions import DefaultBandwidthWarning
+from linearmodels.shared.exceptions import (
+    DefaultBandwidthWarning,
+    lookup_option,
+    unknown_option_error,
+)
 import linearmodels.typing.data
 
 
@@ -375,7 +379,7 @@ def weight_matrix(
             self._bandwidth = nobs - 2
         bw = self._bandwidth
         assert bw is not None
-        w = self._kernels[self._kernel](bw, nobs - 1)
+        w = lookup_option(self._kernels, self._kernel, "kernel")(bw, nobs - 1)
 
         s = cov_kernel(ze, w)
         s *= 1 if not self._debiased else nobs / (nobs - nvar)
@@ -590,7 +594,15 @@ def __init__(
         elif cov_type == "kernel":
             score_cov_estimator = KernelWeightMatrix
         else:
-            raise ValueError("Unknown cov_type")
+            supported = (
+                "clustered",
+                "heteroskedastic",
+                "homoskedastic",
+                "kernel",
+                "robust",
+                "unadjusted",
+            )
+            raise unknown_option_error("cov_type", cov_type, supported)
         self._score_cov_estimator = score_cov_estimator
 
     def __str__(self) -> str:

linearmodels/iv/model.py

@@ -62,7 +62,12 @@
     reference_labels,
     row_labels,
 )
-from linearmodels.shared.exceptions import IndexWarning, missing_warning
+from linearmodels.shared.exceptions import (
+    IndexWarning,
+    lookup_option,
+    missing_warning,
+    unknown_option_error,
+)
 from linearmodels.shared.hypotheses import InvalidTestStatistic, WaldTestStatistic
 from linearmodels.shared.linalg import has_constant, inv_sqrth
 from linearmodels.shared.utility import DataFrameWrapper, SeriesWrapper
@@ -741,7 +746,7 @@ def fit(
 
         params = self.estimate_parameters(wx, wy, wz, est_kappa)
 
-        cov_estimator = COVARIANCE_ESTIMATORS[cov_type]
+        cov_estimator = lookup_option(COVARIANCE_ESTIMATORS, cov_type, "cov_type")
         cov_config["debiased"] = debiased
         cov_config["kappa"] = est_kappa
         cov_config_copy = dict(cov_config.items())
@@ -1122,7 +1127,9 @@ def __init__(
         self._method = "IV-GMM"
 
         self._check_clusters(weight_config)
-        weight_matrix_estimator = WEIGHT_MATRICES[weight_type]
+        weight_matrix_estimator = lookup_option(
+            WEIGHT_MATRICES, weight_type, "weight_type"
+        )
         # Kernel weights without a bandwidth select it from the data. fit warns
         # about the change of this default, and makes the choice explicit so that
         # the weight estimators and models that are created from the arguments
@@ -2388,7 +2395,7 @@ def __init__(
         if cov_type == "kernel":
             kernel = cov_config.get("kernel", "bartlett")
             if kernel not in KERNEL_LOOKUP:
-                raise ValueError(f"Unknown kernel: {kernel}")
+                raise unknown_option_error("kernel", kernel, KERNEL_LOOKUP)
             # Select the bandwidth using the data unless it is given, as in
             # IV2SLS and IVLIML. This is the default of the weight matrix
             # estimator since 7.1, and it is explicit here so that it does not

linearmodels/panel/covariance.py

@@ -15,6 +15,7 @@
     kernel_optimal_bandwidth,
 )
 from linearmodels.shared.covariance import cluster_union, group_debias_coefficient
+from linearmodels.shared.exceptions import lookup_option, unknown_option_error
 from linearmodels.shared.typed_getters import (
     get_array_like,
     get_bool,
@@ -451,7 +452,7 @@ def cov(self) -> linearmodels.typing.data.Float64Array:
         if self._bandwidth is None:
             bw = float(np.floor(4 * (xe_nobs / 100) ** (2 / 9)))
         assert bw is not None
-        w = KERNEL_LOOKUP[self._kernel](bw, xe_nobs - 1)
+        w = lookup_option(KERNEL_LOOKUP, self._kernel, "kernel")(bw, xe_nobs - 1)
         xeex = cov_kernel(np.asarray(xe_df), w) * (xe_nobs / nobs)
         xeex *= self._scale
 
@@ -566,7 +567,7 @@ def _single_cov(
         self, xe: linearmodels.typing.data.Float64Array, bw: float
     ) -> linearmodels.typing.data.Float64Array:
         nobs = xe.shape[0]
-        w = KERNEL_LOOKUP[self._kernel](bw, nobs - 1)
+        w = lookup_option(KERNEL_LOOKUP, self._kernel, "kernel")(bw, nobs - 1)
         return cov_kernel(xe, w)
 
     @cached_property
@@ -644,14 +645,21 @@ def __init__(
         self._supported = cov_estimators
 
     def __getitem__(self, item: str) -> CovarianceEstimatorType:
+        # The names that the model supports, not all of the names that are known
+        supported = [
+            name
+            for name, estimator in self.COVARIANCE_ESTIMATORS.items()
+            if estimator in self._supported
+        ]
         if item not in self.COVARIANCE_ESTIMATORS:
-            raise KeyError("Unknown covariance estimator type.")
+            raise unknown_option_error("cov_type", item, supported)
         cov_est = self.COVARIANCE_ESTIMATORS[item]
         if cov_est not in self._supported:
-            raise ValueError(
+            problem = (
                 "Requested covariance estimator is not supported "
                 "for the {}.".format(self._estimator)
             )
+            raise unknown_option_error("cov_type", item, supported, problem=problem)
         return cov_est
 
 
@@ -724,7 +732,7 @@ def cov(self) -> linearmodels.typing.data.Float64Array:
 
         bw = self.bandwidth
         assert self._kernel is not None
-        w = KERNEL_LOOKUP[self._kernel](bw, nobs - 1)
+        w = lookup_option(KERNEL_LOOKUP, self._kernel, "kernel")(bw, nobs - 1)
         cov = cov_kernel(e, w)
         return cov / (nobs - int(bool(self._debiased)))
 

linearmodels/panel/model.py

@@ -62,6 +62,7 @@
     MissingValueWarning,
     SingletonWarning,
     missing_warning,
+    unknown_option_error,
 )
 from linearmodels.shared.hypotheses import (
     InapplicableTestStatistic,
@@ -3920,7 +3921,14 @@ def single(z: DataFrame) -> Series:
             "heteroskedastic",
             "kernel",
         ):
-            raise ValueError("Unknown cov_type")
+            supported = (
+                "heteroskedastic",
+                "homoskedastic",
+                "kernel",
+                "robust",
+                "unadjusted",
+            )
+            raise unknown_option_error("cov_type", cov_type, supported)
 
         bandwidth = 0.0 if cov_type != "kernel" else bandwidth
         cov = FamaMacBethCovariance(