Resolve #111 - Handle multiclass/binary targets

Author: glemaitre

doc/api.rst

@@ -117,3 +117,4 @@ Functions
    :toctree: generated/
 
    pipeline.make_pipeline
+

doc/whats_new.rst

@@ -12,10 +12,26 @@ Version 0.2
 Changelog
 ---------
 
-- Added support for bumpversion.
-- Added doctest in the documentation.
+New features
+~~~~~~~~~~~~
+
 - Added AllKNN under sampling technique.
 
+API changes summary
+~~~~~~~~~~~~~~~~~~~
+
+- Two base classes :class:`BaseBinaryclassSampler` and :class:`BaseMulticlassSampler` have been created to handle the target type and raise warning in case of abnormality.
+
+Enhancement
+~~~~~~~~~~~
+
+- Added support for bumpversion.
+- Validate the type of target in binary samplers. A warning is raised for the moment.
+
+Documentation changes
+~~~~~~~~~~~~~~~~~~~~~
+
+- Added doctest in the documentation.
 
 .. _changes_0_1:
 

imblearn/__init__.py

@@ -14,6 +14,8 @@
     Module which provides methods to under-sample a dataset.
 under-sampling
     Module which provides methods to over-sample a dataset.
+pipeline
+    Module which allowing to create pipeline with scikit-learn estimators.
 """
 
 from .version import _check_module_dependencies, __version__

imblearn/base.py

@@ -14,6 +14,7 @@
 
 from sklearn.base import BaseEstimator
 from sklearn.utils import check_X_y
+from sklearn.utils.multiclass import type_of_target
 from sklearn.externals import six
 
 from six import string_types
@@ -27,7 +28,7 @@ class SamplerMixin(six.with_metaclass(ABCMeta, BaseEstimator)):
     instead.
     """
 
-    _estimator_type = "sampler"
+    _estimator_type = 'sampler'
 
     def __init__(self, ratio='auto'):
         """Initialize this object and its instance variables.
@@ -226,3 +227,74 @@ def __setstate__(self, dict):
         logger = logging.getLogger(__name__)
         self.__dict__.update(dict)
         self.logger = logger
+
+
+class BaseBinarySampler(six.with_metaclass(ABCMeta, SamplerMixin)):
+    """Base class for all binary class sampler.
+
+    Warning: This class should not be used directly. Use derived classes
+    instead.
+
+    """
+
+    def fit(self, X, y):
+        """Find the classes statistics before to perform sampling.
+
+        Parameters
+        ----------
+        X : ndarray, shape (n_samples, n_features)
+            Matrix containing the data which have to be sampled.
+
+        y : ndarray, shape (n_samples, )
+            Corresponding label for each sample in X.
+
+        Returns
+        -------
+        self : object,
+            Return self.
+
+        """
+
+        super(BaseBinarySampler, self).fit(X, y)
+
+        # Check that the target type is binary
+        if not type_of_target(y) == 'binary':
+            warnings.warn('The target type should be binary.')
+
+        return self
+
+
+class BaseMulticlassSampler(six.with_metaclass(ABCMeta, SamplerMixin)):
+    """Base class for all multiclass sampler.
+
+    Warning: This class should not be used directly. Use derived classes
+    instead.
+
+    """
+
+    def fit(self, X, y):
+        """Find the classes statistics before to perform sampling.
+
+        Parameters
+        ----------
+        X : ndarray, shape (n_samples, n_features)
+            Matrix containing the data which have to be sampled.
+
+        y : ndarray, shape (n_samples, )
+            Corresponding label for each sample in X.
+
+        Returns
+        -------
+        self : object,
+            Return self.
+
+        """
+
+        super(BaseMulticlassSampler, self).fit(X, y)
+
+        # Check that the target type is either binary or multiclass
+        if not (type_of_target(y) == 'binary' or
+                type_of_target(y) == 'multiclass'):
+            warnings.warn('The target type should be binary or multiclass.')
+
+        return self

imblearn/combine/smote_enn.py

@@ -4,10 +4,10 @@
 
 from ..over_sampling import SMOTE
 from ..under_sampling import EditedNearestNeighbours
-from ..base import SamplerMixin
+from ..base import BaseBinarySampler
 
 
-class SMOTEENN(SamplerMixin):
+class SMOTEENN(BaseBinarySampler):
     """Class to perform over-sampling using SMOTE and cleaning using ENN.
 
     Combine over- and under-sampling using SMOTE and Edited Nearest Neighbours.

imblearn/combine/smote_tomek.py

@@ -5,10 +5,10 @@
 
 from ..over_sampling import SMOTE
 from ..under_sampling import TomekLinks
-from ..base import SamplerMixin
+from ..base import BaseBinarySampler
 
 
-class SMOTETomek(SamplerMixin):
+class SMOTETomek(BaseBinarySampler):
     """Class to perform over-sampling using SMOTE and cleaning using
     Tomek links.
 

imblearn/combine/tests/test_smote_enn.py

@@ -131,3 +131,18 @@ def test_sample_wrong_X():
     sm.fit(X, Y)
     assert_raises(RuntimeError, sm.sample, np.random.random((100, 40)),
                   np.array([0] * 50 + [1] * 50))
+
+
+def test_senn_multiclass_error():
+    """ Test either if an error is raised when the target are not binary
+    type. """
+
+    # continuous case
+    y = np.linspace(0, 1, 5000)
+    sm = SMOTEENN(random_state=RND_SEED)
+    assert_warns(UserWarning, sm.fit, X, y)
+
+    # multiclass case
+    y = np.array([0] * 2000 + [1] * 2000 + [2] * 1000)
+    sm = SMOTEENN(random_state=RND_SEED)
+    assert_warns(UserWarning, sm.fit, X, y)

imblearn/combine/tests/test_smote_tomek.py

@@ -131,3 +131,18 @@ def test_sample_wrong_X():
     sm.fit(X, Y)
     assert_raises(RuntimeError, sm.sample, np.random.random((100, 40)),
                   np.array([0] * 50 + [1] * 50))
+
+
+def test_multiclass_error():
+    """ Test either if an error is raised when the target are not binary
+    type. """
+
+    # continuous case
+    y = np.linspace(0, 1, 5000)
+    sm = SMOTETomek(random_state=RND_SEED)
+    assert_warns(UserWarning, sm.fit, X, y)
+
+    # multiclass case
+    y = np.array([0] * 2000 + [1] * 2000 + [2] * 1000)
+    sm = SMOTETomek(random_state=RND_SEED)
+    assert_warns(UserWarning, sm.fit, X, y)

imblearn/ensemble/balance_cascade.py

@@ -5,14 +5,14 @@
 
 from sklearn.utils import check_random_state
 
-from ..base import SamplerMixin
+from ..base import BaseBinarySampler
 
 
 ESTIMATOR_KIND = ('knn', 'decision-tree', 'random-forest', 'adaboost',
                   'gradient-boosting', 'linear-svm')
 
 
-class BalanceCascade(SamplerMixin):
+class BalanceCascade(BaseBinarySampler):
     """Create an ensemble of balanced sets by iteratively under-sampling the
     imbalanced dataset using an estimator.
 
@@ -100,6 +100,7 @@ class BalanceCascade(SamplerMixin):
        April 2009.
 
     """
+
     def __init__(self, ratio='auto', return_indices=False, random_state=None,
                  n_max_subset=None, classifier='knn', bootstrap=True,
                  **kwargs):

imblearn/ensemble/easy_ensemble.py

@@ -3,11 +3,11 @@
 
 import numpy as np
 
-from ..base import SamplerMixin
+from ..base import BaseMulticlassSampler
 from ..under_sampling import RandomUnderSampler
 
 
-class EasyEnsemble(SamplerMixin):
+class EasyEnsemble(BaseMulticlassSampler):
     """Create an ensemble sets by iteratively applying random under-sampling.
 
     This method iteratively select a random subset and make an ensemble of the
@@ -56,6 +56,8 @@ class EasyEnsemble(SamplerMixin):
     -----
     The method is described in [1]_.
 
+    This method supports multiclass target type.
+
     Examples
     --------