ENH: change param symmetric_interval (incorrectly named) to symmetric…

…_correction, and set it to False by default. Updated and improved migration guide

doc/v1_migration_guide.rst

@@ -73,7 +73,7 @@ A parameter used to specify the scoring approach for evaluating model prediction
 - **v0.9**: Only allowed custom objects derived from ``BaseRegressionScore``.
 - **v1**: Now accepts both strings (like ``"absolute"``) for predefined methods and custom ``BaseRegressionScore`` instances, simplifying usage.
 
-``confidence_level``
+``alpha``
 ~~~~~~~~~~~~~~~~~~~~
 Indicates the desired coverage probability of the prediction intervals.
 
@@ -122,7 +122,7 @@ Defines additional parameters exclusively for prediction.
 - **v0.9**: Passed additional parameters in a flexible but less explicit manner, sometimes mixed within training configurations.
 - **v1**: Now structured as a dedicated dictionary, ``predict_params``, to be used during calibration (``conformalize`` method) and prediction stages, ensuring no overlap with training parameters.
 
-``agg_function``, ``aggregation_method``, ``aggregate_predictions``, and ``ensemble``
+``agg_function`` and ``ensemble``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The aggregation method and technique for combining predictions in cross conformal methods.
 
@@ -137,18 +137,24 @@ The aggregation method and technique for combining predictions in cross conforma
 - **v0.9**: This parameter was used to control the randomness of the data splitting.
 - **v1**: This parameter has been removed in cases where data splitting is now manual. Future evolutions may reintroduce it as a general purpose randomness control parameter.
 
-``Other parameters``
+``symmetry``
+~~~~~~~~~~~~~~~~~~
+
+- **v0.9**: This parameter of the `predict` method of the MapieQuantileRegressor was set to True by default
+- **v1**: This parameter is now named `symmetric_correction` and is set to False by default, because the resulting intervals are smaller. It is used in the `predict_interval` method of the ConformalizedQuantileRegressor.
+
+``optimize_beta``
+~~~~~~~~~~~~~~~~~~
+
+This parameter used during interval prediction in regression has been renamed ``minimize_interval_width`` for clarity.
+
+None defaults
 ~~~~~~~~~~~~~~~~~~~~
 No more parameters with incorrect ``None`` defaults.
 
 - **v0.9**: Eg: ``estimator`` had a ``None`` default value, even though the actual default value is ``LinearRegression()``. This was the case for other parameters as well.
 - **v1**: All parameters now have explicit defaults.
 
-Some parameters' name have been improved for clarity:
-
-- ``optimize_beta`` -> ``minimize_interval_width``
-- ``symmetry``-> ``symmetric_intervals``
-
 
 4. Migration example: MAPIE v0.9 to MAPIE v1
 ----------------------------------------------------------------------------------------

mapie_v1/regression.py

@@ -1077,7 +1077,7 @@ def predict_interval(
         X: ArrayLike,
         minimize_interval_width: bool = False,
         allow_infinite_bounds: bool = False,
-        symmetric_intervals: bool = True,
+        symmetric_correction: bool = False,
     ) -> Tuple[NDArray, NDArray]:
         """
         Predicts points and intervals.
@@ -1097,12 +1097,14 @@ def predict_interval(
         allow_infinite_bounds : bool, default=False
             If True, allows prediction intervals with infinite bounds.
 
-        symmetric_intervals : bool, default=True
-            If True, computes symmetric intervals around the predicted
-            median or mean.
+        symmetric_correction : bool, default=False
+            To produce prediction intervals, the conformalized quantile regression
+            technique corrects the predictions of the upper and lower quantile
+            regressors by adding a constant.
 
-            If False, calculates separate upper and lower bounds for
-            asymmetric intervals.
+            If `symmetric_correction` is set to `False` , this constant is different for
+            the upper and the lower quantile predictions. If set to True, this constant
+            is the same for both.
 
         Returns
         -------
@@ -1116,7 +1118,7 @@ def predict_interval(
             X,
             optimize_beta=minimize_interval_width,
             allow_infinite_bounds=allow_infinite_bounds,
-            symmetry=symmetric_intervals,
+            symmetry=symmetric_correction,
             **self._predict_params
         )
         return cast_predictions_to_ndarray_tuple(predictions)

tests_v1/integration_tests/tests/test_regression.py

@@ -357,6 +357,7 @@ def test_intervals_and_predictions_exact_equality_jackknife(
             "calib_size": 0.4,
             "sample_weight": sample_weight,
             "random_state": RANDOM_STATE,
+            "symmetry": False,
         },
         "v1": {
             "confidence_level": 0.8,
@@ -383,6 +384,7 @@ def test_intervals_and_predictions_exact_equality_jackknife(
             "test_size": 0.2,
             "fit_params": {"sample_weight": sample_weight},
             "minimize_interval_width": True,
+            "symmetric_correction": True,
         },
     },
     {
@@ -394,6 +396,7 @@ def test_intervals_and_predictions_exact_equality_jackknife(
             "calib_size": 0.3,
             "allow_infinite_bounds": True,
             "random_state": RANDOM_STATE,
+            "symmetry": False,
         },
         "v1": {
             "estimator": split_model,
@@ -410,13 +413,12 @@ def test_intervals_and_predictions_exact_equality_jackknife(
             "method": "quantile",
             "calib_size": 0.3,
             "random_state": RANDOM_STATE,
-            "symmetry": False
         },
         "v1": {
             "confidence_level": 0.9,
             "prefit": False,
             "test_size": 0.3,
-            "symmetric_intervals": False,
+            "symmetric_correction": True,
         },
     },
 ]