scikit-learn · ogrisel · Aug 31, 2021 · Jun 4, 2020 · Jun 4, 2020 · Jun 4, 2020
diff --git a/doc/modules/calibration.rst b/doc/modules/calibration.rst
@@ -30,11 +30,25 @@ approximately 80% actually belong to the positive class.
 Calibration curves
 ------------------
 
-The following plot compares how well the probabilistic predictions of
-different classifiers are calibrated, using :func:`calibration_curve`.
+Calibration curves (also known as reliability diagrams) compare how well the
+probabilistic predictions of a binary classifier are calibrated. It plots
+the true frequency of the positive label against its predicted probability,
+for binned predictions.
 The x axis represents the average predicted probability in each bin. The
 y axis is the *fraction of positives*, i.e. the proportion of samples whose
-class is the positive class (in each bin).
+class is the positive class (in each bin). The top calibration curve plot
+is created with :func:`CalibrationDisplay.from_estimators`, which uses
+:func:`calibration_curve` to calculate the per bin average predicted
+probabilities and fraction of positives.
+:func:`CalibrationDisplay.from_estimator`
+takes as input a fitted classifier, which is used to calculate the predicted
+probabilities. The classifier thus must have :term:`predict_proba` method. For
+the few classifiers that do not have a :term:`predict_proba` method, it is
+possible to use :class:`CalibratedClassifierCV` to calibrate the classifier
+outputs to probabilities.
+
+The bottom histogram gives some insight into the behavior of each classifier
+by showing the number of samples in each predicted probability bin.
 
 .. figure:: ../auto_examples/calibration/images/sphx_glr_plot_compare_calibration_001.png
    :target: ../auto_examples/calibration/plot_compare_calibration.html
@@ -161,6 +175,8 @@ mean a better calibrated model.
 :class:`CalibratedClassifierCV` supports the use of two 'calibration'
 regressors: 'sigmoid' and 'isotonic'.
 
+.. _sigmoid_regressor:
+
 Sigmoid
 ^^^^^^^
 

diff --git a/doc/modules/classes.rst b/doc/modules/classes.rst
@@ -1123,7 +1123,7 @@ See the :ref:`visualizations` section of the user guide for further details.
    metrics.DetCurveDisplay
    metrics.PrecisionRecallDisplay
    metrics.RocCurveDisplay
-
+   calibration.CalibrationDisplay
 
 .. _mixture_ref:
 

diff --git a/doc/visualizations.rst b/doc/visualizations.rst
@@ -65,6 +65,7 @@ values of the curves.
     * :ref:`sphx_glr_auto_examples_miscellaneous_plot_roc_curve_visualization_api.py`
     * :ref:`sphx_glr_auto_examples_miscellaneous_plot_partial_dependence_visualization_api.py`
     * :ref:`sphx_glr_auto_examples_miscellaneous_plot_display_object_visualization.py`
+    * :ref:`sphx_glr_auto_examples_calibration_plot_compare_calibration.py`
 
 Available Plotting Utilities
 ============================
@@ -90,6 +91,7 @@ Display Objects
 
 .. autosummary::
 
+   calibration.CalibrationDisplay
    inspection.PartialDependenceDisplay
    metrics.ConfusionMatrixDisplay
    metrics.DetCurveDisplay

diff --git a/doc/whats_new/v1.0.rst b/doc/whats_new/v1.0.rst
@@ -152,6 +152,9 @@ Changelog
   :class:`calibration.CalibratedClassifierCV` can now properly be used on
   prefitted pipelines. :pr:`19641` by :user:`Alek Lefebvre <AlekLefebvre>`.
 
+- |Feature| :func:`calibration.CalibrationDisplay` added to plot
+  calibration curves. :pr:`17443` by :user:`Lucy Liu <lucyleeow>`.
+
 - |Fix| Fixed an error when using a ::class:`ensemble.VotingClassifier`
   as `base_estimator` in ::class:`calibration.CalibratedClassifierCV`.
   :pr:`20087` by :user:`Clément Fauchereau <clement-f>`.