[MRG+1] Rename all occurrences of size_ngh to n_neighbors for consistency with scikit-learn (#109)

* Rename all occurrences of size_ngh to n_neighbors for consistency with scikit-learn. * Implement deprecation for smote_enn and enn * Add the changes in documentation * Make the changes in the base function * Minor comment fixes

Author: chkoar

doc/whats_new.rst

@@ -14,7 +14,6 @@ Changelog
 
 Bug fixes
 ~~~~~~~~~
-
 - Fixed a bug in :class:`under_sampling.NearMiss` which was not picking the right samples during under sampling for the method 3. By `Guillaume Lemaitre`_.
 - Fixed a bug in :class:`ensemble.EasyEnsemble`, correction of the `random_state` generation. By `Guillaume Lemaitre`_ and `Christos Aridas`_.
 - Fixed a bug in :class:`under_sampling.RepeatedEditedNearestNeighbours`, add additional stopping criterion to avoid that the minority class become a majority class or that a class disappear. By `Guillaume Lemaitre`_.
@@ -38,6 +37,18 @@ Enhancement
 - Added support for bumpversion. By `Guillaume Lemaitre`_.
 - Validate the type of target in binary samplers. A warning is raised for the moment. By `Guillaume Lemaitre`_ and `Christos Aridas`_.
 
+New features
+~~~~~~~~~~~~
+
+- Added AllKNN under sampling technique.
+- Added support for bumpversion.
+
+API changes summary
+~~~~~~~~~~~~~~~~~~~
+
+- `size_ngh` has been deprecated in :class:`combine.SMOTEENN`. Use `n_neighbors` instead. By `Guillaume Lemaitre`_, `Christos Aridas`_, and `Dayvid Oliveira` .
+- `size_ngh` has been deprecated in :class:`under_sampling.EditedNearestNeighbors`. Use `n_neighbors` instead. By `Guillaume Lemaitre`_, `Christos Aridas`_, and `Dayvid Oliveira`_.
+
 Documentation changes
 ~~~~~~~~~~~~~~~~~~~~~
 

examples/plot_unbalanced_dataset.ipynb

@@ -215,25 +215,25 @@
  "NM3 = NearMiss(version=3)\n",
  "nm3x, nm3y = NM3.fit_sample(x, y)\n",
  "# 'Condensed Nearest Neighbour'\n",
- "CNN = CondensedNearestNeighbour(size_ngh=51, n_seeds_S=51)\n",
+ "CNN = CondensedNearestNeighbour(n_neighbors=51, n_seeds_S=51)\n",
  "cnnx, cnny = CNN.fit_sample(x, y)\n",
  "# 'One-Sided Selection'\n",
- "OSS = OneSidedSelection(size_ngh=51, n_seeds_S=51)\n",
+ "OSS = OneSidedSelection(n_neighbors=51, n_seeds_S=51)\n",
  "ossx, ossy = OSS.fit_sample(x, y)\n",
  "# 'Neighboorhood Cleaning Rule'\n",
- "NCR = NeighbourhoodCleaningRule(size_ngh=51)\n",
+ "NCR = NeighbourhoodCleaningRule(n_neighbors=51)\n",
  "ncrx, ncry = NCR.fit_sample(x, y) \n",
  "# 'Edited Neareast Neighbour'\n",
- "ENN = EditedNearestNeighbours(size_ngh=51)\n",
+ "ENN = EditedNearestNeighbours(n_neighbors=51)\n",
  "ennx, enny = ENN.fit_sample(x, y)\n",
  "# 'Instance Hardness Threshold'\n",
  "IHT = InstanceHardnessThreshold()\n",
  "ihtx, ihty = IHT.fit_sample(x, y)\n",
  "# 'Repeated Edited Nearest Neighbour'\n",
- "RENN = RepeatedEditedNearestNeighbours(size_ngh=51)\n",
+ "RENN = RepeatedEditedNearestNeighbours(n_neighbors=51)\n",
  "rennx, renny = RENN.fit_sample(x, y)\n",
  "# 'AllKNN'\n",
- "ALLK = AllKNN(size_ngh=51)\n",
+ "ALLK = AllKNN(n_neighbors=51)\n",
  "allkx, allky = ALLK.fit_sample(x, y)\n",
  "\n",
  "# Apply PCA to be able to visualise the results\n",

imblearn/base.py

@@ -74,9 +74,12 @@ def fit(self, X, y):
  if hasattr(self, 'ratio'):
  self._validate_ratio()
 
+ if hasattr(self, 'size_ngh'):
+ self._validate_size_ngh_deprecation()
+
  self.logger.info('Compute classes statistics ...')
 
- # # Raise an error if there is only one class
+ # Raise an error if there is only one class
  # if uniques.size == 1:
  # raise RuntimeError("Only one class detected, aborting...")
  # Raise a warning for the moment to be compatible with BaseEstimator
@@ -149,6 +152,9 @@ def sample(self, X, y):
  if hasattr(self, 'ratio'):
  self._validate_ratio()
 
+ if hasattr(self, 'size_ngh'):
+ self._validate_size_ngh_deprecation()
+
  return self._sample(X, y)
 
  def fit_sample(self, X, y):
@@ -190,6 +196,15 @@ def _validate_ratio(self):
  else:
  raise ValueError('Unknown parameter type for ratio.')
 
+ def _validate_size_ngh_deprecation(self):
+ "Private function to warn about the deprecation about size_ngh."
+
+ # Announce deprecation if necessary
+ if self.size_ngh is not None:
+ warnings.warn('`size_ngh` will be replaced in version 0.4. Use'
+ ' `n_neighbors` instead.', DeprecationWarning)
+ self.n_neighbors = self.size_ngh
+
  @abstractmethod
  def _sample(self, X, y):
  """Resample the dataset.

imblearn/combine/smote_enn.py

@@ -1,6 +1,8 @@
 """Class to perform over-sampling using SMOTE and cleaning using ENN."""
 from __future__ import division, print_function
 
+import warnings
+
 from ..base import BaseBinarySampler
 from ..over_sampling import SMOTE
 from ..under_sampling import EditedNearestNeighbours
@@ -40,7 +42,14 @@ class SMOTEENN(BaseBinarySampler):
  The type of SMOTE algorithm to use one of the following
  options: 'regular', 'borderline1', 'borderline2', 'svm'.
 
- size_ngh : int, optional (default=3)
+ size_ngh : int, optional (default=None)
+ Size of the neighbourhood to consider to compute the average
+ distance to the minority point samples.
+
+ NOTE: size_ngh is deprecated from 0.2 and will be replaced in 0.4
+ Use ``n_neighbors`` instead.
+
+ n_neighbors : int, optional (default=3)
  Size of the neighbourhood to consider to compute the average
  distance to the minority point samples.
 
@@ -103,7 +112,8 @@ class SMOTEENN(BaseBinarySampler):
 
  def __init__(self, ratio='auto', random_state=None,
  k=5, m=10, out_step=0.5, kind_smote='regular',
- size_ngh=3, kind_enn='all', n_jobs=-1, **kwargs):
+ size_ngh=None, n_neighbors=3, kind_enn='all', n_jobs=-1,
+ **kwargs):
 
  super(SMOTEENN, self).__init__(ratio=ratio)
  self.random_state = random_state
@@ -112,6 +122,7 @@ def __init__(self, ratio='auto', random_state=None,
  self.out_step = out_step
  self.kind_smote = kind_smote
  self.size_ngh = size_ngh
+ self.n_neighbors = n_neighbors
  self.kind_enn = kind_enn
  self.n_jobs = n_jobs
  self.kwargs = kwargs
@@ -121,6 +132,7 @@ def __init__(self, ratio='auto', random_state=None,
  **self.kwargs)
  self.enn = EditedNearestNeighbours(random_state=self.random_state,
  size_ngh=self.size_ngh,
+ n_neighbors=self.n_neighbors,
  kind_sel=self.kind_enn,
  n_jobs=self.n_jobs)
 
@@ -144,6 +156,12 @@ def fit(self, X, y):
 
  super(SMOTEENN, self).fit(X, y)
 
+ # Annonce deprecation if necessary
+ if self.size_ngh is not None:
+ warnings.warn('`size_ngh` will be replaced in version 0.4. Use'
+ ' `n_neighbors` instead.', DeprecationWarning)
+ self.n_neighbors = self.size_ngh
+
  # Fit using SMOTE
  self.sm.fit(X, y)
 

imblearn/combine/smote_tomek.py

@@ -42,10 +42,6 @@ class SMOTETomek(BaseBinarySampler):
  The type of SMOTE algorithm to use one of the following
  options: 'regular', 'borderline1', 'borderline2', 'svm'
 
- size_ngh : int, optional (default=3)
- Size of the neighbourhood to consider to compute the average
- distance to the minority point samples.
-
  kind_sel : str, optional (default='all')
  Strategy to use in order to exclude samples.
 

imblearn/under_sampling/condensed_nearest_neighbour.py

@@ -2,6 +2,8 @@
 method."""
 from __future__ import division, print_function
 
+import warnings
+
 from collections import Counter
 
 import numpy as np
@@ -27,7 +29,14 @@ class CondensedNearestNeighbour(BaseMulticlassSampler):
  If None, the random number generator is the RandomState instance used
  by np.random.
 
- size_ngh : int, optional (default=1)
+ size_ngh : int, optional (default=None)
+ Size of the neighbourhood to consider to compute the average
+ distance to the minority point samples.
+
+ NOTE: size_ngh is deprecated from 0.2 and will be replaced in 0.4
+ Use ``n_neighbors`` instead.
+
+ n_neighbors : int, optional (default=1)
  Size of the neighbourhood to consider to compute the average
  distance to the minority point samples.
 
@@ -86,12 +95,14 @@ class CondensedNearestNeighbour(BaseMulticlassSampler):
  """
 
  def __init__(self, return_indices=False, random_state=None,
- size_ngh=1, n_seeds_S=1, n_jobs=-1, **kwargs):
+ size_ngh=None, n_neighbors=1, n_seeds_S=1, n_jobs=-1,
+ **kwargs):
  super(CondensedNearestNeighbour, self).__init__()
 
  self.return_indices = return_indices
  self.random_state = random_state
  self.size_ngh = size_ngh
+ self.n_neighbors = n_neighbors
  self.n_seeds_S = n_seeds_S
  self.n_jobs = n_jobs
  self.kwargs = kwargs
@@ -158,7 +169,7 @@ def _sample(self, X, y):
  S_y = y[y == key]
 
  # Create a k-NN classifier
- knn = KNeighborsClassifier(n_neighbors=self.size_ngh,
+ knn = KNeighborsClassifier(n_neighbors=self.n_neighbors,
  n_jobs=self.n_jobs,
  **self.kwargs)
 

imblearn/under_sampling/edited_nearest_neighbours.py

@@ -4,6 +4,7 @@
 
 from collections import Counter
 
+import warnings
 import numpy as np
 from scipy.stats import mode
 from sklearn.neighbors import NearestNeighbors
@@ -29,7 +30,14 @@ class EditedNearestNeighbours(BaseMulticlassSampler):
  If None, the random number generator is the RandomState instance used
  by np.random.
 
- size_ngh : int, optional (default=3)
+ size_ngh : int, optional (default=None)
+ Size of the neighbourhood to consider to compute the average
+ distance to the minority point samples.
+
+ NOTE: size_ngh is deprecated from 0.2 and will be replaced in 0.4
+ Use ``n_neighbors`` instead.
+
+ n_neighbors : int, optional (default=3)
  Size of the neighbourhood to consider to compute the average
  distance to the minority point samples.
 
@@ -91,11 +99,12 @@ class EditedNearestNeighbours(BaseMulticlassSampler):
  """
 
  def __init__(self, return_indices=False, random_state=None,
- size_ngh=3, kind_sel='all', n_jobs=-1):
+ size_ngh=None, n_neighbors=3, kind_sel='all', n_jobs=-1):
  super(EditedNearestNeighbours, self).__init__()
  self.return_indices = return_indices
  self.random_state = random_state
  self.size_ngh = size_ngh
+ self.n_neighbors = n_neighbors
  self.kind_sel = kind_sel
  self.n_jobs = n_jobs
 
@@ -140,7 +149,7 @@ def _sample(self, X, y):
  idx_under = np.flatnonzero(y == self.min_c_)
 
  # Create a k-NN to fit the whole data
- nn_obj = NearestNeighbors(n_neighbors=self.size_ngh + 1,
+ nn_obj = NearestNeighbors(n_neighbors=self.n_neighbors + 1,
  n_jobs=self.n_jobs)
  # Fit the data
  nn_obj.fit(X)
@@ -217,7 +226,14 @@ class RepeatedEditedNearestNeighbours(BaseMulticlassSampler):
  If None, the random number generator is the RandomState instance used
  by np.random.
 
- size_ngh : int, optional (default=3)
+ size_ngh : int, optional (default=None)
+ Size of the neighbourhood to consider to compute the average
+ distance to the minority point samples.
+
+ NOTE: size_ngh is deprecated from 0.2 and will be replaced in 0.4
+ Use ``n_neighbors`` instead.
+
+ n_neighbors : int, optional (default=3)
  Size of the neighbourhood to consider to compute the average
  distance to the minority point samples.
 
@@ -283,18 +299,20 @@ class RepeatedEditedNearestNeighbours(BaseMulticlassSampler):
  """
 
  def __init__(self, return_indices=False, random_state=None,
- size_ngh=3, max_iter=100, kind_sel='all', n_jobs=-1):
+ size_ngh=None, n_neighbors=3, max_iter=100, kind_sel='all',
+ n_jobs=-1):
  super(RepeatedEditedNearestNeighbours, self).__init__()
  self.return_indices = return_indices
  self.random_state = random_state
  self.size_ngh = size_ngh
+ self.n_neighbors = n_neighbors
  self.kind_sel = kind_sel
  self.n_jobs = n_jobs
  self.max_iter = max_iter
  self.enn_ = EditedNearestNeighbours(
  return_indices=self.return_indices,
  random_state=self.random_state,
- size_ngh=self.size_ngh,
+ n_neighbors=self.n_neighbors,
  kind_sel=self.kind_sel,
  n_jobs=self.n_jobs)
 
@@ -441,7 +459,14 @@ class AllKNN(BaseMulticlassSampler):
  If None, the random number generator is the RandomState instance used
  by np.random.
 
- size_ngh : int, optional (default=3)
+ size_ngh : int, optional (default=None)
+ Size of the neighbourhood to consider to compute the average
+ distance to the minority point samples.
+
+ NOTE: size_ngh is deprecated from 0.2 and will be replaced in 0.4
+ Use ``n_neighbors`` instead.
+
+ n_neighbors : int, optional (default=3)
  Size of the neighbourhood to consider to compute the average
  distance to the minority point samples.
 
@@ -503,17 +528,18 @@ class AllKNN(BaseMulticlassSampler):
  """
 
  def __init__(self, return_indices=False, random_state=None,
- size_ngh=3, kind_sel='all', n_jobs=-1):
+ size_ngh=None, n_neighbors=3, kind_sel='all', n_jobs=-1):
  super(AllKNN, self).__init__()
  self.return_indices = return_indices
  self.random_state = random_state
  self.size_ngh = size_ngh
+ self.n_neighbors = n_neighbors
  self.kind_sel = kind_sel
  self.n_jobs = n_jobs
  self.enn_ = EditedNearestNeighbours(
  return_indices=self.return_indices,
  random_state=self.random_state,
- size_ngh=self.size_ngh,
+ n_neighbors=self.n_neighbors,
  kind_sel=self.kind_sel,
  n_jobs=self.n_jobs)
 
@@ -572,10 +598,11 @@ def _sample(self, X, y):
  if self.return_indices:
  idx_under = np.arange(X.shape[0], dtype=int)
 
- for curr_size_ngh in range(1, self.size_ngh + 1):
+ for curr_size_ngh in range(1, self.n_neighbors + 1):
  self.logger.debug('Apply ENN size_ngh #%s', curr_size_ngh)
  # updating ENN size_ngh
  self.enn_.size_ngh = curr_size_ngh
+
  if self.return_indices:
  X_enn, y_enn, idx_enn = self.enn_.fit_sample(X_, y_)
  else: