scikit-learn · glemaitre · Jul 17, 2022 · Mar 10, 2022 · Mar 10, 2022 · Mar 10, 2022
diff --git a/doc/metadata_routing.rst b/doc/metadata_routing.rst
@@ -205,7 +205,7 @@ or not::
     ...     ).fit(X, y, sample_weight=my_weights)
     ... except ValueError as e:
     ...     print(e)
-    sample_weight is passed but is not explicitly set as requested or not for
+    [sample_weight] are passed but are not explicitly set as requested or not for
     LogisticRegression.score
 
 The issue can be fixed by explicitly setting the request value::

diff --git a/examples/plot_metadata_routing.py b/examples/plot_metadata_routing.py
@@ -37,7 +37,7 @@
 from sklearn.utils.metadata_routing import MethodMapping
 from sklearn.utils.metadata_routing import process_routing
 from sklearn.utils.validation import check_is_fitted
-from sklearn.linear_model import LinearRegression
+from sklearn.linear_model import LinearRegression, LogisticRegression
 
 N, M = 100, 4
 X = np.random.rand(N, M)
@@ -585,7 +585,7 @@ def get_metadata_routing(self):
 
 
 # %%
-# When an estimator suports a metadata which wasn't supported before, the
+# When an estimator supports a metadata which wasn't supported before, the
 # following pattern can be used to warn the users about it.
 
 
@@ -605,6 +605,53 @@ def predict(self, X):
 for w in record:
     print(w.message)
 
+# %%
+# Deprecation to Give Users Time to Adapt their Code
+# --------------------------------------------------
+# With the introduction of metadata routing, following user code would raise an
+# error:
+
+try:
+    reg = MetaRegressor(estimator=LinearRegression())
+    reg.fit(X, y, sample_weight=my_weights)
+except Exception as e:
+    print(e)
+
+# %%
+# You might want to give your users a period during which they see a
+# ``FutureWarning`` instead in order to have time to adapt to the new API. For
+# this, the :class:`~sklearn.utils.metadata_routing.MetadataRouter` provides a
+# `warn_on` method:
+
+
+class WarningMetaRegressor(MetaEstimatorMixin, RegressorMixin, BaseEstimator):
+    def __init__(self, estimator):
+        self.estimator = estimator
+
+    def fit(self, X, y, **fit_params):
+        params = process_routing(self, "fit", fit_params)
+        self.estimator_ = clone(self.estimator).fit(X, y, **params.estimator.fit)
+
+    def get_metadata_routing(self):
+        router = (
+            MetadataRouter(owner=self.__class__.__name__)
+            .add(estimator=self.estimator, method_mapping="one-to-one")
+            .warn_on(child="estimator", method="fit", params=None)
+        )
+        return router
+
+
+with warnings.catch_warnings(record=True) as record:
+    WarningMetaRegressor(estimator=LogisticRegression()).fit(
+        X, y, sample_weight=my_weights
+    )
+for w in record:
+    print(w.message)
+
+# %%
+# Note that in the above implementation, the value passed to ``child`` the same
+# as the key passed to the ``add`` method, in this case ``"estimator"``.
+
 # %%
 # Third Party Development and scikit-learn Dependency
 # ---------------------------------------------------

diff --git a/sklearn/exceptions.py b/sklearn/exceptions.py
@@ -13,9 +13,35 @@
     "SkipTestWarning",
     "UndefinedMetricWarning",
     "PositiveSpectrumWarning",
+    "UnsetMetadataPassedError",
 ]
 
 
+class UnsetMetadataPassedError(ValueError):
+    """Exception class to raise if a metadata is passed which is not explicitly \
+        requested.
+
+    .. versionadded:: 1.2
+
+    Parameters
+    ----------
+    message : str
+        The message
+
+    unrequested_params : dict
+        A dictionary of parameters and their values which are provided but not
+        requested.
+
+    routed_params : dict
+        A dictionary of routed parameters.
+    """
+
+    def __init__(self, *, message, unrequested_params, routed_params):
+        super().__init__(message)
+        self.unrequested_params = unrequested_params
+        self.routed_params = routed_params
+
+
 class NotFittedError(ValueError, AttributeError):
     """Exception class to raise if estimator is used before fitting.
 

diff --git a/sklearn/multioutput.py b/sklearn/multioutput.py
@@ -24,9 +24,10 @@
 from .model_selection import cross_val_predict
 from .utils.metaestimators import available_if
 from .utils import check_random_state
-from .utils.validation import check_is_fitted, has_fit_parameter, _check_fit_params
+from .utils.validation import check_is_fitted
 from .utils.multiclass import check_classification_targets
 from .utils.fixes import delayed
+from .utils.metadata_routing import MetadataRouter, MethodMapping, process_routing
 
 __all__ = [
     "MultiOutputRegressor",
@@ -46,21 +47,16 @@ def _fit_estimator(estimator, X, y, sample_weight=None, **fit_params):
 
 
 def _partial_fit_estimator(
-    estimator, X, y, classes=None, sample_weight=None, first_time=True
+    estimator, X, y, classes=None, partial_fit_params=None, first_time=True
 ):
+    partial_fit_params = {} if partial_fit_params is None else partial_fit_params
     if first_time:
         estimator = clone(estimator)
 
-    if sample_weight is not None:
-        if classes is not None:
-            estimator.partial_fit(X, y, classes=classes, sample_weight=sample_weight)
-        else:
-            estimator.partial_fit(X, y, sample_weight=sample_weight)
+    if classes is not None:
+        estimator.partial_fit(X, y, classes=classes, **partial_fit_params)
     else:
-        if classes is not None:
-            estimator.partial_fit(X, y, classes=classes)
-        else:
-            estimator.partial_fit(X, y)
+        estimator.partial_fit(X, y, **partial_fit_params)
     return estimator
 
 
@@ -85,7 +81,7 @@ def __init__(self, estimator, *, n_jobs=None):
         self.n_jobs = n_jobs
 
     @_available_if_estimator_has("partial_fit")
-    def partial_fit(self, X, y, classes=None, sample_weight=None):
+    def partial_fit(self, X, y, classes=None, sample_weight=None, **partial_fit_params):
         """Incrementally fit a separate model for each class output.
 
         Parameters
@@ -110,6 +106,11 @@ def partial_fit(self, X, y, classes=None, sample_weight=None):
             Only supported if the underlying regressor supports sample
             weights.
 
+        **partial_fit_params : dict of str -> object
+            Parameters passed to the ``estimator.partial_fit`` method of each step.
+
+            .. versionadded:: 1.2
+
         Returns
         -------
         self : object
@@ -124,10 +125,12 @@ def partial_fit(self, X, y, classes=None, sample_weight=None):
                 "multi-output regression but has only one."
             )
 
-        if sample_weight is not None and not has_fit_parameter(
-            self.estimator, "sample_weight"
-        ):
-            raise ValueError("Underlying estimator does not support sample weights.")
+        routed_params = process_routing(
+            obj=self,
+            method="partial_fit",
+            other_params=partial_fit_params,
+            sample_weight=sample_weight,
+        )
 
         first_time = not hasattr(self, "estimators_")
 
@@ -137,8 +140,8 @@ def partial_fit(self, X, y, classes=None, sample_weight=None):
                 X,
                 y[:, i],
                 classes[i] if classes is not None else None,
-                sample_weight,
-                first_time,
+                partial_fit_params=routed_params.estimator.partial_fit,
+                first_time=first_time,
             )
             for i in range(y.shape[1])
         )
@@ -192,16 +195,13 @@ def fit(self, X, y, sample_weight=None, **fit_params):
                 "multi-output regression but has only one."
             )
 
-        if sample_weight is not None and not has_fit_parameter(
-            self.estimator, "sample_weight"
-        ):
-            raise ValueError("Underlying estimator does not support sample weights.")
-
-        fit_params_validated = _check_fit_params(X, fit_params)
+        routed_params = process_routing(
+            obj=self, method="fit", other_params=fit_params, sample_weight=sample_weight
+        )
 
         self.estimators_ = Parallel(n_jobs=self.n_jobs)(
             delayed(_fit_estimator)(
-                self.estimator, X, y[:, i], sample_weight, **fit_params_validated
+                self.estimator, X, y[:, i], **routed_params.estimator.fit
             )
             for i in range(y.shape[1])
         )
@@ -240,6 +240,36 @@ def predict(self, X):
     def _more_tags(self):
         return {"multioutput_only": True}
 
+    def get_metadata_routing(self):
+        """Get metadata routing of this object.
+
+        Please check :ref:`User Guide <metadata_routing>` on how the routing
+        mechanism works.
+
+        Returns
+        -------
+        routing : MetadataRouter
+            A :class:`~utils.metadata_routing.MetadataRouter` encapsulating
+            routing information.
+        """
+        router = (
+            MetadataRouter(owner=self.__class__.__name__).add(
+                estimator=self.estimator,
+                method_mapping=MethodMapping()
+                .add(callee="partial_fit", caller="partial_fit")
+                .add(callee="fit", caller="fit"),
+            )
+            # the fit method already accepts everything, therefore we don't
+            # specify parameters. The value passed to ``child`` needs to be the
+            # same as what's passed to ``add`` above, in this case
+            # `"estimator"`.
+            .warn_on(child="estimator", method="fit", params=None)
+            # the partial_fit method at the time of this change (v1.2) only
+            # supports sample_weight, therefore we only include this metadata.
+            .warn_on(child="estimator", method="partial_fit", params=["sample_weight"])
+        )
+        return router
+
 
 class MultiOutputRegressor(RegressorMixin, _MultiOutputEstimator):
     """Multi target regression.
@@ -311,7 +341,7 @@ def __init__(self, estimator, *, n_jobs=None):
         super().__init__(estimator, n_jobs=n_jobs)
 
     @_available_if_estimator_has("partial_fit")
-    def partial_fit(self, X, y, sample_weight=None):
+    def partial_fit(self, X, y, sample_weight=None, **partial_fit_params):
         """Incrementally fit the model to data, for each output variable.
 
         Parameters
@@ -327,12 +357,17 @@ def partial_fit(self, X, y, sample_weight=None):
             Only supported if the underlying regressor supports sample
             weights.
 
+        **partial_fit_params : dict of str -> object
+            Parameters passed to the ``estimator.partial_fit`` method of each step.
+
+            .. versionadded:: 1.2
+
         Returns
         -------
         self : object
             Returns a fitted instance.
         """
-        super().partial_fit(X, y, sample_weight=sample_weight)
+        super().partial_fit(X, y, sample_weight=sample_weight, **partial_fit_params)
 
 
 class MultiOutputClassifier(ClassifierMixin, _MultiOutputEstimator):
@@ -419,7 +454,7 @@ def fit(self, X, Y, sample_weight=None, **fit_params):
 
         sample_weight : array-like of shape (n_samples,), default=None
             Sample weights. If `None`, then samples are equally weighted.
-            Only supported if the underlying classifier supports sample
+            Only supported if the underlying regressor supports sample
             weights.
 
         **fit_params : dict of string -> object
@@ -432,7 +467,7 @@ def fit(self, X, Y, sample_weight=None, **fit_params):
         self : object
             Returns a fitted instance.
         """
-        super().fit(X, Y, sample_weight, **fit_params)
+        super().fit(X, Y, sample_weight=sample_weight, **fit_params)
         self.classes_ = [estimator.classes_ for estimator in self.estimators_]
         return self