MTN: make MapieRegressor and MapieQuantileRegressor private

Author: Valentin-Laurent

doc/api.rst

@@ -13,8 +13,6 @@ Regression
    mapie.regression.CrossConformalRegressor
    mapie.regression.JackknifeAfterBootstrapRegressor
    mapie.regression.ConformalizedQuantileRegressor
-   mapie.regression.MapieRegressor
-   mapie.regression.MapieQuantileRegressor
    mapie.regression.TimeSeriesRegressor
 
 Classification

doc/v1_migration_guide.rst

@@ -296,7 +296,7 @@ MAPIE v0.x Code
 
 Below is a MAPIE v0.x code for split conformal prediction in case of pre-fitted model:
 
-.. testcode::
+.. code:: python
 
     from sklearn.linear_model import LinearRegression
     from mapie.regression import MapieRegressor
@@ -366,7 +366,7 @@ MAPIE v0.x code
 
 Below is a MAPIE v0.x code for cross-conformal prediction:
 
-.. testcode::
+.. code:: python
 
     import numpy as np
     from sklearn.ensemble import RandomForestRegressor

examples/regression/1-quickstart/plot_prefit.py

@@ -180,7 +180,7 @@ def f(x: NDArray) -> NDArray:
 # three estimators need to be trained at quantile values of
 # ``(1+confidence_level)/2, (1-confidence_level)/2, 0.5)``.
 
-# Train LGBMRegressor models for MapieQuantileRegressor
+# Train LGBMRegressor models for _MapieQuantileRegressor
 list_estimators_cqr = []
 for alpha_ in [(1 - confidence_level) / 2, (1 + confidence_level) / 2, 0.5]:
     estimator_ = LGBMRegressor(

examples/regression/1-quickstart/plot_ts-tutorial.py

@@ -31,7 +31,6 @@
 the prediction intervals associated with one-step ahead forecasts through
 the EnbPI method.
 
-As its parent class :class:`~MapieRegressor`,
 :class:`~mapie.regression.TimeSeriesRegressor` has two main arguments :
 "cv", and "method".
 In order to implement EnbPI, "method" must be set to "enbpi" (the default

examples/regression/2-advanced-analysis/plot_coverage_validity.py

@@ -300,7 +300,7 @@ def cumulative_average(arr):
     )
     empirical_coverages_ref.append(coverage)
 
-    # Compute empirical coverage for each trial with MapieRegressor
+    # Compute empirical coverage for each trial
     conformalizer = SplitConformalRegressor(
         estimator=model, confidence_level=confidence_level, prefit=True
     )

mapie/quantile_regression.py

@@ -1,15 +1,12 @@
-from .quantile_regression import MapieQuantileRegressor, ConformalizedQuantileRegressor
+from .quantile_regression import ConformalizedQuantileRegressor
 from .regression import (
-    MapieRegressor,
     SplitConformalRegressor,
     CrossConformalRegressor,
     JackknifeAfterBootstrapRegressor,
 )
 from .time_series_regression import TimeSeriesRegressor
 
 __all__ = [
-    "MapieRegressor",
-    "MapieQuantileRegressor",
     "TimeSeriesRegressor",
     "SplitConformalRegressor",
     "CrossConformalRegressor",

mapie/regression/__init__.py

@@ -18,7 +18,7 @@
                          check_estimator_fit_predict, check_lower_upper_bounds,
                          check_null_weight, fit_estimator)
 
-from .regression import MapieRegressor
+from .regression import _MapieRegressor
 from mapie_v1.utils import (
     cast_predictions_to_ndarray_tuple,
     prepare_params,
@@ -113,7 +113,7 @@ def __init__(
         self._is_fitted = prefit
         self._is_conformalized = False
 
-        self._mapie_quantile_regressor = MapieQuantileRegressor(
+        self._mapie_quantile_regressor = _MapieQuantileRegressor(
             estimator=estimator,
             method="quantile",
             cv="prefit" if prefit else "split",
@@ -302,8 +302,12 @@ def predict(
         return predictions
 
 
-class MapieQuantileRegressor(MapieRegressor):
+class _MapieQuantileRegressor(_MapieRegressor):
     """
+    Note to users: _MapieQuantileRegressor is now private, and may change at any time.
+    Please use ConformalizedQuantileRegressor instead.
+    See the v1 migration guide for more information.
+
     This class implements the conformalized quantile regression strategy
     as proposed by Romano et al. (2019) to make conformal predictions.
 
@@ -372,12 +376,12 @@ class MapieQuantileRegressor(MapieRegressor):
     Examples
     --------
     >>> import numpy as np
-    >>> from mapie.regression import MapieQuantileRegressor
+    >>> from mapie.regression.quantile_regression import _MapieQuantileRegressor
     >>> X_train = np.array([[0], [1], [2], [3], [4], [5]])
     >>> y_train = np.array([5, 7.5, 9.5, 10.5, 12.5, 15])
     >>> X_calib = np.array([[0], [1], [2], [3], [4], [5], [6], [7], [8], [9]])
     >>> y_calib = np.array([5, 7, 9, 4, 8, 1, 5, 7.5, 9.5, 12])
-    >>> mapie_reg = MapieQuantileRegressor().fit(
+    >>> mapie_reg = _MapieQuantileRegressor().fit(
     ...     X_train,
     ...     y_train,
     ...     X_calib=X_calib,
@@ -496,7 +500,7 @@ def _check_estimator(
         """
         Perform several checks on the estimator to check if it has
         all the required specifications to be used with this methodology.
-        The estimators that can be used in MapieQuantileRegressor need to
+        The estimators that can be used in _MapieQuantileRegressor need to
         have a ``fit`` and ``predict`` attribute, but also need to allow
         a quantile loss and therefore also setting a quantile value.
         Note that there is a ``TypedDict`` to check which methods allow for
@@ -530,7 +534,7 @@ def _check_estimator(
 
         ValueError
             There is no quantile ``"loss_name"`` and therefore this estimator
-            can not be used as a ``MapieQuantileRegressor``.
+            can not be used as a ``_MapieQuantileRegressor``.
 
         ValueError
             The parameter to set the alpha value does not exist in this
@@ -714,7 +718,7 @@ def fit(
         shuffle: Optional[bool] = True,
         stratify: Optional[ArrayLike] = None,
         **fit_params,
-    ) -> MapieQuantileRegressor:
+    ) -> _MapieQuantileRegressor:
         """
         Fit estimator and compute residuals used for prediction intervals.
         All the clones of the estimators for different quantile values are
@@ -786,7 +790,7 @@ def fit(
 
         Returns
         -------
-        MapieQuantileRegressor
+        _MapieQuantileRegressor
              The model itself.
         """
         self._initialize_fit_conformalize()
@@ -922,10 +926,10 @@ def conformalize(
         X: ArrayLike,
         y: ArrayLike,
         sample_weight: Optional[ArrayLike] = None,
-        # Parameter groups kept for compliance with superclass MapieRegressor
+        # Parameter groups kept for compliance with superclass _MapieRegressor
         groups: Optional[ArrayLike] = None,
         **kwargs: Any,
-    ) -> MapieRegressor:
+    ) -> _MapieRegressor:
         if self.cv == "prefit":
             self._initialize_and_check_prefit_estimators()
 

mapie/regression/quantile_regression.py

@@ -130,7 +130,7 @@ def __init__(
         # Note to developers: to implement this v1 class without touching the
         # v0 backend, we're for now using a hack. We always set cv="prefit",
         # and we fit the estimator if needed. See the .fit method below.
-        self._mapie_regressor = MapieRegressor(
+        self._mapie_regressor = _MapieRegressor(
             estimator=self._estimator,
             method="base",
             cv="prefit",
@@ -409,7 +409,7 @@ def __init__(
         )
         check_cv_not_string(cv)
 
-        self._mapie_regressor = MapieRegressor(
+        self._mapie_regressor = _MapieRegressor(
             estimator=estimator,
             method=method,
             cv=cv,
@@ -722,7 +722,7 @@ def __init__(
 
         cv = self._check_and_convert_resampling_to_cv(resampling)
 
-        self._mapie_regressor = MapieRegressor(
+        self._mapie_regressor = _MapieRegressor(
             estimator=estimator,
             method=method,
             cv=cv,
@@ -909,8 +909,13 @@ def _check_and_convert_resampling_to_cv(
         return cv
 
 
-class MapieRegressor(RegressorMixin, BaseEstimator):
+class _MapieRegressor(RegressorMixin, BaseEstimator):
     """
+    Note to users: _MapieRegressor is now private, and may change at any time.
+    Please use CrossConformalRegressor, CrossConformalRegressor or
+    JackknifeAfterBootstrapRegressor instead.
+    See the v1 migration guide for more information.
+
     Prediction interval with out-of-fold conformity scores.
 
     This class implements the jackknife+ strategy and its variations
@@ -1075,12 +1080,12 @@ class MapieRegressor(RegressorMixin, BaseEstimator):
     Examples
     --------
     >>> import numpy as np
-    >>> from mapie.regression import MapieRegressor
+    >>> from mapie.regression.regression import _MapieRegressor
     >>> from sklearn.linear_model import LinearRegression
     >>> X_toy = np.array([[0], [1], [2], [3], [4], [5]])
     >>> y_toy = np.array([5, 7.5, 9.5, 10.5, 12.5, 15])
     >>> clf = LinearRegression().fit(X_toy, y_toy)
-    >>> mapie_reg = MapieRegressor(estimator=clf, cv="prefit")
+    >>> mapie_reg = _MapieRegressor(estimator=clf, cv="prefit")
     >>> mapie_reg = mapie_reg.fit(X_toy, y_toy)
     >>> y_pred, y_pis = mapie_reg.predict(X_toy, alpha=0.5)
     >>> print(y_pis[:, :, 0])
@@ -1358,7 +1363,7 @@ def fit(
         sample_weight: Optional[ArrayLike] = None,
         groups: Optional[ArrayLike] = None,
         **kwargs: Any
-    ) -> MapieRegressor:
+    ) -> _MapieRegressor:
         """
         Fit estimator and compute conformity scores used for
         prediction intervals.
@@ -1395,7 +1400,7 @@ def fit(
 
         Returns
         -------
-        MapieRegressor
+        _MapieRegressor
             The model itself.
         """
 
@@ -1449,7 +1454,7 @@ def fit_estimator(
         y: ArrayLike,
         sample_weight: Optional[ArrayLike] = None,
         groups: Optional[ArrayLike] = None,
-    ) -> MapieRegressor:
+    ) -> _MapieRegressor:
 
         self.estimator_.fit_single_estimator(
             X,
@@ -1468,7 +1473,7 @@ def conformalize(
         sample_weight: Optional[ArrayLike] = None,
         groups: Optional[ArrayLike] = None,
         **kwargs: Any
-    ) -> MapieRegressor:
+    ) -> _MapieRegressor:
 
         predict_params = kwargs.pop('predict_params', {})
         self._predict_params = len(predict_params) > 0

mapie/regression/regression.py

@@ -10,12 +10,12 @@
 
 from numpy.typing import ArrayLike, NDArray
 from mapie.conformity_scores import BaseRegressionScore
-from mapie.regression import MapieRegressor
+from mapie.regression.regression import _MapieRegressor
 from mapie.utils import check_alpha, check_gamma
 from mapie_v1.utils import transform_confidence_level_to_alpha_list
 
 
-class TimeSeriesRegressor(MapieRegressor):
+class TimeSeriesRegressor(_MapieRegressor):
     """
     Prediction intervals with out-of-fold residuals for time series.
     This class only has two valid ``method`` : ``"enbpi"`` or ``"aci"``
@@ -54,8 +54,7 @@ class TimeSeriesRegressor(MapieRegressor):
     https://arxiv.org/pdf/2202.07282.pdf
     """
 
-    cv_need_agg_function_ = MapieRegressor.cv_need_agg_function_ \
-        + ["BlockBootstrap"]
+    cv_need_agg_function_ = _MapieRegressor.cv_need_agg_function_ + ["BlockBootstrap"]
     valid_methods_ = ["enbpi", "aci"]
     default_sym_ = False