DOC: Migrate every regression examples and notebooks to v1. (#624)

* Migrate homoscedastic, heteroscedastic and gamma examples

* Migrate plot_coverage_validity.py

* Migrate plot_barber2020_simulations.py

* Migrate plot_kim2020_simulations.py

* Migrate plot_conformal_predictive_distribution.py

* Migrate plot_cqr_symmetry_difference.py

* Migrate plot_nested-cv.py to v1

* Migrate plot_both_uncertainties.py to v1

* Migrate plot-coverage-width-based-criterion.py to v1

* Migrate plot_conditional_coverage.py to v1

* Migrate plot_ResidualNormalisedScore_tutorial.py to v1

* Migrate plot_cqr_tutorial.py to v1

* Migrate two exoplanets.ipynb and tutorial_regression.ipynb to v1

* Few edits from code review

* Delete mentions to 'pre-v1'

* Fix lint

* Migrate plot_main-tutorial-regression.py to v1

* Change titles and arborescence of regression examples

* Delete optimize_beta parameter from examples as it does not work.

* Restore subtitles on plot_prefit. The gestion of the subtitles is on another ticket.

* Make lint

* Fix typo and links

* Fix bullet point lists.

* Delete v1 mention on the regression examples README.rst

---------

Co-authored-by: Valentin Laurent <[email protected]>

Author: C-BdB

doc/choosing_the_right_algorithm_regression.rst

@@ -1,5 +1,5 @@
 ############################################
-Choosing the right algorithm
+Choose the right algorithm
 ############################################
 
 Following is a simple decision tree to help you you getting started quickly with MAPIE.

doc/index_regression.rst

@@ -6,6 +6,7 @@ Prediction intervals (regression)
 
    choosing_the_right_algorithm_regression
    examples_regression/1-quickstart/plot_toy_model
+   examples_regression/1-quickstart/plot_prefit
    examples_regression/index
    theoretical_description_regression
    theoretical_description_conformity_scores

examples/regression/1-quickstart/README.rst

@@ -1,6 +1,6 @@
 .. _regression_examples_1:
 
-1. Quickstart examples
+1. Quickstart
 ----------------------
 
 The following examples present the main functionalities of MAPIE through basic quickstart regression problems.

examples/regression/1-quickstart/plot_compare_conformity_scores.py

@@ -1,11 +1,10 @@
 """
 ==========================================================================================
-[Pre-v1] Estimating prediction intervals of Gamma distributed target
+Use MAPIE on data with gamma distribution
 ==========================================================================================
-**Note: we recently released MAPIE v1.0.0, which introduces breaking API changes.**
-**This notebook hasn't been updated to the new API yet.**
 
-This example uses :class:`~mapie.regression.MapieRegressor` to estimate
+
+This example uses :class:`~mapie_v1.regression.CrossConformalRegressor` to estimate
 prediction intervals associated with Gamma distributed target.
 The limit of the absolute residual conformity score is illustrated.
 
@@ -17,10 +16,10 @@
 The data is modelled by a Random Forest model
 :class:`~sklearn.ensemble.RandomForestRegressor` with a fixed parameter set.
 The prediction intervals are determined by means of the MAPIE regressor
-:class:`~mapie.regression.MapieRegressor` considering two conformity scores:
-:class:`~mapie.conformity_scores.AbsoluteConformityScore` which
+:class:`~mapie_v1.regression.CrossConformalRegressor` considering two conformity scores:
+``"absolute"`` which
 considers the absolute residuals as the conformity scores and
-:class:`~mapie.conformity_scores.GammaConformityScore` which
+``"gamma"`` which
 considers the residuals divided by the predicted means as conformity scores.
 We consider the standard CV+ resampling method.
 
@@ -31,7 +30,7 @@
 overcomes this issue by considering prediction intervals with width
 proportional to the predicted mean. For low prices, the Gamma prediction
 intervals are narrower than the default ones, conversely to high prices
-for which the conficence intervals are higher but visually more relevant.
+for which the confidence intervals are higher but visually more relevant.
 The empirical coverage is similar between the two conformity scores.
 """
 import matplotlib.pyplot as plt
@@ -43,11 +42,10 @@
 from sklearn.ensemble import RandomForestRegressor
 from sklearn.model_selection import train_test_split
 
-from mapie.conformity_scores import GammaConformityScore
 from mapie.metrics import regression_coverage_score
-from mapie.regression import MapieRegressor
+from mapie_v1.regression import CrossConformalRegressor
 
-random_state = 42
+RANDOM_STATE = 42
 
 # Parameters
 features = [
@@ -59,8 +57,8 @@
 ]
 target = "SalePrice"
 
-alpha = 0.05
-rf_kwargs = {"n_estimators": 10, "random_state": random_state}
+confidence_level = 0.95
+rf_kwargs = {"n_estimators": 10, "random_state": RANDOM_STATE}
 model = RandomForestRegressor(**rf_kwargs)
 
 ##############################################################################
@@ -69,8 +67,6 @@
 #
 # We start by loading a dataset with a target following approximately
 # a Gamma distribution.
-# The :class:`~mapie.conformity_scores.GammaConformityScore`` is relevant
-# in such cases.
 # Two sub datasets are extracted: the training and test ones.
 
 dataset_url = (
@@ -85,8 +81,8 @@
 X = data[features]
 y = data[target]
 
-X_train, X_test, y_train, y_test = train_test_split(
-    X[features], y, test_size=0.2, random_state=random_state
+X_train_conformalize, X_test, y_train_conformalize, y_test = train_test_split(
+    X[features], y, test_size=0.2, random_state=RANDOM_STATE
 )
 
 ##############################################################################
@@ -95,22 +91,24 @@
 #
 # Two models are trained with two different conformity score:
 #
-# - :class:`~mapie.conformity_scores.AbsoluteConformityScore` (default
-#   conformity score) relevant for target positive as well as negative.
+# - ``conformity_score = "absolute"`` (default
+#   conformity score) is relevant for target positive as well as negative.
 #   The prediction interval widths are, in this case, approximately the same
 #   over the range of prediction.
 #
-# - :class:`~mapie.conformity_scores.GammaConformityScore` relevant for target
+# - ``conformity_score = "gamma"`` is relevant for target
 #   following roughly a Gamma distribution. The prediction interval widths
 #   scale with the predicted value.
 
 ##############################################################################
 # First, train model with
-# :class:`~mapie.conformity_scores.AbsoluteConformityScore`.
-mapie = MapieRegressor(model, random_state=random_state)
-mapie.fit(X_train, y_train)
-y_pred_absconfscore, y_pis_absconfscore = mapie.predict(
-    X_test, alpha=alpha, ensemble=True
+# conformity_score = "absolute".
+mapie = CrossConformalRegressor(
+    model, confidence_level=confidence_level, conformity_score="absolute"
+)
+mapie.fit_conformalize(X_train_conformalize, y_train_conformalize)
+y_pred_absconfscore, y_pis_absconfscore = mapie.predict_interval(
+    X_test
 )
 
 coverage_absconfscore = regression_coverage_score(
@@ -138,14 +136,14 @@ def get_yerr(y_pred, y_pis):
 )
 
 ##############################################################################
-# Then, train the model with
-# :class:`~mapie.conformity_scores.GammaConformityScore`.
-mapie = MapieRegressor(
-    model, conformity_score=GammaConformityScore(), random_state=random_state
+# Then, train the model with:
+# `conformity_score = "gamma"`.
+mapie = CrossConformalRegressor(
+    model, confidence_level=confidence_level, conformity_score="gamma"
 )
-mapie.fit(X_train, y_train)
-y_pred_gammaconfscore, y_pis_gammaconfscore = mapie.predict(
-    X_test, alpha=[alpha], ensemble=True
+mapie.fit_conformalize(X_train_conformalize, y_train_conformalize)
+y_pred_gammaconfscore, y_pis_gammaconfscore = mapie.predict_interval(
+    X_test
 )
 
 coverage_gammaconfscore = regression_coverage_score(
@@ -164,9 +162,9 @@ def get_yerr(y_pred, y_pis):
 #
 # Once the models have been trained, we now compare the prediction intervals
 # obtained from the two conformity scores. We can see that the
-# :class:`~mapie.conformity_scores.AbsoluteConformityScore` generates
+# ``"absolute" ``conformity score generates
 # prediction interval with almost the same width for all the predicted values.
-# Conversely, the `mapie.conformity_scores.GammaConformityScore`
+# Conversely, the ``"gamma"`` conformity score
 # yields prediction interval with width scaling with the predicted values.
 #
 # The choice of the conformity score depends on the problem we face.
@@ -209,7 +207,7 @@ def get_yerr(y_pred, y_pis):
     axs[1, img_id].set_ylim([ymin, ymax])
 
 fig.suptitle(
-    f"Predicted values with the prediction intervals of level {alpha}"
+    f"Predicted values with the prediction intervals of level {confidence_level}"
 )
 plt.subplots_adjust(wspace=0.3, hspace=0.3)
 plt.show()