version to propose

doc/visualizations.rst

@@ -8,12 +8,19 @@ Scikit-learn defines a simple API for creating visualizations for machine
 learning. The key feature of this API is to allow for quick plotting and
 visual adjustments without recalculation. We provide `Display` classes that
 expose two methods for creating plots: `from_estimator` and
-`from_predictions`. The `from_estimator` method will take a fitted estimator
-and some data (`X` and `y`) and create a `Display` object. The `from_predictions``
-method creates a `Display` object when given the true and predicted values.
-We should use the latter when we want to compute the predictions only once.
+`from_predictions`.
+
+The `from_estimator` method generates a `Display` object from a fitted estimator and input data (X, y).
+And the `from_predictions` method creates a `Display` object when given the true and predicted values.
+This is useful when predictions should only be computed once.
+
+The `Display` object stores the computed values required for plotting with Matplotlib.
+These values can either be passed directly via `from_predictions`, or derived from an estimator
+and sample data using `from_estimator`.
+Additionally, the plot method allows adding to an existing plot via the ax parameter.
+
 In the following example, we plot a ROC curve for a fitted support
-vector machine:
+vector machine using `from_estimator`:
 
 .. plot::
    :context: close-figs
@@ -35,9 +42,9 @@ vector machine:
 The returned `svc_disp` object allows us to continue using the already computed
 ROC curve for SVC in future plots. In this case, the `svc_disp` is a
 :class:`~sklearn.metrics.RocCurveDisplay` that stores the computed values as
-attributes called `roc_auc`, `fpr`, and `tpr`. Be aware that we could get
-the predictions from the support vector machine and then use `from_predictions`
-instead of `from_estimator`. Next, we train a random forest classifier and plot
+attributes called `roc_auc`, `fpr`, and `tpr`.
+
+Next, we train a random forest classifier and plot
 the previously computed ROC curve again by using the `plot` method of the
 `Display` object.
 
@@ -58,6 +65,28 @@ the previously computed ROC curve again by using the `plot` method of the
 Notice that we pass `alpha=0.8` to the plot functions to adjust the alpha
 values of the curves.
 
+Finally, compared with the first example above, we can first obtain predictions
+from the support vector machine and then use `from_predictions` instead of `from_estimator`.
+
+
+.. plot::
+   :context: close-figs
+   :align: center
+
+   from sklearn.model_selection import train_test_split
+   from sklearn.svm import SVC
+   from sklearn.metrics import RocCurveDisplay
+   from sklearn.datasets import load_wine
+
+   X, y = load_wine(return_X_y=True)
+   y = y == 2  # make binary
+   X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=42)
+   svc = SVC(random_state=42).fit(X_train, y_train)
+   y_pred = svc.decision_function(X_test)
+
+   svc_disp = RocCurveDisplay.from_predictions(y_test, y_pred)
+
+
 .. rubric:: Examples
 
 * :ref:`sphx_glr_auto_examples_miscellaneous_plot_roc_curve_visualization_api.py`