Merge pull request scikit-learn#417 from larsmans/multilabel

MRG : ENH multilabel learning in OneVsRestClassifier

Author: amueller

doc/datasets/index.rst

@@ -116,6 +116,7 @@ can be used to build artifical datasets of controled size and complexity.
    :template: function.rst
 
    make_classification
+   make_multilabel_classification
    make_regression
    make_blobs
    make_friedman1

doc/modules/classes.rst

@@ -145,6 +145,7 @@ Samples generator
    :template: function.rst
 
    datasets.make_classification
+   datasets.make_multilabel_classification
    datasets.make_regression
    datasets.make_blobs
    datasets.make_friedman1
@@ -640,6 +641,39 @@ Pairwise metrics
    mixture.VBGMM
 
 
+.. _multiclass_ref:
+
+:mod:`sklearn.multiclass`: Multiclass and multilabel classification
+===================================================================
+
+.. automodule:: sklearn.multiclass
+   :no-members:
+   :no-inherited-members:
+
+**User guide:** See the :ref:`multiclass` section for further details.
+
+.. currentmodule:: sklearn
+
+.. autosummary::
+    :toctree: generated
+    :template: class.rst
+
+    multiclass.OneVsRestClassifier
+    multiclass.OneVsOneClassifier
+    multiclass.OutputCodeClassifier
+
+.. autosummary::
+    :toctree: generated
+    :template: function.rst
+
+    multiclass.fit_ovr
+    multiclass.predict_ovr
+    multiclass.fit_ovo
+    multiclass.predict_ovo
+    multiclass.fit_ecoc
+    multiclass.predict_ecoc
+
+
 .. _naive_bayes_ref:
 
 :mod:`sklearn.naive_bayes`: Naive Bayes

doc/modules/multiclass.rst

@@ -1,17 +1,23 @@
 
 .. _multiclass:
 
-=====================
-Multiclass algorithms
-=====================
+====================================
+Multiclass and multilabel algorithms
+====================================
 
 .. currentmodule:: sklearn.multiclass
 
-This module implements multiclass learning algorithms:
+This module implements multiclass and multilabel learning algorithms:
     - one-vs-the-rest / one-vs-all
     - one-vs-one
     - error correcting output codes
 
+Multiclass classification means classification with more than two classes.
+Multilabel classification is a different task, where a classifier is used to
+predict a set of target labels for each instance; i.e., the set of target
+classes is not assumed to be disjoint as in ordinary (binary or multiclass)
+classification. This is also called any-of classification.
+
 The estimators provided in this module are meta-estimators: they require a base
 estimator to be provided in their constructor. For example, it is possible to
 use these estimators to turn a binary classifier or a regressor into a
@@ -26,9 +32,15 @@ improves.
     multiclass classification out-of-the-box. Below is a summary of the
     classifiers supported in scikit-learn grouped by the strategy used.
 
-    - Inherently multiclass: Naive Bayes, LDA.
-    - One-Vs-One: SVC.
-    - One-Vs-All: LinearSVC, LogisticRegression, SGDClassifier, RidgeClassifier.
+    - Inherently multiclass: Naive Bayes, :class:`LDA`.
+    - One-Vs-One: :class:`SVC`.
+    - One-Vs-All: :class:`LinearSVC`, :class:`LogisticRegression`,
+      :class:`SGDClassifier`, :class:`RidgeClassifier`.
+
+.. note::
+
+    At the moment there are no evaluation metrics implemented for multilabel
+    learnings.
 
 
 One-Vs-The-Rest
@@ -57,6 +69,24 @@ fair default choice. Below is an example::
          2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 2, 2, 2, 1, 2, 2, 2, 2,
          2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2])
 
+Multilabel learning with OvR
+----------------------------
+
+``OneVsRestClassifier`` also supports multilabel classification.
+To use this feature, feed the classifier a list of tuples containing
+target labels, like in the example below.
+
+
+.. figure:: ../auto_examples/images/plot_multilabel_1.png
+    :target: ../auto_examples/plot_multilabel.html
+    :align: center
+    :scale: 75%
+
+
+.. topic:: Examples:
+
+    * :ref:`example_plot_multilabel.py`
+
 
 One-Vs-One
 ==========

examples/plot_multilabel.py

@@ -0,0 +1,75 @@
+"""
+=========================
+Multilabel classification
+=========================
+
+This example simulates a multi-label document classification problem. The
+dataset is generated randomly based on the following process:
+
+    - pick the number of labels: n ~ Poisson(n_labels)
+    - n times, choose a class c: c ~ Multinomial(theta)
+    - pick the document length: k ~ Poisson(length)
+    - k times, choose a word: w ~ Multinomial(theta_c)
+
+In the above process, rejection sampling is used to make sure that
+n is never zero or more than 2, and that the document length
+is never zero. Likewise, we reject classes which have already been chosen.
+The documents that are assigned to both classes are plotted surrounded by
+two colored circles.
+
+The classification is performed by projecting to the first two principal
+components for visualisation purposes, followed by using the
+:class:`sklearn.multiclass.OneVsRestClassifier` metaclassifier using two SVCs
+with linear kernels to learn a discriminative model for each class.
+"""
+print __doc__
+
+import numpy as np
+import matplotlib.pylab as pl
+
+from sklearn.datasets import make_multilabel_classification
+from sklearn.multiclass import OneVsRestClassifier
+from sklearn.svm import SVC
+from sklearn.decomposition import PCA
+
+
+def plot_hyperplane(clf, min_x, max_x, linestyle, label):
+    # get the separating hyperplane
+    w = clf.coef_[0]
+    a = -w[0] / w[1]
+    xx = np.linspace(min_x, max_x)
+    yy = a * xx - (clf.intercept_[0]) / w[1]
+    pl.plot(xx, yy, linestyle, label=label)
+
+
+X, Y = make_multilabel_classification(n_classes=2, n_labels=1, random_state=42)
+X = PCA(n_components=2).fit_transform(X)
+min_x = np.min(X[:, 0])
+max_x = np.max(X[:, 0])
+
+classif = OneVsRestClassifier(SVC(kernel='linear'))
+classif.fit(X, Y)
+
+pl.figure()
+pl.title('Multilabel classification example')
+pl.xlabel('First principal component')
+pl.ylabel('Second principal component')
+
+zero_class = np.where([0 in y for y in Y])
+one_class = np.where([1 in y for y in Y])
+pl.scatter(X[:, 0], X[:, 1], s=40, c='gray')
+pl.scatter(X[zero_class, 0], X[zero_class, 1], s=160, edgecolors='b',
+           facecolors='none', linewidths=2, label='Class 1')
+pl.scatter(X[one_class, 0], X[one_class, 1], s=80, edgecolors='orange',
+           facecolors='none', linewidths=2, label='Class 2')
+pl.axis('tight')
+
+plot_hyperplane(classif.estimators_[0], min_x, max_x, 'k--',
+                'Boundary\nfor class 1')
+plot_hyperplane(classif.estimators_[1], min_x, max_x, 'k-.',
+                'Boundary\nfor class 2')
+pl.xticks(())
+pl.yticks(())
+pl.legend()
+
+pl.show()

sklearn/datasets/__init__.py

@@ -24,6 +24,7 @@
 from .twenty_newsgroups import load_20newsgroups
 from .mldata import fetch_mldata, mldata_filename
 from .samples_generator import make_classification
+from .samples_generator import make_multilabel_classification
 from .samples_generator import make_regression
 from .samples_generator import make_blobs
 from .samples_generator import make_friedman1