DOCS: Add MAPIE v1 docstrings to the DOC (#554)

* DOCS: Add MAPIE v1 regression docstrings to ReadTheDoc, fix warnings
scikit-learn-contrib · Dec 20, 2024 · f386fb4 · f386fb4
1 parent 7897690
commit f386fb4
Show file tree

Hide file tree

Showing 4 changed files with 97 additions and 78 deletions.
diff --git a/doc/api.rst b/doc/api.rst
@@ -2,18 +2,28 @@
 MAPIE API
 #########
 
-.. currentmodule:: mapie
+Regression V1 (from mapie_v1)
+=============================
 
-Regression
-==========
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+   mapie_v1.regression.SplitConformalRegressor
+   mapie_v1.regression.CrossConformalRegressor
+   mapie_v1.regression.JackknifeAfterBootstrapRegressor
+   mapie_v1.regression.ConformalizedQuantileRegressor
+
+Regression (from mapie)
+=======================
 
 .. autosummary::
    :toctree: generated/
    :template: class.rst
 
-   regression.MapieRegressor
-   regression.MapieQuantileRegressor
-   regression.MapieTimeSeriesRegressor
+   mapie.regression.MapieRegressor
+   mapie.regression.MapieQuantileRegressor
+   mapie.regression.MapieTimeSeriesRegressor
 
 Classification
 ==============
@@ -22,7 +32,7 @@ Classification
    :toctree: generated/
    :template: class.rst
 
-   classification.MapieClassifier
+   mapie.classification.MapieClassifier
 
 Multi-Label Classification
 ==========================
@@ -31,7 +41,7 @@ Multi-Label Classification
    :toctree: generated/
    :template: class.rst
 
-   multi_label_classification.MapieMultiLabelClassifier
+   mapie.multi_label_classification.MapieMultiLabelClassifier
 
 Calibration
 ===========
@@ -40,64 +50,64 @@ Calibration
    :toctree: generated/
    :template: class.rst
 
-   calibration.MapieCalibrator
+   mapie.calibration.MapieCalibrator
 
 Metrics
 =======
 
 .. autosummary::
    :toctree: generated/
    :template: function.rst
-   
-   metrics.classification_coverage_score
-   metrics.classification_coverage_score_v2
-   metrics.classification_mean_width_score
-   metrics.classification_ssc
-   metrics.classification_ssc_score
-   metrics.cumulative_differences
-   metrics.expected_calibration_error
-   metrics.hsic
-   metrics.kolmogorov_smirnov_cdf
-   metrics.kolmogorov_smirnov_p_value
-   metrics.kolmogorov_smirnov_statistic
-   metrics.kuiper_cdf
-   metrics.kuiper_p_value
-   metrics.kuiper_statistic
-   metrics.length_scale
-   metrics.regression_coverage_score
-   metrics.regression_coverage_score_v2
-   metrics.regression_mean_width_score
-   metrics.regression_ssc
-   metrics.regression_ssc_score
-   metrics.spiegelhalter_p_value
-   metrics.spiegelhalter_statistic
-   metrics.top_label_ece
-
-Conformity scores (regression)
+
+   mapie.metrics.classification_coverage_score
+   mapie.metrics.classification_coverage_score_v2
+   mapie.metrics.classification_mean_width_score
+   mapie.metrics.classification_ssc
+   mapie.metrics.classification_ssc_score
+   mapie.metrics.cumulative_differences
+   mapie.metrics.expected_calibration_error
+   mapie.metrics.hsic
+   mapie.metrics.kolmogorov_smirnov_cdf
+   mapie.metrics.kolmogorov_smirnov_p_value
+   mapie.metrics.kolmogorov_smirnov_statistic
+   mapie.metrics.kuiper_cdf
+   mapie.metrics.kuiper_p_value
+   mapie.metrics.kuiper_statistic
+   mapie.metrics.length_scale
+   mapie.metrics.regression_coverage_score
+   mapie.metrics.regression_coverage_score_v2
+   mapie.metrics.regression_mean_width_score
+   mapie.metrics.regression_ssc
+   mapie.metrics.regression_ssc_score
+   mapie.metrics.spiegelhalter_p_value
+   mapie.metrics.spiegelhalter_statistic
+   mapie.metrics.top_label_ece
+
+Conformity Scores (Regression)
 ==============================
 
 .. autosummary::
    :toctree: generated/
    :template: class.rst
 
-   conformity_scores.BaseRegressionScore
-   conformity_scores.AbsoluteConformityScore
-   conformity_scores.GammaConformityScore
-   conformity_scores.ResidualNormalisedScore
+   mapie.conformity_scores.BaseRegressionScore
+   mapie.conformity_scores.AbsoluteConformityScore
+   mapie.conformity_scores.GammaConformityScore
+   mapie.conformity_scores.ResidualNormalisedScore
 
-Conformity scores (classification)
+Conformity Scores (Classification)
 ==================================
 
 .. autosummary::
    :toctree: generated/
    :template: class.rst
 
-   conformity_scores.BaseClassificationScore
-   conformity_scores.NaiveConformityScore
-   conformity_scores.LACConformityScore
-   conformity_scores.APSConformityScore
-   conformity_scores.RAPSConformityScore
-   conformity_scores.TopKConformityScore
+   mapie.conformity_scores.BaseClassificationScore
+   mapie.conformity_scores.NaiveConformityScore
+   mapie.conformity_scores.LACConformityScore
+   mapie.conformity_scores.APSConformityScore
+   mapie.conformity_scores.RAPSConformityScore
+   mapie.conformity_scores.TopKConformityScore
 
 Resampling
 ==========
@@ -106,15 +116,14 @@ Resampling
    :toctree: generated/
    :template: class.rst
 
-   subsample.BlockBootstrap
-   subsample.Subsample
-
+   mapie.subsample.BlockBootstrap
+   mapie.subsample.Subsample
 
 Mondrian
-==========
+========
 
 .. autosummary::
    :toctree: generated/
    :template: class.rst
 
-   mondrian.MondrianCP
+   mapie.mondrian.MondrianCP
diff --git a/mapie_v1/__init__.py b/mapie_v1/__init__.py
@@ -0,0 +1,8 @@
+from . import classification, regression
+from ._version import __version__
+
+__all__ = [
+    "regression",
+    "classification",
+    "__version__"
+]
diff --git a/mapie_v1/_version.py b/mapie_v1/_version.py
@@ -0,0 +1 @@
+__version__ = "1.0.0"
diff --git a/mapie_v1/regression.py b/mapie_v1/regression.py
@@ -22,9 +22,10 @@
 class SplitConformalRegressor:
     """
     A conformal regression model using split conformal prediction to generate
-    prediction intervals with statistical guarantees. This method involves
-    using a hold-out conformity set to determine prediction intervals around
-    point predictions from a base regressor.
+    prediction intervals.
+
+    This method involves using a hold-out conformity set to determine
+    prediction intervals around point predictions from a base regressor.
 
     Parameters
     ----------
@@ -243,10 +244,11 @@ def predict(
 class CrossConformalRegressor:
     """
     A conformal regression model using cross-conformal prediction to generate
-    prediction intervals with statistical guarantees. This method involves
-    computing conformity scoring across multiple folds in a cross-validation
-    fashion to determine prediction intervals around point predictions from a
-    base regressor.
+    prediction intervals.
+
+    This method involves computing conformity scoring across multiple folds in
+    a cross-validation fashion to determine prediction intervals around point
+    predictions from a base regressor.
 
     Parameters
     ----------
@@ -272,20 +274,20 @@ class CrossConformalRegressor:
         The method used to compute prediction intervals. Options are:
         - "base": Based on the conformity scores from each fold.
         - "plus": Based on the conformity scores from each fold and
-          the test set predictions.
+        the test set predictions.
         - "minmax": Based on the conformity scores from each fold and
-          the test set predictions, using the minimum and maximum among
-          each fold models.
+        the test set predictions, using the minimum and maximum among
+        each fold models.
 
     cv : Union[int, BaseCrossValidator], default=5
         The cross-validation strategy used to compute confomity scores.
         Valid options:
         - integer, to specify the number of folds
         - any ``sklearn.model_selection.BaseCrossValidator`` suitable for
-          regression, or a custom cross-validator inheriting from it.
-          Main variants in the cross conformal setting are:
-          - ``sklearn.model_selection.KFold`` (vanilla cross conformal)
-          - ``sklearn.model_selection.LeaveOneOut`` (jackknife)
+        regression, or a custom cross-validator inheriting from it.
+        Main variants in the cross conformal setting are:
+        * ``sklearn.model_selection.KFold`` (vanilla cross conformal)
+        * ``sklearn.model_selection.LeaveOneOut`` (jackknife)
 
     n_jobs : Optional[int], default=None
         The number of jobs to run in parallel when applicable.
@@ -304,7 +306,7 @@ class CrossConformalRegressor:
         An array containing the prediction intervals with shape:
         - `(n_samples, 2)` if `confidence_level` is a single float
         - `(n_samples, 2, n_confidence_levels)` if `confidence_level`
-           is a list of floats.
+        is a list of floats.
 
     Examples
     --------
@@ -492,7 +494,7 @@ def predict(
         Generates point predictions for the input data `X`:
         - using the model fitted on the entire dataset
         - or if aggregation_method is provided, aggregating predictions from
-          the models fitted on each fold
+        the models fitted on each fold
 
         Parameters
         ----------
@@ -524,9 +526,11 @@ def predict(
 class JackknifeAfterBootstrapRegressor:
     """
     A conformal regression model using the jackknife-after-bootstrap approach
-    to generate prediction intervals with statistical guarantees. This method
-    combines bootstrap sampling with the jackknife technique to produce robust
-    prediction intervals around point predictions from a base regressor.
+    to generate prediction intervals.
+
+    This method combines bootstrap sampling with the jackknife technique
+    to produce robust prediction intervals around point predictions from
+    a base regressor.
 
     Parameters
     ----------
@@ -553,9 +557,9 @@ class JackknifeAfterBootstrapRegressor:
         The method used for jackknife-after-bootstrap prediction. Options are:
         - "base": Based on the conformity scores from each bootstrap sample.
         - "plus": Based on the conformity scores from each bootstrap sample and
-           the testing prediction.
+        the testing prediction.
         - "minmax": Based on the minimum and maximum conformity scores from
-          each bootstrap sample.
+        each bootstrap sample.
 
     n_bootstraps : int, default=100
         The number of bootstrap resamples to generate for the
@@ -718,8 +722,9 @@ def predict(
 class ConformalizedQuantileRegressor:
     """
     A conformal quantile regression model that generates prediction intervals
-    with statistical guarantees using quantile regression as the base
-    estimator. This approach provides prediction intervals by leveraging
+    using quantile regression as the base estimator.
+
+    This approach provides prediction intervals by leveraging
     quantile predictions and applying conformal adjustments to ensure coverage.
 
     Parameters
@@ -790,10 +795,6 @@ def __init__(
         estimator: RegressorMixin = QuantileRegressor(),
         confidence_level: Union[float, List[float]] = 0.9,
         conformity_score: Union[str, BaseRegressionScore] = "absolute",
-        # n_jobs: Optional[int] = None
-        # Not yet available in MapieQuantileRegressor
-        # verbose: int = 0,
-        # Idem
         random_state: Optional[Union[int, np.random.RandomState]] = None,
     ) -> None:
         pass