[MRG] User Guide

Makefile

@@ -11,6 +11,7 @@ clean:
 	rm -rf coverage
 	rm -rf dist
 	rm -rf build
+	rm -rf doc/_build
 	rm -rf doc/auto_examples
 	rm -rf doc/generated
 	rm -rf doc/modules
@@ -35,7 +36,6 @@ test-coverage:
 test: test-coverage test-doc
 
 html:
-	conda install -y sphinx sphinx_rtd_theme numpydoc
 	export SPHINXOPTS=-W; make -C doc html
 
 conda:

README.rst

@@ -83,6 +83,10 @@ commands to get a copy from GitHub and install all dependencies::
   cd imbalanced-learn
   pip install .
 
+Or install using pip and GitHub::
+
+  pip install -U git+https://github.com/scikit-learn-contrib/imbalanced-learn.git
+
 Testing
 ~~~~~~~
 

doc/_static/js/copybutton.js

@@ -0,0 +1,63 @@
+$(document).ready(function() {
+    /* Add a [>>>] button on the top-right corner of code samples to hide
+     * the >>> and ... prompts and the output and thus make the code
+     * copyable. */
+    var div = $('.highlight-python .highlight,' +
+                '.highlight-python3 .highlight,' +
+                '.highlight-pycon .highlight,' +
+		'.highlight-default .highlight')
+    var pre = div.find('pre');
+
+    // get the styles from the current theme
+    pre.parent().parent().css('position', 'relative');
+    var hide_text = 'Hide the prompts and output';
+    var show_text = 'Show the prompts and output';
+    var border_width = pre.css('border-top-width');
+    var border_style = pre.css('border-top-style');
+    var border_color = pre.css('border-top-color');
+    var button_styles = {
+        'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0',
+        'border-color': border_color, 'border-style': border_style,
+        'border-width': border_width, 'color': border_color, 'text-size': '75%',
+        'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em',
+        'border-radius': '0 3px 0 0'
+    }
+
+    // create and add the button to all the code blocks that contain >>>
+    div.each(function(index) {
+        var jthis = $(this);
+        if (jthis.find('.gp').length > 0) {
+            var button = $('<span class="copybutton">&gt;&gt;&gt;</span>');
+            button.css(button_styles)
+            button.attr('title', hide_text);
+            button.data('hidden', 'false');
+            jthis.prepend(button);
+        }
+        // tracebacks (.gt) contain bare text elements that need to be
+        // wrapped in a span to work with .nextUntil() (see later)
+        jthis.find('pre:has(.gt)').contents().filter(function() {
+            return ((this.nodeType == 3) && (this.data.trim().length > 0));
+        }).wrap('<span>');
+    });
+
+    // define the behavior of the button when it's clicked
+    $('.copybutton').click(function(e){
+        e.preventDefault();
+        var button = $(this);
+        if (button.data('hidden') === 'false') {
+            // hide the code output
+            button.parent().find('.go, .gp, .gt').hide();
+            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden');
+            button.css('text-decoration', 'line-through');
+            button.attr('title', show_text);
+            button.data('hidden', 'true');
+        } else {
+            // show the code output
+            button.parent().find('.go, .gp, .gt').show();
+            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible');
+            button.css('text-decoration', 'none');
+            button.attr('title', hide_text);
+            button.data('hidden', 'false');
+        }
+    });
+});

doc/_templates/class.rst

@@ -0,0 +1,16 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}==============
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   .. automethod:: __init__
+   {% endblock %}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div style='clear:both'></div>

doc/_templates/function.rst

@@ -0,0 +1,12 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}====================
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div style='clear:both'></div>

doc/_templates/numpydoc_docstring.py

@@ -0,0 +1,16 @@
+{{index}}
+{{summary}}
+{{extended_summary}}
+{{parameters}}
+{{returns}}
+{{yields}}
+{{other_parameters}}
+{{attributes}}
+{{raises}}
+{{warns}}
+{{warnings}}
+{{see_also}}
+{{notes}}
+{{references}}
+{{examples}}
+{{methods}}

doc/api.rst

@@ -6,8 +6,8 @@ This is the full API documentation of the `imbalanced-learn` toolbox.
 
 .. _under_sampling_ref:
 
-Under-sampling methods
-======================
+:mod:`imblearn.under_sampling`: Under-sampling methods
+======================================================
 
 .. automodule:: imblearn.under_sampling
     :no-members:
@@ -26,6 +26,7 @@ Prototype generation
 
 .. autosummary::
    :toctree: generated/
+   :template: class.rst
 
    under_sampling.ClusterCentroids
 
@@ -40,6 +41,7 @@ Prototype selection
 
 .. autosummary::
    :toctree: generated/
+   :template: class.rst
 
    under_sampling.CondensedNearestNeighbour
    under_sampling.EditedNearestNeighbours
@@ -54,8 +56,8 @@ Prototype selection
 
 .. _over_sampling_ref:
 
-Over-sampling methods
-=====================
+:mod:`imblearn.over_sampling`: Over-sampling methods
+====================================================
 
 .. automodule:: imblearn.over_sampling
     :no-members:
@@ -65,6 +67,7 @@ Over-sampling methods
 
 .. autosummary::
    :toctree: generated/
+   :template: class.rst
 
    over_sampling.ADASYN
    over_sampling.RandomOverSampler
@@ -73,8 +76,8 @@ Over-sampling methods
 
 .. _combine_ref:
 
-Combination of over- and under-sampling methods
-===============================================
+:mod:`imblearn.combine`: Combination of over- and under-sampling methods
+========================================================================
 
 .. automodule:: imblearn.combine
    :no-members:
@@ -84,15 +87,16 @@ Combination of over- and under-sampling methods
 
 .. autosummary::
    :toctree: generated/
+   :template: class.rst
 
    combine.SMOTEENN
    combine.SMOTETomek
 
 
 .. _ensemble_ref:
 
-Ensemble methods
-================
+:mod:`imblearn.ensemble`: Ensemble methods
+==========================================
 
 .. automodule:: imblearn.ensemble
     :no-members:
@@ -102,15 +106,16 @@ Ensemble methods
 
 .. autosummary::
    :toctree: generated/
+   :template: class.rst
 
    ensemble.BalanceCascade
    ensemble.EasyEnsemble
 
 
 .. _pipeline_ref:
 
-Pipeline
-========
+:mod:`imblearn.pipeline`: Pipeline
+==================================
 
 .. automodule:: imblearn.pipeline
     :no-members:
@@ -120,14 +125,20 @@ Pipeline
 
 .. autosummary::
    :toctree: generated/
+   :template: class.rst
 
    pipeline.Pipeline
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
    pipeline.make_pipeline
 
 .. _metrics_ref:
 
-Metrics
-=======
+:mod:`imblearn.metrics`: Metrics
+================================
 
 .. automodule:: imblearn.metrics
    :no-members:
@@ -137,6 +148,7 @@ Metrics
 
 .. autosummary::
    :toctree: generated/
+   :template: function.rst
 
    metrics.classification_report_imbalanced
    metrics.sensitivity_specificity_support
@@ -147,8 +159,8 @@ Metrics
 
 .. _datasets_ref:
 
-Datasets
-========
+:mod:`imblearn.datasets`: Datasets
+==================================
 
 .. automodule:: imblearn.datasets
     :no-members:
@@ -158,12 +170,13 @@ Datasets
 
 .. autosummary::
    :toctree: generated/
+   :template: function.rst
 
    datasets.make_imbalance
    datasets.fetch_datasets
 
-Utilities
-=========
+:mod:`imblearn.utils`: Utilities
+================================
 
 .. automodule:: imblearn.utils
     :no-members:
@@ -173,6 +186,7 @@ Utilities
 
 .. autosummary::
    :toctree: generated/
+   :template: function.rst
 
    utils.estimator_checks.check_estimator
    utils.check_neighbors_object

doc/combine.rst

@@ -0,0 +1,56 @@
+.. _combine:
+
+=======================================
+Combination of over- and under-sampling
+=======================================
+
+.. currentmodule:: imblearn.over_sampling
+
+We previously presented :class:`SMOTE` and showed that this method can generate
+noisy samples by interpolating new points between marginal outliers and
+inliers. This issue can be solved by cleaning the resulted space obtained
+after over-sampling.
+
+.. currentmodule:: imblearn.combine
+
+In this regard, Tomek's link and edited nearest-neighbours are the two cleaning
+methods which have been added pipeline after SMOTE over-sampling to obtain a
+cleaner space. Therefore, imbalanced-learn implemented two ready-to-use class
+which pipeline both over- and under-sampling methods: (i) :class:`SMOTETomek`
+and (ii) :class:`SMOTEENN`.
+
+These two classes can be used as any other sampler with identical parameters
+than their former samplers::
+
+  >>> from collections import Counter
+  >>> from sklearn.datasets import make_classification
+  >>> X, y = make_classification(n_samples=5000, n_features=2, n_informative=2,
+  ...                            n_redundant=0, n_repeated=0, n_classes=3,
+  ...                            n_clusters_per_class=1,
+  ...                            weights=[0.01, 0.05, 0.94],
+  ...                            class_sep=0.8, random_state=0)
+  >>> print(Counter(y))
+  Counter({2: 4674, 1: 262, 0: 64})
+  >>> from imblearn.combine import SMOTEENN
+  >>> smote_enn = SMOTEENN(random_state=0)
+  >>> X_resampled, y_resampled = smote_enn.fit_sample(X, y)
+  >>> print(Counter(y_resampled))
+  Counter({1: 4381, 0: 4060, 2: 3502})
+  >>> from imblearn.combine import SMOTETomek
+  >>> smote_tomek = SMOTETomek(random_state=0)
+  >>> X_resampled, y_resampled = smote_tomek.fit_sample(X, y)
+  >>> print(Counter(y_resampled))
+  Counter({1: 4566, 0: 4499, 2: 4413})
+
+We can also see in the example below that :class:`SMOTEENN` tends to clean more
+noisy samples than :class:`SMOTETomek`.
+
+.. image:: ./auto_examples/combine/images/sphx_glr_plot_comparison_combine_001.png
+   :target: ./auto_examples/combine/plot_comparison_combine.html
+   :scale: 60
+   :align: center
+
+See :ref:`sphx_glr_auto_examples_combine_plot_smote_enn.py`,
+:ref:`sphx_glr_auto_examples_combine_plot_smote_tomek.py`,
+and
+:ref:`sphx_glr_auto_examples_combine_plot_comparison_combine.py`.