scikit-learn · alexshtf · May 17, 2025 · May 17, 2025 · May 17, 2025 · May 18, 2025
diff --git a/doc/whats_new/_contributors.rst b/doc/whats_new/_contributors.rst
@@ -179,3 +179,5 @@
 .. _Guillaume Lemaitre: https://github.com/glemaitre
 
 .. _Tim Head: https://betatim.github.io/
+
+.. _Alex Shtoff: https://alexshtf.github.io/
diff --git a/doc/whats_new/upcoming_changes/sklearn.metrics/31380.feature.rst b/doc/whats_new/upcoming_changes/sklearn.metrics/31380.feature.rst
@@ -0,0 +1,8 @@
+The new functiom :func:`metrics.rec_curve` computes the Regression Error Characteristic
+(REC) curve of error tolerances vs the fraction of samples below the tolerance (the CDF
+of the regression errors). Suggested in the ICML'03 paper "Regression error
+characteristic curves" by Bi and Bennett as the regression-variant of the ROC curve.
+
+The new class :class:`metrics.RecCurveDisplay` visualizes the REC curves.
+
+By :user:`Alex Shtoff <alexshtf>`
diff --git a/examples/miscellaneous/plot_rec_curve_visualization.py b/examples/miscellaneous/plot_rec_curve_visualization.py
@@ -0,0 +1,105 @@
+"""
+=============================================
+Regression Error Characteristic curve display
+=============================================
+
+We illustrate how to display the regression error characteristic curve, and how to use
+it to compare various regression models.
+"""
+
+# Authors: The scikit-learn developers
+# SPDX-License-Identifier: BSD-3-Clause
+
+# %%
+# Data Loading and Preparation
+# ----------------------------
+#
+# Load the diabetes dataset. For simplicity, we only keep a single feature in the data.
+# Then, we split the data and target into training and test sets.
+from sklearn.datasets import fetch_california_housing
+from sklearn.model_selection import train_test_split
+
+X, y = fetch_california_housing(return_X_y=True, as_frame=True)
+X_train, X_test, y_train, y_test = train_test_split(
+    X, y, test_size=0.2, random_state=42, shuffle=True
+)
+
+# %%
+# Linear regression model
+# -----------------------
+#
+# We create a linear regression model and fit it on the training after standard scaling
+from sklearn.linear_model import LinearRegression
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+
+lr_estimator = make_pipeline(StandardScaler(), LinearRegression())
+lr_estimator.fit(X_train, y_train)
+
+# %%
+# Display REC curve using the test set. See that our linear regressor's REC curve
+# dominates the curve of the default constant predictor - the median. This is an
+# indicator that our model is doing something "reasonable".
+from sklearn.metrics import RecCurveDisplay
+
+RecCurveDisplay.from_estimator(lr_estimator, X_test, y_test, name="Linear regression")
+
+
+# %%
+# Compare two REC curves of linear regression to KNN and histogram gradient boosting
+# regressors. We can see a clear hierarchy here. KNN is strictly better than linear
+# regression for any error tolerance, and HGBR is strictly better than both for any
+# error tolerance.
+import matplotlib.pyplot as plt
+
+from sklearn.ensemble import HistGradientBoostingRegressor
+from sklearn.metrics import mean_absolute_error, root_mean_squared_error
+from sklearn.neighbors import KNeighborsRegressor
+
+hgbr_estimator = HistGradientBoostingRegressor()
+hgbr_estimator.fit(X_train, y_train)
+
+knn_estimator = make_pipeline(StandardScaler(), KNeighborsRegressor())
+knn_estimator.fit(X_train, y_train)
+
+pred_lr = lr_estimator.predict(X_test)
+pred_hgbr = hgbr_estimator.predict(X_test)
+pred_knn = knn_estimator.predict(X_test)
+
+lr_metrics = (
+    f"RMSE = {root_mean_squared_error(pred_lr, y_test):.2f}, "
+    f"MAE = {mean_absolute_error(pred_lr, y_test):.2f}"
+)
+hgbr_metrics = (
+    f"RMSE = {root_mean_squared_error(pred_hgbr, y_test):.2f}, "
+    f"MAE = {mean_absolute_error(pred_hgbr, y_test):.2f}"
+)
+knn_metrics = (
+    f"RMSE = {root_mean_squared_error(pred_knn, y_test):.2f}, "
+    f"MAE = {mean_absolute_error(pred_knn, y_test):.2f}"
+)
+
+fig, ax = plt.subplots()
+RecCurveDisplay.from_predictions(
+    y_test,
+    pred_lr,
+    ax=ax,
+    name=f"Linear regression ({lr_metrics})",
+    plot_const_predictor=False,
+)
+RecCurveDisplay.from_predictions(
+    y_test,
+    pred_knn,
+    ax=ax,
+    name=f"KNN ({knn_metrics})",
+    plot_const_predictor=False,
+)
+RecCurveDisplay.from_predictions(
+    y_test,
+    pred_hgbr,
+    ax=ax,
+    name=f"Gradient Boosting Regressor ({hgbr_metrics})",
+)
+fig.show()
+
+# %%
diff --git a/sklearn/metrics/__init__.py b/sklearn/metrics/__init__.py
@@ -30,6 +30,7 @@
 from ._plot.confusion_matrix import ConfusionMatrixDisplay
 from ._plot.det_curve import DetCurveDisplay
 from ._plot.precision_recall_curve import PrecisionRecallDisplay
+from ._plot.rec_curve import RecCurveDisplay
 from ._plot.regression import PredictionErrorDisplay
 from ._plot.roc_curve import RocCurveDisplay
 from ._ranking import (
@@ -65,6 +66,7 @@
     root_mean_squared_error,
     root_mean_squared_log_error,
 )
+from ._regression_characteristic import rec_curve
 from ._scorer import check_scoring, get_scorer, get_scorer_names, make_scorer
 from .cluster import (
     adjusted_mutual_info_score,
@@ -100,6 +102,7 @@
     "DistanceMetric",
     "PrecisionRecallDisplay",
     "PredictionErrorDisplay",
+    "RecCurveDisplay",
     "RocCurveDisplay",
     "accuracy_score",
     "adjusted_mutual_info_score",
@@ -168,6 +171,7 @@
     "precision_score",
     "r2_score",
     "rand_score",
+    "rec_curve",
     "recall_score",
     "roc_auc_score",
     "roc_curve",
Original file line number	Diff line number	Diff line change
Expand Up		@@ -179,3 +179,5 @@
		.. _Guillaume Lemaitre: https://github.com/glemaitre

		.. _Tim Head: https://betatim.github.io/

		.. _Alex Shtoff: https://alexshtf.github.io/