ENH: improve Risk Control API (#697)

FaustinPulveric · vincentblot28 · Valentin-Laurent · web-flow · commit cb829070d56c · 2025-05-15T14:54:46.000+02:00
* ENH: rename MapieMultiLabelClassifier to PrecisionRecallController and related file names

* ENH: renaming calib_size as conformalize_size in risk control class

* DOC: improve PrecisionRecallController docstring, mention API changes in v1 migration guide, update wording in documentation to keep coherence

---------

Co-authored-by: vincentblot28 &lt;vincentblot28@gmail.com&gt;
Co-authored-by: Valentin Laurent &lt;valentin.laurent.fr@gmail.com&gt;
diff --git a/doc/api.rst b/doc/api.rst
@@ -32,7 +32,7 @@ Multi-Label Classification
    :toctree: generated/
    :template: class.rst
 
-   mapie.multi_label_classification.MapieMultiLabelClassifier
+   mapie.risk_control.PrecisionRecallController
 
 Calibration
 ===========
diff --git a/doc/index.rst b/doc/index.rst
@@ -23,9 +23,9 @@
    :hidden:
    :caption: Control prediction errors
 
-   theoretical_description_multilabel_classification
-   examples_multilabel_classification/1-quickstart/plot_tutorial_multilabel_classification
-   notebooks_multilabel_classification
+   theoretical_description_risk_control
+   examples_multilabel_classification/1-quickstart/plot_tutorial_risk_control
+   notebooks_risk_control
 
 .. toctree::
    :maxdepth: 2
diff --git a/doc/notebooks_risk_control.rst b/doc/notebooks_risk_control.rst
@@ -1,12 +1,10 @@
-Multi-label Classification notebooks
+Risk control notebooks
 ====================================
 
-The following examples present advanced analyses
-on multi-label classification problems with different 
-methods proposed in MAPIE.
+The following examples present advanced analyses on risk control problems with different methods proposed in MAPIE.
 
-1. Overview of Recall Control for Multi-Label Classification : `recall_notebook <https://github.com/scikit-learn-contrib/MAPIE/tree/master/notebooks/classification/tutorial_multilabel_classification_recall.ipynb>`_
+1. Overview of Recall Control for Multi-Label Classification : `recall_notebook <https://github.com/scikit-learn-contrib/MAPIE/tree/master/notebooks/classification/tutorial_risk_control_recall.ipynb>`_
 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 
-2. Overview of Precision Control for Multi-Label Classification : `precision_notebook <https://github.com/scikit-learn-contrib/MAPIE/tree/master/notebooks/classification/tutorial_multilabel_classification_precision.ipynb>`_
+2. Overview of Precision Control for Multi-Label Classification : `precision_notebook <https://github.com/scikit-learn-contrib/MAPIE/tree/master/notebooks/classification/tutorial_risk_control_precision.ipynb>`_
 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
diff --git a/doc/theoretical_description_risk_control.rst b/doc/theoretical_description_risk_control.rst
@@ -1,15 +1,12 @@
-.. title:: Theoretical Description Multi label Classification : contents
+.. title:: Theoretical Description Recall and Precision Control for Multi label Classification : contents
 
-.. _theoretical_description_multilabel_classification:
+.. _theoretical_description_risk_control:
 
 #######################
 Theoretical Description
 #######################
 
-Note: in theoretical parts of the documentation, we use the following terms employed in the scientific literature:
-
-- `alpha` is equivalent to `1 - confidence_level`. It can be seen as a *risk level*
-- *calibrate* and *calibration*, are equivalent to *conformalize* and *conformalization*.
+Note: in theoretical parts of this documentation, we use the terms *calibrate* and *calibration* employed in the scientific literature, that are equivalent to *conformalize* and *conformalization*.
 
 —
 
diff --git a/doc/v1_migration_guide.rst b/doc/v1_migration_guide.rst
@@ -393,7 +393,9 @@ The already deprecated path to import the class (``from mapie.time_series_regres
 Risk control
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-TODO
+The ``MapieMultiLabelClassifier`` class has been renamed ``PrecisionRecallController``.
+
+The parameter ``calib_size`` from the ``fit`` method has been renamed ``conformalize_size``.
 
 Calibration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/examples/multilabel_classification/1-quickstart/plot_tutorial_risk_control.py b/examples/multilabel_classification/1-quickstart/plot_tutorial_risk_control.py
@@ -1,7 +1,7 @@
 """
-======================================
-Tutorial for multilabel-classification
-======================================
+=========================================================================
+Tutorial for recall and precision control for multi-label classification
+=========================================================================
 In this tutorial, we compare the prediction sets estimated by the
 RCPS and CRC methods implemented in MAPIE, for recall control purpose,
 on a two-dimensional toy dataset.
@@ -23,7 +23,7 @@
 from sklearn.multioutput import MultiOutputClassifier
 from sklearn.naive_bayes import GaussianNB
 
-from mapie.multi_label_classification import MapieMultiLabelClassifier
+from mapie.risk_control import PrecisionRecallController
 
 ##############################################################################
 # 1. Construction of the dataset
@@ -95,9 +95,9 @@
 ##############################################################################
 # 2 Recall control risk with CRC and RCPS
 # ----------------------------------------------------------------------------
-# 2.1 Fitting MapieMultiLabelClassifier
+# 2.1 Fitting PrecisionRecallController
 # ----------------------------------------------------------------------------
-# MapieMultiLabelClassifier will be fitted with RCPS and CRC methods. For the
+# PrecisionRecallController will be fitted with RCPS and CRC methods. For the
 # RCPS method, we will test all three Upper Confidence Bounds (Hoeffding,
 # Bernstein and Waudby-Smith–Ramdas).
 # The two methods give two different guarantees on the risk:
@@ -129,7 +129,7 @@
 y_test_repeat = np.repeat(y_test[:, :, np.newaxis], len(alpha), 2)
 for i, (name, (method, bound)) in enumerate(method_params.items()):
 
-    mapie = MapieMultiLabelClassifier(
+    mapie = PrecisionRecallController(
         estimator=clf, method=method, metric_control="recall"
     )
     mapie.fit(X_cal, y_cal)
@@ -217,7 +217,7 @@
 ##############################################################################
 # 3. Precision control risk with LTT
 # ----------------------------------------------------------------------------
-# 3.1 Fitting MapieMultilabelClassifier
+# 3.1 Fitting PrecisionRecallController
 # ----------------------------------------------------------------------------
 #
 # In this part, we will use LTT to control precision.
@@ -240,7 +240,7 @@
 # doesn't necessarly pass the FWER control! This is what we are going to
 # explore.
 
-mapie_clf = MapieMultiLabelClassifier(
+mapie_clf = PrecisionRecallController(
     estimator=clf,
     method='ltt',
     metric_control='precision'
diff --git a/mapie/__init__.py b/mapie/__init__.py
@@ -3,7 +3,7 @@
     metrics,
     regression,
     utils,
-    multi_label_classification,
+    risk_control,
     calibration,
     subsample,
 )
@@ -12,7 +12,7 @@
 __all__ = [
     "regression",
     "classification",
-    "multi_label_classification",
+    "risk_control",
     "calibration",
     "metrics",
     "utils",
diff --git a/mapie/control_risk/risks.py b/mapie/control_risk/risks.py
@@ -12,7 +12,7 @@ def compute_risk_recall(
     y: NDArray
 ) -> NDArray:
     """
-    In `MapieMultiLabelClassifier` when `metric_control=recall`,
+    In `PrecisionRecallController` when `metric_control=recall`,
     compute the recall per observation for each different
     thresholds lambdas.
 
@@ -70,7 +70,7 @@ def compute_risk_precision(
     y: NDArray
 ) -> NDArray:
     """
-    In `MapieMultiLabelClassifier` when `metric_control=precision`,
+    In `PrecisionRecallController` when `metric_control=precision`,
     compute the precision per observation for each different
     thresholds lambdas.
 
diff --git a/mapie/risk_control.py b/mapie/risk_control.py
@@ -21,7 +21,7 @@
 from .utils import _check_alpha, _check_n_jobs, _check_verbose
 
 
-class MapieMultiLabelClassifier(BaseEstimator, ClassifierMixin):
+class PrecisionRecallController(BaseEstimator, ClassifierMixin):
     """
     Prediction sets for multilabel-classification.
 
@@ -41,6 +41,17 @@ class MapieMultiLabelClassifier(BaseEstimator, ClassifierMixin):
 
          by default ``None``
 
+    metric_control : Optional[str]
+        Metric to control. Either "recall" or "precision".
+        By default ``recall``.
+
+    method : Optional[str]
+        Method to use for the prediction sets. If `metric_control` is
+        "recall", then the method can be either "crc" or "rcps".
+        If `metric_control` is "precision", then the method used to control
+        the precision is "ltt".
+        If `metric_control` is "recall" the default method is "crc".
+
     n_jobs: Optional[int]
         Number of jobs for parallel processing using joblib
         via the "locky" backend.
@@ -130,11 +141,11 @@ class MapieMultiLabelClassifier(BaseEstimator, ClassifierMixin):
     >>> import numpy as np
     >>> from sklearn.multioutput import MultiOutputClassifier
     >>> from sklearn.linear_model import LogisticRegression
-    >>> from mapie.multi_label_classification import MapieMultiLabelClassifier
+    >>> from mapie.risk_control import PrecisionRecallController
     >>> X_toy = np.arange(4).reshape(-1, 1)
     >>> y_toy = np.stack([[1, 0, 1], [1, 0, 0], [0, 1, 1], [0, 1, 0]])
     >>> clf = MultiOutputClassifier(LogisticRegression()).fit(X_toy, y_toy)
-    >>> mapie = MapieMultiLabelClassifier(estimator=clf).fit(X_toy, y_toy)
+    >>> mapie = PrecisionRecallController(estimator=clf).fit(X_toy, y_toy)
     >>> _, y_pi_mapie = mapie.predict(X_toy, alpha=0.3)
     >>> print(y_pi_mapie[:, :, 0])
     [[ True False  True]
@@ -341,7 +352,7 @@ def _check_estimator(
 
         Warning
             If estimator is then to warn about the split of the
-            data between train and calibration
+            data between train and conformalization
         """
         if (estimator is None) and (not _refit):
             raise ValueError(
@@ -353,19 +364,19 @@ def _check_estimator(
             estimator = MultiOutputClassifier(
                 LogisticRegression()
             )
-            X_train, X_calib, y_train, y_calib = train_test_split(
+            X_train, X_conf, y_train, y_conf = train_test_split(
                     X,
                     y,
-                    test_size=self.calib_size,
+                    test_size=self.conformalize_size,
                     random_state=self.random_state,
             )
             estimator.fit(X_train, y_train)
             warnings.warn(
-                "WARNING: To avoid overffiting, X has been splitted"
+                "WARNING: To avoid overfitting, X has been split"
                 + "into X_train and X_conf. The conformalization will only"
                 + "be done on X_conf"
             )
-            return estimator, X_calib, y_calib
+            return estimator, X_conf, y_conf
 
         if isinstance(estimator, Pipeline):
             est = estimator[-1]
@@ -464,7 +475,7 @@ def _transform_pred_proba(
 
         Returns
         -------
-        NDArray of shape (n_samples, n_classe, 1)
+        NDArray of shape (n_samples, n_classes, 1)
             Output of the model ready for risk computation.
         """
         if isinstance(y_pred_proba, np.ndarray):
@@ -483,7 +494,7 @@ def partial_fit(
         X: ArrayLike,
         y: ArrayLike,
         _refit: Optional[bool] = False,
-    ) -> MapieMultiLabelClassifier:
+    ) -> PrecisionRecallController:
         """
         Fit the base estimator or use the fitted base estimator on
         batch data. All the computed risks will be concatenated each
@@ -504,7 +515,7 @@ def partial_fit(
 
         Returns
         -------
-        MapieMultiLabelClassifier
+        PrecisionRecallController
             The model itself.
         """
         # Checks
@@ -568,8 +579,8 @@ def fit(
         self,
         X: ArrayLike,
         y: ArrayLike,
-        calib_size: Optional[float] = .3
-    ) -> MapieMultiLabelClassifier:
+        conformalize_size: Optional[float] = .3
+    ) -> PrecisionRecallController:
         """
         Fit the base estimator or use the fitted base estimator.
 
@@ -581,18 +592,18 @@ def fit(
         y: NDArray of shape (n_samples, n_classes)
             Training labels.
 
-        calib_size: Optional[float]
-            Size of the calibration dataset with respect to X if the
+        conformalize_size: Optional[float]
+            Size of the conformity dataset with respect to X if the
             given model is ``None`` need to fit a LogisticRegression.
 
             By default .3
 
         Returns
         -------
-        MapieMultiLabelClassifier
+        PrecisionRecallController
             The model itself.
         """
-        self.calib_size = calib_size
+        self.conformalize_size = conformalize_size
         return self.partial_fit(X, y, _refit=True)
 
     def predict(
diff --git a/mapie/tests/test_risk_control.py b/mapie/tests/test_risk_control.py
diff --git a/notebooks/classification/tutorial_risk_control_precision.ipynb b/notebooks/classification/tutorial_risk_control_precision.ipynb
diff --git a/notebooks/classification/tutorial_risk_control_recall.ipynb b/notebooks/classification/tutorial_risk_control_recall.ipynb
