Skip to content

DOC Improve descriptions of roc_curve-related dosctrings #31238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Apr 28, 2025
+30 −16
Merged

DOC Improve descriptions of roc_curve-related dosctrings #31238

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4fcd34e
DOC Improve descriptions of roc_curve-related dosctrings
Apr 22, 2025
409c67e
Improve description of drop_intermediate parameter
Apr 22, 2025
0e7bb1e
Use versionchanged directive in description of the thresholds attribute
Apr 22, 2025
cd789b4
Cross-ref both visualizations and model evaluation from docstrings
Apr 28, 2025
7cbffdd
Avoid redundancy in thresholds description
Apr 28, 2025
3b6e62a
Apply suggestions from code review
ArturoAmorQ Apr 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 21 additions & 8 deletions sklearn/metrics/_plot/roc_curve.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,10 @@ class RocCurveDisplay(_BinaryClassifierCurveDisplayMixin):
a :class:`~sklearn.metrics.RocCurveDisplay`. All parameters are
stored as attributes.

Read more in the :ref:`User Guide <visualizations>`.
For general information regarding `scikit-learn` visualization tools, see
the :ref:`Visualization Guide <visualizations>`.
For guidance on interpreting these plots, refer to the :ref:`Model
Evaluation Guide <roc_metrics>`.

Parameters
----------
Expand Down Expand Up @@ -215,6 +218,11 @@ def from_estimator(
):
"""Create a ROC Curve display from an estimator.

For general information regarding `scikit-learn` visualization tools,
see the :ref:`Visualization Guide <visualizations>`.
For guidance on interpreting these plots, refer to the :ref:`Model
Evaluation Guide <roc_metrics>`.

Parameters
----------
estimator : estimator instance
Expand All @@ -231,9 +239,10 @@ def from_estimator(
Sample weights.

drop_intermediate : bool, default=True
Whether to drop some suboptimal thresholds which would not appear
on a plotted ROC curve. This is useful in order to create lighter
ROC curves.
Whether to drop thresholds where the resulting point is collinear
with its neighbors in ROC space. This has no effect on the ROC AUC
or visual shape of the curve, but reduces the number of plotted
points.

response_method : {'predict_proba', 'decision_function', 'auto'} \
default='auto'
Expand Down Expand Up @@ -343,7 +352,10 @@ def from_predictions(
):
"""Plot ROC curve given the true and predicted values.

Read more in the :ref:`User Guide <visualizations>`.
For general information regarding `scikit-learn` visualization tools,
see the :ref:`Visualization Guide <visualizations>`.
For guidance on interpreting these plots, refer to the :ref:`Model
Evaluation Guide <roc_metrics>`.

.. versionadded:: 1.0

Expand All @@ -364,9 +376,10 @@ def from_predictions(
Sample weights.

drop_intermediate : bool, default=True
Whether to drop some suboptimal thresholds which would not appear
on a plotted ROC curve. This is useful in order to create lighter
ROC curves.
Whether to drop thresholds where the resulting point is collinear
with its neighbors in ROC space. This has no effect on the ROC AUC
or visual shape of the curve, but reduces the number of plotted
points.

pos_label : int, float, bool or str, default=None
The label of the positive class. When `pos_label=None`, if `y_true`
Expand Down
17 changes: 9 additions & 8 deletions sklearn/metrics/_ranking.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1093,9 +1093,9 @@ def roc_curve(
Sample weights.

drop_intermediate : bool, default=True
Whether to drop some suboptimal thresholds which would not appear
on a plotted ROC curve. This is useful in order to create lighter
ROC curves.
Whether to drop thresholds where the resulting point is collinear with
its neighbors in ROC space. This has no effect on the ROC AUC or visual
shape of the curve, but reduces the number of plotted points.

.. versionadded:: 0.17
parameter *drop_intermediate*.
Expand All @@ -1112,8 +1112,12 @@ def roc_curve(

thresholds : ndarray of shape (n_thresholds,)
Decreasing thresholds on the decision function used to compute
fpr and tpr. `thresholds[0]` represents no instances being predicted
and is arbitrarily set to `np.inf`.
fpr and tpr. The first threshold is set to `np.inf`.

.. versionchanged:: 1.3
An arbitrary threshold at infinity (stored in `thresholds[0]`) is
added to represent a classifier that always predicts the negative
class, i.e. `fpr=0` and `tpr=0`.

See Also
--------
Expand All @@ -1130,9 +1134,6 @@ def roc_curve(
are reversed upon returning them to ensure they correspond to both ``fpr``
and ``tpr``, which are sorted in reversed order during their calculation.

An arbritrary threshold at infinity is added to represent a classifier
that always predicts the negative class, i.e. `fpr=0` and `tpr=0`.

References
----------
.. [1] `Wikipedia entry for the Receiver operating characteristic
Expand Down