ENH/DEP add class method and deprecate plot function for confusion matrix (scikit-learn#18543)

glemaitre · thomasjpfan · adrinjalali · web-flow · commit 8c6a045e46ab · 2021-01-22T19:57:41.000+01:00
Co-authored-by: Thomas J. Fan &lt;thomasjpfan@gmail.com&gt;
Co-authored-by: Adrin Jalali &lt;adrin.jalali@gmail.com&gt;
diff --git a/doc/modules/model_evaluation.rst b/doc/modules/model_evaluation.rst
@@ -613,7 +613,7 @@ predicted to be in group :math:`j`. Here is an example::
          [0, 0, 1],
          [1, 0, 2]])
 
-:func:`plot_confusion_matrix` can be used to visually represent a confusion
+:class:`ConfusionMatrixDisplay` can be used to visually represent a confusion
 matrix as shown in the
 :ref:`sphx_glr_auto_examples_model_selection_plot_confusion_matrix.py`
 example, which creates the following figure:
diff --git a/doc/whats_new/v1.0.rst b/doc/whats_new/v1.0.rst
@@ -91,6 +91,17 @@ Changelog
   :pr:`17743` by :user:`Maria Telenczuk <maikia>` and
   :user:`Alexandre Gramfort <agramfort>`.
 
+:mod:`sklearn.metrics`
+......................
+
+- |API| :class:`metrics.ConfusionMatrixDisplay` exposes two class methods
+  :func:`~metrics.ConfusionMatrixDisplay.from_estimator` and
+  :func:`~metrics.ConfusionMatrixDisplay.from_predictions` allowing to create
+  a confusion matrix plot using an estimator or the predictions.
+  :func:`metrics.plot_confusion_matrix` is deprecated in favor of these two
+  class methods and will be removed in 1.2.
+  :pr:`18543` by `Guillaume Lemaitre`_.
+
 :mod:`sklearn.naive_bayes`
 ..........................
 
diff --git a/examples/classification/plot_digits_classification.py b/examples/classification/plot_digits_classification.py
@@ -95,7 +95,7 @@
 # We can also plot a :ref:`confusion matrix <confusion_matrix>` of the
 # true digit values and the predicted digit values.
 
-disp = metrics.plot_confusion_matrix(clf, X_test, y_test)
+disp = metrics.ConfusionMatrixDisplay.from_predictions(y_test, predicted)
 disp.figure_.suptitle("Confusion Matrix")
 print(f"Confusion matrix:\n{disp.confusion_matrix}")
 
diff --git a/examples/model_selection/plot_confusion_matrix.py b/examples/model_selection/plot_confusion_matrix.py
@@ -31,7 +31,7 @@
 
 from sklearn import svm, datasets
 from sklearn.model_selection import train_test_split
-from sklearn.metrics import plot_confusion_matrix
+from sklearn.metrics import ConfusionMatrixDisplay
 
 # import some data to play with
 iris = datasets.load_iris()
@@ -52,10 +52,10 @@
 titles_options = [("Confusion matrix, without normalization", None),
                   ("Normalized confusion matrix", 'true')]
 for title, normalize in titles_options:
-    disp = plot_confusion_matrix(classifier, X_test, y_test,
-                                 display_labels=class_names,
-                                 cmap=plt.cm.Blues,
-                                 normalize=normalize)
+    disp = ConfusionMatrixDisplay.from_estimator(
+        classifier, X_test, y_test, display_labels=class_names,
+        cmap=plt.cm.Blues, normalize=normalize
+    )
     disp.ax_.set_title(title)
 
     print(title)
diff --git a/sklearn/metrics/_plot/confusion_matrix.py b/sklearn/metrics/_plot/confusion_matrix.py
@@ -4,6 +4,7 @@
 
 from .. import confusion_matrix
 from ...utils import check_matplotlib_support
+from ...utils import deprecated
 from ...utils.multiclass import unique_labels
 from ...utils.validation import _deprecate_positional_args
 from ...base import is_classifier
@@ -12,7 +13,9 @@
 class ConfusionMatrixDisplay:
     """Confusion Matrix visualization.
 
-    It is recommend to use :func:`~sklearn.metrics.plot_confusion_matrix` to
+    It is recommend to use
+    :func:`~sklearn.metrics.ConfusionMatrixDisplay.from_estimator` or
+    :func:`~sklearn.metrics.ConfusionMatrixDisplay.from_predictions` to
     create a :class:`ConfusionMatrixDisplay`. All parameters are stored as
     attributes.
 
@@ -161,7 +164,274 @@ def plot(self, *, include_values=True, cmap='viridis',
         self.ax_ = ax
         return self
 
+    @classmethod
+    def from_estimator(
+        cls,
+        estimator,
+        X,
+        y,
+        *,
+        labels=None,
+        sample_weight=None,
+        normalize=None,
+        display_labels=None,
+        include_values=True,
+        xticks_rotation="horizontal",
+        values_format=None,
+        cmap="viridis",
+        ax=None,
+        colorbar=True,
+    ):
+        """Plot Confusion Matrix given an estimator and some data.
+
+        Read more in the :ref:`User Guide <confusion_matrix>`.
+
+        .. versionadded:: 1.0
 
+        Parameters
+        ----------
+        estimator : estimator instance
+            Fitted classifier or a fitted :class:`~sklearn.pipeline.Pipeline`
+            in which the last estimator is a classifier.
+
+        X : {array-like, sparse matrix} of shape (n_samples, n_features)
+            Input values.
+
+        y : array-like of shape (n_samples,)
+            Target values.
+
+        labels : array-like of shape (n_classes,), default=None
+            List of labels to index the confusion matrix. This may be used to
+            reorder or select a subset of labels. If `None` is given, those
+            that appear at least once in `y_true` or `y_pred` are used in
+            sorted order.
+
+        sample_weight : array-like of shape (n_samples,), default=None
+            Sample weights.
+
+        normalize : {'true', 'pred', 'all'}, default=None
+            Either to normalize the counts display in the matrix:
+
+            - if `'true'`, the confusion matrix is normalized over the true
+              conditions (e.g. rows);
+            - if `'pred'`, the confusion matrix is normalized over the
+              predicted conditions (e.g. columns);
+            - if `'all'`, the confusion matrix is normalized by the total
+              number of samples;
+            - if `None` (default), the confusion matrix will not be normalized.
+
+        display_labels : array-like of shape (n_classes,), default=None
+            Target names used for plotting. By default, `labels` will be used
+            if it is defined, otherwise the unique labels of `y_true` and
+            `y_pred` will be used.
+
+        include_values : bool, default=True
+            Includes values in confusion matrix.
+
+        xticks_rotation : {'vertical', 'horizontal'} or float, \
+                default='horizontal'
+            Rotation of xtick labels.
+
+        values_format : str, default=None
+            Format specification for values in confusion matrix. If `None`, the
+            format specification is 'd' or '.2g' whichever is shorter.
+
+        cmap : str or matplotlib Colormap, default='viridis'
+            Colormap recognized by matplotlib.
+
+        ax : matplotlib Axes, default=None
+            Axes object to plot on. If `None`, a new figure and axes is
+            created.
+
+        colorbar : bool, default=True
+            Whether or not to add a colorbar to the plot.
+
+        Returns
+        -------
+        display : :class:`~sklearn.metrics.ConfusionMatrixDisplay`
+
+        See Also
+        --------
+        ConfusionMatrixDisplay.from_predictions : Plot the confusion matrix
+            given the true and predicted labels.
+
+        Examples
+        --------
+        >>> import matplotlib.pyplot as plt  # doctest: +SKIP
+        >>> from sklearn.datasets import make_classification
+        >>> from sklearn.metrics import ConfusionMatrixDisplay
+        >>> from sklearn.model_selection import train_test_split
+        >>> from sklearn.svm import SVC
+        >>> X, y = make_classification(random_state=0)
+        >>> X_train, X_test, y_train, y_test = train_test_split(
+        ...         X, y, random_state=0)
+        >>> clf = SVC(random_state=0)
+        >>> clf.fit(X_train, y_train)
+        SVC(random_state=0)
+        >>> ConfusionMatrixDisplay.from_estimator(
+        ...     clf, X_test, y_test)  # doctest: +SKIP
+        >>> plt.show()  # doctest: +SKIP
+        """
+        method_name = f"{cls.__name__}.from_estimator"
+        check_matplotlib_support(method_name)
+        if not is_classifier(estimator):
+            raise ValueError(f"{method_name} only supports classifiers")
+        y_pred = estimator.predict(X)
+
+        return cls.from_predictions(
+            y,
+            y_pred,
+            sample_weight=sample_weight,
+            labels=labels,
+            normalize=normalize,
+            display_labels=display_labels,
+            include_values=include_values,
+            cmap=cmap,
+            ax=ax,
+            xticks_rotation=xticks_rotation,
+            values_format=values_format,
+            colorbar=colorbar,
+        )
+
+    @classmethod
+    def from_predictions(
+        cls,
+        y_true,
+        y_pred,
+        *,
+        labels=None,
+        sample_weight=None,
+        normalize=None,
+        display_labels=None,
+        include_values=True,
+        xticks_rotation="horizontal",
+        values_format=None,
+        cmap="viridis",
+        ax=None,
+        colorbar=True,
+    ):
+        """Plot Confusion Matrix given true and predicted labels.
+
+        Read more in the :ref:`User Guide <confusion_matrix>`.
+
+        .. versionadded:: 0.24
+
+        Parameters
+        ----------
+        y_true : array-like of shape (n_samples,)
+            True labels.
+
+        y_pred : array-like of shape (n_samples,)
+            The predicted labels given by the method `predict` of an
+            classifier.
+
+        labels : array-like of shape (n_classes,), default=None
+            List of labels to index the confusion matrix. This may be used to
+            reorder or select a subset of labels. If `None` is given, those
+            that appear at least once in `y_true` or `y_pred` are used in
+            sorted order.
+
+        sample_weight : array-like of shape (n_samples,), default=None
+            Sample weights.
+
+        normalize : {'true', 'pred', 'all'}, default=None
+            Either to normalize the counts display in the matrix:
+
+            - if `'true'`, the confusion matrix is normalized over the true
+              conditions (e.g. rows);
+            - if `'pred'`, the confusion matrix is normalized over the
+              predicted conditions (e.g. columns);
+            - if `'all'`, the confusion matrix is normalized by the total
+              number of samples;
+            - if `None` (default), the confusion matrix will not be normalized.
+
+        display_labels : array-like of shape (n_classes,), default=None
+            Target names used for plotting. By default, `labels` will be used
+            if it is defined, otherwise the unique labels of `y_true` and
+            `y_pred` will be used.
+
+        include_values : bool, default=True
+            Includes values in confusion matrix.
+
+        xticks_rotation : {'vertical', 'horizontal'} or float, \
+                default='horizontal'
+            Rotation of xtick labels.
+
+        values_format : str, default=None
+            Format specification for values in confusion matrix. If `None`, the
+            format specification is 'd' or '.2g' whichever is shorter.
+
+        cmap : str or matplotlib Colormap, default='viridis'
+            Colormap recognized by matplotlib.
+
+        ax : matplotlib Axes, default=None
+            Axes object to plot on. If `None`, a new figure and axes is
+            created.
+
+        colorbar : bool, default=True
+            Whether or not to add a colorbar to the plot.
+
+        Returns
+        -------
+        display : :class:`~sklearn.metrics.ConfusionMatrixDisplay`
+
+        See Also
+        --------
+        ConfusionMatrixDisplay.from_estimator : Plot the confusion matrix
+            given an estimator, the data, and the label.
+
+        Examples
+        --------
+        >>> import matplotlib.pyplot as plt  # doctest: +SKIP
+        >>> from sklearn.datasets import make_classification
+        >>> from sklearn.metrics import ConfusionMatrixDisplay
+        >>> from sklearn.model_selection import train_test_split
+        >>> from sklearn.svm import SVC
+        >>> X, y = make_classification(random_state=0)
+        >>> X_train, X_test, y_train, y_test = train_test_split(
+        ...         X, y, random_state=0)
+        >>> clf = SVC(random_state=0)
+        >>> clf.fit(X_train, y_train)
+        SVC(random_state=0)
+        >>> y_pred = clf.predict(X_test)
+        >>> ConfusionMatrixDisplay.from_predictions(
+        ...    y_test, y_pred)  # doctest: +SKIP
+        >>> plt.show()  # doctest: +SKIP
+        """
+        check_matplotlib_support(f"{cls.__name__}.from_predictions")
+
+        if display_labels is None:
+            if labels is None:
+                display_labels = unique_labels(y_true, y_pred)
+            else:
+                display_labels = labels
+
+        cm = confusion_matrix(
+            y_true,
+            y_pred,
+            sample_weight=sample_weight,
+            labels=labels,
+            normalize=normalize,
+        )
+
+        disp = cls(confusion_matrix=cm, display_labels=display_labels)
+
+        return disp.plot(
+            include_values=include_values,
+            cmap=cmap,
+            ax=ax,
+            xticks_rotation=xticks_rotation,
+            values_format=values_format,
+            colorbar=colorbar,
+        )
+
+
+@deprecated(
+    "Function plot_confusion_matrix is deprecated in 1.0 and will be "
+    "removed in 1.2. Use one of the class methods: "
+    "ConfusionMatrixDisplay.from_predictions or "
+    "ConfusionMatrixDisplay.from_estimator."
+)
 @_deprecate_positional_args
 def plot_confusion_matrix(estimator, X, y_true, *, labels=None,
                           sample_weight=None, normalize=None,
@@ -173,6 +443,12 @@ def plot_confusion_matrix(estimator, X, y_true, *, labels=None,
 
     Read more in the :ref:`User Guide <confusion_matrix>`.
 
+    .. deprecated:: 1.0
+       `plot_confusion_matrix` is deprecated in 1.0 and will be removed in
+       1.2. Use one of the following class methods:
+       :func:`~sklearn.metrics.ConfusionMatrixDisplay.from_predictions` or
+       :func:`~sklearn.metrics.ConfusionMatrixDisplay.from_estimator`.
+
     Parameters
     ----------
     estimator : estimator instance
@@ -194,9 +470,15 @@ def plot_confusion_matrix(estimator, X, y_true, *, labels=None,
         Sample weights.
 
     normalize : {'true', 'pred', 'all'}, default=None
-        Normalizes confusion matrix over the true (rows), predicted (columns)
-        conditions or all the population. If None, confusion matrix will not be
-        normalized.
+        Either to normalize the counts display in the matrix:
+
+            - if `'true'`, the confusion matrix is normalized over the true
+              conditions (e.g. rows);
+            - if `'pred'`, the confusion matrix is normalized over the
+              predicted conditions (e.g. columns);
+            - if `'all'`, the confusion matrix is normalized by the total
+              number of samples;
+            - if `None` (default), the confusion matrix will not be normalized.
 
     display_labels : array-like of shape (n_classes,), default=None
         Target names used for plotting. By default, `labels` will be used if
diff --git a/sklearn/metrics/_plot/tests/test_confusion_matrix_display.py b/sklearn/metrics/_plot/tests/test_confusion_matrix_display.py
diff --git a/sklearn/metrics/_plot/tests/test_plot_confusion_matrix.py b/sklearn/metrics/_plot/tests/test_plot_confusion_matrix.py
