DOC: Improve terminology clarity in display classes

Yashp002 · Yashp002 · commit c62edd02545a · 2025-08-30T01:19:50.000+05:30
Replace ambiguous "chance level" terminology with clearer descriptions: - ROC curves: use "random classifier baseline" - PR curves: use "prevalence baseline" - Improves user understanding of reference lines Closes #30352
diff --git a/sklearn/metrics/_plot/precision_recall_curve.py b/sklearn/metrics/_plot/precision_recall_curve.py
@@ -47,8 +47,9 @@ class PrecisionRecallDisplay(_BinaryClassifierCurveDisplayMixin):
         .. versionadded:: 0.24
 
     prevalence_pos_label : float, default=None
-        The prevalence of the positive label. It is used for plotting the
-        chance level line. If None, the chance level line will not be plotted
+        The prevalence of the positive label. It is used for plotting the 
+        prevalence baseline line (horizontal line representing the proportion
+        of positive samples). If None, the baseline line will not be plotted
         even if `plot_chance_level` is set to True when plotting.
 
         .. versionadded:: 1.3
@@ -58,8 +59,10 @@ class PrecisionRecallDisplay(_BinaryClassifierCurveDisplayMixin):
     line_ : matplotlib Artist
         Precision recall curve.
 
-    chance_level_ : matplotlib Artist or None
-        The chance level line. It is `None` if the chance level is not plotted.
+    chance_level : matplotlib Artist or None
+    The prevalence baseline line (horizontal line representing the proportion
+    of positive samples). It is `None` if the baseline is not plotted.
+
 
         .. versionadded:: 1.3
 
@@ -154,15 +157,18 @@ def plot(
             `estimator_name` if not `None`, otherwise no labeling is shown.
 
         plot_chance_level : bool, default=False
-            Whether to plot the chance level. The chance level is the prevalence
-            of the positive label computed from the data passed during
+            Whether to plot the prevalence baseline. The baseline is the prevalence 
+            of the positive label computed from the data passed during 
             :meth:`from_estimator` or :meth:`from_predictions` call.
 
+
             .. versionadded:: 1.3
 
         chance_level_kw : dict, default=None
-            Keyword arguments to be passed to matplotlib's `plot` for rendering
-            the chance level line.
+            Keyword arguments to be passed to matplotlib's `plot` for rendering 
+            the prevalence baseline line (horizontal line representing the 
+            proportion of positive samples).
+
 
             .. versionadded:: 1.3
 
@@ -224,8 +230,8 @@ def plot(
             if self.prevalence_pos_label is None:
                 raise ValueError(
                     "You must provide prevalence_pos_label when constructing the "
-                    "PrecisionRecallDisplay object in order to plot the chance "
-                    "level line. Alternatively, you may use "
+                    "PrecisionRecallDisplay object in order to plot the prevalence "
+                    "baseline line. Alternatively, you may use "
                     "PrecisionRecallDisplay.from_estimator or "
                     "PrecisionRecallDisplay.from_predictions "
                     "to automatically set prevalence_pos_label"
@@ -326,15 +332,18 @@ def from_estimator(
             Axes object to plot on. If `None`, a new figure and axes is created.
 
         plot_chance_level : bool, default=False
-            Whether to plot the chance level. The chance level is the prevalence
-            of the positive label computed from the data passed during
-            :meth:`from_estimator` or :meth:`from_predictions` call.
+            Whether to plot the prevalence baseline (horizontal reference line). 
+            The baseline represents the prevalence of the positive label computed 
+            from the data passed during :meth:`from_estimator` or 
+            :meth:`from_predictions` call.
 
             .. versionadded:: 1.3
 
         chance_level_kw : dict, default=None
-            Keyword arguments to be passed to matplotlib's `plot` for rendering
-            the chance level line.
+            Keyword arguments to be passed to matplotlib's `plot` for rendering 
+            the prevalence baseline line (horizontal line representing the 
+            proportion of positive samples).
+
 
             .. versionadded:: 1.3
 
@@ -466,15 +475,19 @@ def from_predictions(
             Axes object to plot on. If `None`, a new figure and axes is created.
 
         plot_chance_level : bool, default=False
-            Whether to plot the chance level. The chance level is the prevalence
-            of the positive label computed from the data passed during
-            :meth:`from_estimator` or :meth:`from_predictions` call.
+            Whether to plot the prevalence baseline (horizontal reference line). 
+            The baseline represents the prevalence of the positive label computed 
+            from the data passed during :meth:`from_estimator` or 
+            :meth:`from_predictions` call.
+
 
             .. versionadded:: 1.3
 
         chance_level_kw : dict, default=None
-            Keyword arguments to be passed to matplotlib's `plot` for rendering
-            the chance level line.
+            Keyword arguments to be passed to matplotlib's `plot` for rendering 
+            the prevalence baseline line (horizontal line representing the 
+            proportion of positive samples).
+
 
             .. versionadded:: 1.3
 
diff --git a/sklearn/metrics/_plot/roc_curve.py b/sklearn/metrics/_plot/roc_curve.py
@@ -91,8 +91,11 @@ class RocCurveDisplay(_BinaryClassifierCurveDisplayMixin):
             This attribute can now be a list of Artists, for when multiple curves
             are plotted.
 
-    chance_level_ : matplotlib Artist or None
-        The chance level line. It is `None` if the chance level is not plotted.
+    chance_level : matplotlib Artist or None  
+         The random classifier baseline line representing chance performance.
+         It is `None` if the baseline is not plotted.
+
+
 
         .. versionadded:: 1.3
 
