docs: update the docstring for the conformity score methods to align with the typing. (#808)

* update the docstring of sets and BaseClassificationScore : get_predictions, get_conformity_score_quantiles, get_prediction_sets 

* remove not used args

Author: hmaissoro

mapie/conformity_scores/classification.py

@@ -2,11 +2,10 @@
 from typing import Optional, Union
 
 import numpy as np
-
-from mapie.conformity_scores.interface import BaseConformityScore
+from numpy.typing import ArrayLike, NDArray
 from sklearn.model_selection import BaseCrossValidator
 
-from numpy.typing import ArrayLike, NDArray
+from mapie.conformity_scores.interface import BaseConformityScore
 
 
 class BaseClassificationScore(BaseConformityScore, metaclass=ABCMeta):
@@ -17,6 +16,12 @@ class BaseClassificationScore(BaseConformityScore, metaclass=ABCMeta):
 
     Attributes
     ----------
+    classes: Optional[ArrayLike]
+        Names of the classes.
+
+    random_state: Optional[Union[int, np.random.RandomState]]
+        Pseudo random number generator state.
+
     quantiles_: ArrayLike of shape (n_alpha)
         The quantiles estimated from ``get_sets`` method.
     """
@@ -41,7 +46,7 @@ def set_external_attributes(
 
             By default ``None``.
 
-        random_state: Optional[Union[int, RandomState]]
+        random_state: Optional[Union[int, np.random.RandomState]]
             Pseudo random number generator state.
         """
         super().set_external_attributes(**kwargs)
@@ -71,8 +76,11 @@ def get_predictions(
             NDArray of floats between ``0`` and ``1``, represents the
             uncertainty of the confidence set.
 
-        estimator: EnsembleClassifier
-            Estimator that is fitted to predict y from X.
+        y_pred_proba: NDArray
+            Predicted probabilities from the estimator.
+
+        cv: Optional[Union[int, str, BaseCrossValidator]]
+            Cross-validation strategy used by the estimator.
 
         Returns
         --------
@@ -102,8 +110,8 @@ def get_conformity_score_quantiles(
             NDArray of floats between 0 and 1, representing the uncertainty
             of the confidence set.
 
-        estimator: EnsembleClassifier
-            Estimator that is fitted to predict y from X.
+        cv: Optional[Union[int, str, BaseCrossValidator]]
+            Cross-validation strategy used by the estimator.
 
         Returns
         --------
@@ -138,8 +146,8 @@ def get_prediction_sets(
             NDArray of floats between 0 and 1, representing the uncertainty
             of the confidence set.
 
-        estimator: EnsembleClassifier
-            Estimator that is fitted to predict y from X.
+        cv: Optional[Union[int, str, BaseCrossValidator]]
+            Cross-validation strategy used by the estimator.
 
         Returns
         --------
@@ -211,12 +219,6 @@ def predict_set(self, X: NDArray, alpha_np: NDArray, **kwargs):
         alpha_np: NDArray of shape (n_alpha, )
             Represents the uncertainty of the confidence set to produce.
 
-        y_pred_proba: NDArray
-            Predicted probabilities from the estimator.
-
-        cv: Optional[Union[int, str, BaseCrossValidator]]
-            Cross-validation strategy used by the estimator.
-
         **kwargs: dict
             Additional keyword arguments.
 

mapie/conformity_scores/sets/aps.py

@@ -1,15 +1,14 @@
 from typing import Optional, Tuple, Union, cast
 
 import numpy as np
-from sklearn.utils import check_random_state
-from sklearn.preprocessing import label_binarize
+from numpy.typing import ArrayLike, NDArray
 from sklearn.model_selection import BaseCrossValidator
+from sklearn.preprocessing import label_binarize
+from sklearn.utils import check_random_state
 
+from mapie._machine_precision import EPSILON
 from mapie.conformity_scores.sets.naive import NaiveConformityScore
 from mapie.conformity_scores.sets.utils import check_include_last_label
-
-from mapie._machine_precision import EPSILON
-from numpy.typing import ArrayLike, NDArray
 from mapie.utils import _compute_quantiles
 
 
@@ -30,7 +29,7 @@ class APSConformityScore(NaiveConformityScore):
     classes: Optional[ArrayLike]
         Names of the classes.
 
-    random_state: Optional[Union[int, RandomState]]
+    random_state: Optional[Union[int, np.random.RandomState]]
         Pseudo random number generator state.
 
     quantiles_: ArrayLike of shape (n_alpha)
@@ -65,7 +64,7 @@ def get_predictions(
             Predicted probabilities from the estimator.
 
         cv: Optional[Union[int, str, BaseCrossValidator]]
-            Cross-validation strategy used by the estimator.
+            Cross-validation strategy used by the estimator (not used here).
 
         agg_scores: Optional[str]
             Method to aggregate the scores from the base estimators.
@@ -94,20 +93,20 @@ def get_true_label_cumsum_proba(
 
         Parameters
         ----------
-        y: NDArray of shape (n_samples, )
+        y: ArrayLike of shape (n_samples, )
             Array with the labels.
 
         y_pred_proba: NDArray of shape (n_samples, n_classes)
             Predictions of the model.
 
-        classes: NDArray of shape (n_classes, )
+        classes: ArrayLike of shape (n_classes, )
             Array with the classes.
 
         Returns
         -------
         Tuple[NDArray, NDArray] of shapes (n_samples, 1) and (n_samples, ).
             The first element is the cumsum probability of the true label.
-            The second is the sorted position of the true label.
+            The second is the 1-based rank of the true label in the sorted probabilities.
         """
         y_true = label_binarize(y=y, classes=classes)
         index_sorted = np.fliplr(np.argsort(y_pred_proba, axis=1))
@@ -136,7 +135,7 @@ def get_conformity_scores(
         y_pred: NDArray of shape (n_samples,)
             Predicted target values.
 
-        y_enc: NDArray of shape (n_samples,)
+        y_enc: Optional[NDArray] of shape (n_samples,)
             Target values as normalized encodings.
 
         Returns
@@ -225,8 +224,8 @@ def _compute_v_parameter(
         y_pred_proba_last: NDArray of shape (n_samples, 1, n_alpha)
             Last included probability.
 
-        predicition_sets: NDArray of shape (n_samples, n_alpha)
-            Prediction sets.
+        prediction_sets: NDArray of shape (n_samples, n_alpha)
+            Prediction sets (not used here).
 
         Returns
         --------
@@ -328,7 +327,7 @@ def get_prediction_sets(
 
         alpha_np: NDArray of shape (n_alpha,)
             NDArray of floats between 0 and 1, representing the uncertainty
-            of the confidence interval.
+            of the confidence interval (not used here).
 
         cv: Optional[Union[int, str, BaseCrossValidator]]
             Cross-validation strategy used by the estimator.

mapie/conformity_scores/sets/lac.py

@@ -29,7 +29,7 @@ class LACConformityScore(BaseClassificationScore):
     classes: Optional[ArrayLike]
         Names of the classes.
 
-    random_state: Optional[Union[int, RandomState]]
+    random_state: Optional[Union[int, np.random.RandomState]]
         Pseudo random number generator state.
 
     quantiles_: ArrayLike of shape (n_alpha)
@@ -48,7 +48,7 @@ def get_conformity_scores(
         Parameters
         ----------
         y: NDArray of shape (n_samples,)
-            Observed target values.
+            Observed target values (not used here).
 
         y_pred: NDArray of shape (n_samples,)
             Predicted target values.
@@ -94,7 +94,7 @@ def get_predictions(
             Predicted probabilities from the estimator.
 
         cv: Optional[Union[int, str, BaseCrossValidator]]
-            Cross-validation strategy used by the estimator.
+            Cross-validation strategy used by the estimator (not used here).
 
         agg_scores: Optional[str]
             Method to aggregate the scores from the base estimators.

mapie/conformity_scores/sets/naive.py

@@ -1,13 +1,12 @@
-from typing import Tuple, Union, Optional
+from typing import Optional, Tuple, Union
 
 import numpy as np
-
-from mapie.conformity_scores.classification import BaseClassificationScore
-from mapie.conformity_scores.sets.utils import get_last_index_included
+from numpy.typing import NDArray
 from sklearn.model_selection import BaseCrossValidator
 
 from mapie._machine_precision import EPSILON
-from numpy.typing import NDArray
+from mapie.conformity_scores.classification import BaseClassificationScore
+from mapie.conformity_scores.sets.utils import get_last_index_included
 
 
 class NaiveConformityScore(BaseClassificationScore):
@@ -20,10 +19,10 @@ class NaiveConformityScore(BaseClassificationScore):
     classes: Optional[ArrayLike]
         Names of the classes.
 
-    random_state: Optional[Union[int, RandomState]]
+    random_state: Optional[Union[int, np.random.RandomState]]
         Pseudo random number generator state.
 
-    quantiles_: ArrayLike of shape (n_alpha)
+    quantiles_: ArrayLike of shape (n_alpha,)
         The quantiles estimated from ``get_sets`` method.
     """
 
@@ -37,7 +36,7 @@ def get_conformity_scores(self, y: NDArray, y_pred: NDArray, **kwargs) -> NDArra
         Parameters
         ----------
         y: NDArray of shape (n_samples,)
-            Observed target values.
+            Observed target values (not used here).
 
         y_pred: NDArray of shape (n_samples,)
             Predicted target values.
@@ -97,11 +96,11 @@ def get_conformity_score_quantiles(
         Parameters
         -----------
         conformity_scores: NDArray of shape (n_samples,)
-            Conformity scores for each sample.
+            Conformity scores for each sample (not used here).
 
         alpha_np: NDArray of shape (n_alpha,)
             NDArray of floats between 0 and 1, representing the uncertainty
-            of the confidence interval.
+            of the confidence interval (not used here).
 
         cv: Optional[Union[int, str, BaseCrossValidator]]
             Cross-validation strategy used by the estimator (not used here).
@@ -222,11 +221,11 @@ def get_prediction_sets(
             Target prediction.
 
         conformity_scores: NDArray of shape (n_samples,)
-            Conformity scores for each sample.
+            Conformity scores for each sample (not used here).
 
         alpha_np: NDArray of shape (n_alpha,)
             NDArray of floats between 0 and 1, representing the uncertainty
-            of the confidence interval.
+            of the confidence interval (not used here).
 
         cv: Optional[Union[int, str, BaseCrossValidator]]
             Cross-validation strategy used by the estimator (not used here).