update documentation

Author: glemaitre

imblearn/over_sampling/_smote/base.py

@@ -224,10 +224,17 @@ class SMOTE(BaseSMOTE):
     {random_state}
 
     k_neighbors : int or object, default=5
-        If ``int``, number of nearest neighbours to used to construct synthetic
-        samples.  If object, an estimator that inherits from
-        :class:`~sklearn.neighbors.base.KNeighborsMixin` that will be used to
-        find the k_neighbors.
+        The nearest neighbors used to define the neighborhood of samples to use
+        to generate the synthetic samples. You can pass:
+
+        - an `int` corresponding to the number of neighbors to use. A
+          `~sklearn.neighbors.NearestNeighbors` instance will be fitted in this
+          case.
+        - an instance of a compatible nearest neighbors algorithm that should
+          implement both methods `kneighbors` and `kneighbors_graph`. For
+          instance, it could correspond to a
+          :class:`~sklearn.neighbors.NearestNeighbors` but could be extended to
+          any compatible class.
 
     {n_jobs}
 
@@ -367,10 +374,17 @@ class SMOTENC(SMOTE):
     {random_state}
 
     k_neighbors : int or object, default=5
-        If ``int``, number of nearest neighbours to used to construct synthetic
-        samples.  If object, an estimator that inherits from
-        :class:`~sklearn.neighbors.base.KNeighborsMixin` that will be used to
-        find the k_neighbors.
+        The nearest neighbors used to define the neighborhood of samples to use
+        to generate the synthetic samples. You can pass:
+
+        - an `int` corresponding to the number of neighbors to use. A
+          `~sklearn.neighbors.NearestNeighbors` instance will be fitted in this
+          case.
+        - an instance of a compatible nearest neighbors algorithm that should
+          implement both methods `kneighbors` and `kneighbors_graph`. For
+          instance, it could correspond to a
+          :class:`~sklearn.neighbors.NearestNeighbors` but could be extended to
+          any compatible class.
 
     {n_jobs}
 
@@ -636,10 +650,17 @@ class SMOTEN(SMOTE):
     {random_state}
 
     k_neighbors : int or object, default=5
-        If ``int``, number of nearest neighbours to used to construct synthetic
-        samples.  If object, an estimator that inherits from
-        :class:`~sklearn.neighbors.base.KNeighborsMixin` that will be used to
-        find the k_neighbors.
+        The nearest neighbors used to define the neighborhood of samples to use
+        to generate the synthetic samples. You can pass:
+
+        - an `int` corresponding to the number of neighbors to use. A
+          `~sklearn.neighbors.NearestNeighbors` instance will be fitted in this
+          case.
+        - an instance of a compatible nearest neighbors algorithm that should
+          implement both methods `kneighbors` and `kneighbors_graph`. For
+          instance, it could correspond to a
+          :class:`~sklearn.neighbors.NearestNeighbors` but could be extended to
+          any compatible class.
 
     {n_jobs}
 

imblearn/over_sampling/_smote/cluster.py

@@ -45,10 +45,17 @@ class KMeansSMOTE(BaseSMOTE):
     {random_state}
 
     k_neighbors : int or object, default=2
-        If ``int``, number of nearest neighbours to used to construct synthetic
-        samples.  If object, an estimator that inherits from
-        :class:`~sklearn.neighbors.base.KNeighborsMixin` that will be used to
-        find the k_neighbors.
+        The nearest neighbors used to define the neighborhood of samples to use
+        to generate the synthetic samples. You can pass:
+
+        - an `int` corresponding to the number of neighbors to use. A
+          `~sklearn.neighbors.NearestNeighbors` instance will be fitted in this
+          case.
+        - an instance of a compatible nearest neighbors algorithm that should
+          implement both methods `kneighbors` and `kneighbors_graph`. For
+          instance, it could correspond to a
+          :class:`~sklearn.neighbors.NearestNeighbors` but could be extended to
+          any compatible class.
 
     {n_jobs}
 

imblearn/over_sampling/_smote/filter.py

@@ -47,18 +47,32 @@ class BorderlineSMOTE(BaseSMOTE):
     {random_state}
 
     k_neighbors : int or object, default=5
-        If ``int``, number of nearest neighbours to used to construct synthetic
-        samples.  If object, an estimator that inherits from
-        :class:`~sklearn.neighbors.base.KNeighborsMixin` that will be used to
-        find the k_neighbors.
+        The nearest neighbors used to define the neighborhood of samples to use
+        to generate the synthetic samples. You can pass:
+
+        - an `int` corresponding to the number of neighbors to use. A
+          `~sklearn.neighbors.NearestNeighbors` instance will be fitted in this
+          case.
+        - an instance of a compatible nearest neighbors algorithm that should
+          implement both methods `kneighbors` and `kneighbors_graph`. For
+          instance, it could correspond to a
+          :class:`~sklearn.neighbors.NearestNeighbors` but could be extended to
+          any compatible class.
 
     {n_jobs}
 
     m_neighbors : int or object, default=10
-        If int, number of nearest neighbours to use to determine if a minority
-        sample is in danger. If object, an estimator that inherits
-        from :class:`~sklearn.neighbors.base.KNeighborsMixin` that will be used
-        to find the m_neighbors.
+        The nearest neighbors used to determine if a minority sample is in
+        "danger". You can pass:
+
+        - an `int` corresponding to the number of neighbors to use. A
+          `~sklearn.neighbors.NearestNeighbors` instance will be fitted in this
+          case.
+        - an instance of a compatible nearest neighbors algorithm that should
+          implement both methods `kneighbors` and `kneighbors_graph`. For
+          instance, it could correspond to a
+          :class:`~sklearn.neighbors.NearestNeighbors` but could be extended to
+          any compatible class.
 
     kind : {{"borderline-1", "borderline-2"}}, default='borderline-1'
         The type of SMOTE algorithm to use one of the following options:
@@ -261,18 +275,32 @@ class SVMSMOTE(BaseSMOTE):
     {random_state}
 
     k_neighbors : int or object, default=5
-        If ``int``, number of nearest neighbours to used to construct synthetic
-        samples.  If object, an estimator that inherits from
-        :class:`~sklearn.neighbors.base.KNeighborsMixin` that will be used to
-        find the k_neighbors.
+        The nearest neighbors used to define the neighborhood of samples to use
+        to generate the synthetic samples. You can pass:
+
+        - an `int` corresponding to the number of neighbors to use. A
+          `~sklearn.neighbors.NearestNeighbors` instance will be fitted in this
+          case.
+        - an instance of a compatible nearest neighbors algorithm that should
+          implement both methods `kneighbors` and `kneighbors_graph`. For
+          instance, it could correspond to a
+          :class:`~sklearn.neighbors.NearestNeighbors` but could be extended to
+          any compatible class.
 
     {n_jobs}
 
     m_neighbors : int or object, default=10
-        If int, number of nearest neighbours to use to determine if a minority
-        sample is in danger. If object, an estimator that inherits from
-        :class:`~sklearn.neighbors.base.KNeighborsMixin` that will be used to
-        find the m_neighbors.
+        The nearest neighbors used to determine if a minority sample is in
+        "danger". You can pass:
+
+        - an `int` corresponding to the number of neighbors to use. A
+          `~sklearn.neighbors.NearestNeighbors` instance will be fitted in this
+          case.
+        - an instance of a compatible nearest neighbors algorithm that should
+          implement both methods `kneighbors` and `kneighbors_graph`. For
+          instance, it could correspond to a
+          :class:`~sklearn.neighbors.NearestNeighbors` but could be extended to
+          any compatible class.
 
     svm_estimator : estimator object, default=SVC()
         A parametrized :class:`~sklearn.svm.SVC` classifier can be passed.

imblearn/under_sampling/_prototype_generation/tests/test_cluster_centroids.py

@@ -5,12 +5,12 @@
 import numpy as np
 from scipy import sparse
 
-from sklearn.base import BaseEstimator
 from sklearn.linear_model import LogisticRegression
 from sklearn.cluster import KMeans
 from sklearn.datasets import make_classification
 
 from imblearn.under_sampling import ClusterCentroids
+from imblearn.utils.testing import CustomClusterer
 
 RND_SEED = 0
 X = np.array(
@@ -155,16 +155,6 @@ def test_cluster_centroids_hard_target_class():
     assert sum(sample_from_minority_in_majority) == 0
 
 
-class FakeCluster(BaseEstimator):
-    """Class that mimics a cluster that does not expose `cluster_centers_`."""
-
-    def __init__(self, n_clusters=1):
-        self.n_clusters = n_clusters
-
-    def fit(self, X, y=None):
-        return self
-
-
 def test_cluster_centroids_error_estimator():
     """Check that an error is raised when estimator does not have a cluster API."""
 
@@ -180,4 +170,4 @@ def test_cluster_centroids_error_estimator():
         "`cluster_centers_`."
     )
     with pytest.raises(RuntimeError, match=err_msg):
-        ClusterCentroids(estimator=FakeCluster()).fit_resample(X, Y)
+        ClusterCentroids(estimator=CustomClusterer()).fit_resample(X, Y)

imblearn/utils/testing.py

@@ -195,3 +195,13 @@ def kneighbors_graph(X=None, n_neighbors=None, mode="connectivity"):
         """This method is not used within imblearn but it is required for
         duck-typing."""
         pass
+
+
+class CustomClusterer(BaseEstimator):
+    """Class that mimics a cluster that does not expose `cluster_centers_`."""
+
+    def __init__(self, n_clusters=1):
+        self.n_clusters = n_clusters
+
+    def fit(self, X, y=None):
+        return self