From 0aee15adb1abfef4318ac7193fb105c1c3ecbfbb Mon Sep 17 00:00:00 2001
From: Joan Massich <sik@visor.udg.edu>
Date: Wed, 6 Jun 2018 16:58:14 +0200
Subject: [PATCH 01/25] Use consistent naming

---
 doc/modules/multiclass.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 7090967aac221..f51812991ccb6 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -14,7 +14,7 @@ Multiclass and multilabel algorithms
 
 The :mod:`sklearn.multiclass` module implements *meta-estimators* to solve
 ``multiclass`` and ``multilabel`` classification problems
-by decomposing such problems into binary classification problems. Multitarget
+by decomposing such problems into binary classification problems. Multioutput
 regression is also supported.
 
 - **Multiclass classification** means a classification task with more than
@@ -34,7 +34,8 @@ regression is also supported.
   for each data-point, such as wind direction and magnitude at a
   certain location.
 
-- **Multioutput-multiclass classification** and **multi-task classification**
+- **Multioutput-multiclass classification** 
+  (also known as **multi-task classification**)
   means that a single estimator has to handle several joint classification
   tasks. This is both a generalization of the multi-label classification
   task, which only considers binary classification, as well as a
@@ -94,7 +95,7 @@ if you're using one of these, unless you want custom multiclass behavior:
   - :class:`sklearn.gaussian_process.GaussianProcessClassifier` (setting multi_class = "one_vs_one")
 
 
-- **Multiclass as One-Vs-All:**
+- **Multiclass as One-Vs-The-Rest:**
 
   - :class:`sklearn.ensemble.GradientBoostingClassifier`
   - :class:`sklearn.gaussian_process.GaussianProcessClassifier` (setting multi_class = "one_vs_rest")

From b17598a0d7ce10222f0c58f6f37ec30d56806ef2 Mon Sep 17 00:00:00 2001
From: Joan Massich <sik@visor.udg.edu>
Date: Tue, 10 Jul 2018 05:26:18 +0200
Subject: [PATCH 02/25] [draft] Use the same 'fruit' example to drive the
 conversation

---
 doc/modules/multiclass.rst | 101 ++++++++++++++++++++++++-------------
 1 file changed, 65 insertions(+), 36 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index f51812991ccb6..d78c45a235ced 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -14,46 +14,75 @@ Multiclass and multilabel algorithms
 
 The :mod:`sklearn.multiclass` module implements *meta-estimators* to solve
 ``multiclass`` and ``multilabel`` classification problems
-by decomposing such problems into binary classification problems. Multioutput
+by decomposing such problems into binary classification problems. ``multioutput``
 regression is also supported.
 
-- **Multiclass classification** means a classification task with more than
-  two classes; e.g., classify a set of images of fruits which may be oranges,
-  apples, or pears. Multiclass classification makes the assumption that each
-  sample is assigned to one and only one label: a fruit can be either an
-  apple or a pear but not both at the same time.
+- **Multiclass classification** produce single output that is categorical variable.
+  In other words, a single classification task with more than two classes.
 
-- **Multilabel classification** assigns to each sample a set of target
-  labels. This can be thought as predicting properties of a data-point
-  that are not mutually exclusive, such as topics that are relevant for a
-  document. A text might be about any of religion, politics, finance or
-  education at the same time or none of these.
+  - valid :term:`multiclass` representation for
+    :func:`~utils.multiclass.type_of_target` (`y`) are:
 
-- **Multioutput regression** assigns each sample a set of target
-  values.  This can be thought of as predicting several properties
-  for each data-point, such as wind direction and magnitude at a
-  certain location.
+    - 1d or column vector containing more than two discrete values.
+    - sparse :term:`binary` matrix of shape ``(n_samples, n_classes)`` with a single element per row, where each column represents one class.
 
-- **Multioutput-multiclass classification** 
+  - *example:* classify a set of images of fruits which may be oranges, apples,
+    or pears. Multiclass classification makes the assumption that each sample is
+    assigned to one and only one label: a fruit can be either an apple or a pear
+    but not both at the same time.
+
+- **Multilabel classification** predict a set of binary attributes that can
+  either be true or false independently of one another. In other words, assigns
+  to each sample a set of target labels. (This task can also be seen as a binary
+  label multioutput task)
+
+  - valid representation :term:`multilabel` `y` is:
+
+    - either dense (or sparse) :term:`binary` matrix of shape
+      ``(n_samples, n_classes)`` with multiple active elements per row to denote
+      that the sample belongs to multiple classes. Each column represents a class.
+
+  - *example:* based on an arbitrary set of features from fruit images, **Multilabel
+    classification** simultaneously predict a set of binary attributes such as:
+    grows in a tree, has stone fruit, is citric ...
+
+- **Multioutput regression** predicts multiple outputs that are all continuous
+  variables. In other words, assigns each sample a set of target values.
+
+  - valid representation :term:`multilabel` `y` is:
+
+    - dense matrix of shape ``(n_samples, n_classes)`` of floats. A column wise
+      concatenation of :term:`continuous` variables.
+
+  - *example:* based on an arbitrary set of features from fruit images, predicts
+    a set of :term:`contineous` variables such as: weight, sugar content, calories, etc.
+
+- **Multioutput-multiclass classification**
   (also known as **multi-task classification**)
   means that a single estimator has to handle several joint classification
   tasks. This is both a generalization of the multi-label classification
   task, which only considers binary classification, as well as a
-  generalization of the multi-class classification task.  *The output format
-  is a 2d numpy array or sparse matrix.*
-
-  The set of labels can be different for each output variable.
-  For instance, a sample could be assigned "pear" for an output variable that
-  takes possible values in a finite set of species such as "pear", "apple"; 
-  and "blue" or "green" for a second output variable that takes possible values
-  in a finite set of colors such as "green", "red", "blue", "yellow"...
-
-  This means that any classifiers handling multi-output
-  multiclass or multi-task classification tasks,
-  support the multi-label classification task as a special case.
-  Multi-task classification is similar to the multi-output
-  classification task with different model formulations. For
-  more information, see the relevant estimator documentation.
+  generalization of the multi-class classification task.
+
+
+  - valid representation :term:`multilabel` `y` is:
+
+    - dense matrix of shape ``(n_samples, n_classes)`` of floats. A column wise
+      concatenation of 1d :term:`multiclass` variables.
+
+  - *example:*  The set of labels can be different for each output variable.
+    For instance, a sample could be assigned "pear" for an output variable that
+    takes possible values in a finite set of species such as "pear", "apple";
+    and "blue" or "green" for a second output variable that takes possible values
+    in a finite set of colors such as "green", "red", "blue", "yellow"...
+
+  - Note that any classifiers handling multi-output
+    multiclass or multi-task classification tasks,
+    support the multi-label classification task as a special case.
+    Multi-task classification is similar to the multi-output
+    classification task with different model formulations. For
+    more information, see the relevant estimator documentation.
+
 
 All scikit-learn classifiers are capable of multiclass classification,
 but the meta-estimators offered by :mod:`sklearn.multiclass`
@@ -168,7 +197,7 @@ This strategy, also known as **one-vs-all**, is implemented in
 per class. For each classifier, the class is fitted against all the other
 classes. In addition to its computational efficiency (only `n_classes`
 classifiers are needed), one advantage of this approach is its
-interpretability. Since each class is represented by one and only one classifier, 
+interpretability. Since each class is represented by one and only one classifier,
 it is possible to gain knowledge about the class by inspecting its
 corresponding classifier. This is the most commonly used strategy and is a fair
 default choice.
@@ -371,7 +400,7 @@ that are trained on a single X predictor matrix to predict a series
 of responses (y1,y2,y3...,yn).
 
 Below is an example of multioutput classification:
-    
+
     >>> from sklearn.datasets import make_classification
     >>> from sklearn.multioutput import MultiOutputClassifier
     >>> from sklearn.ensemble import RandomForestClassifier
@@ -434,7 +463,7 @@ averaged together.
 Regressor Chain
 ================
 
-Regressor chains (see :class:`RegressorChain`) is analogous to 
-ClassifierChain as a way of combining a number of regressions 
-into a single multi-target model that is capable of exploiting 
+Regressor chains (see :class:`RegressorChain`) is analogous to
+ClassifierChain as a way of combining a number of regressions
+into a single multi-target model that is capable of exploiting
 correlations among targets.

From 2e03d7a02b6fae442fc2dc99436754d35f6c7faf Mon Sep 17 00:00:00 2001
From: Joan Massich <sik@visor.udg.edu>
Date: Fri, 6 Sep 2019 16:51:37 +0200
Subject: [PATCH 03/25] [emtpy] trigger circle


From 2c13dcfc230c815d14020878335d3b9a198a4169 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Fri, 6 Sep 2019 17:50:14 +0200
Subject: [PATCH 04/25] [empty] push to sik PR


From 27b08c40ef680d9f9bf9aa74e69a55daeae06775 Mon Sep 17 00:00:00 2001
From: Joan Massich <sik@visor.udg.edu>
Date: Fri, 6 Sep 2019 18:12:24 +0200
Subject: [PATCH 05/25] add the examples to the explanation

---
 doc/modules/multiclass.rst | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index d78c45a235ced..5e4115c2f6076 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -20,42 +20,46 @@ regression is also supported.
 - **Multiclass classification** produce single output that is categorical variable.
   In other words, a single classification task with more than two classes.
 
+  *example:* classify a set of images of fruits which may be oranges, apples, or
+   pears. Multiclass classification makes the assumption that each sample is
+   assigned to one and only one label: a fruit can be either an apple or a pear
+   but not both at the same time.
+
   - valid :term:`multiclass` representation for
     :func:`~utils.multiclass.type_of_target` (`y`) are:
 
     - 1d or column vector containing more than two discrete values.
     - sparse :term:`binary` matrix of shape ``(n_samples, n_classes)`` with a single element per row, where each column represents one class.
 
-  - *example:* classify a set of images of fruits which may be oranges, apples,
-    or pears. Multiclass classification makes the assumption that each sample is
-    assigned to one and only one label: a fruit can be either an apple or a pear
-    but not both at the same time.
 
 - **Multilabel classification** predict a set of binary attributes that can
   either be true or false independently of one another. In other words, assigns
   to each sample a set of target labels. (This task can also be seen as a binary
   label multioutput task)
 
+  *example:* based on an arbitrary set of features from fruit images,
+    **Multilabel classification** simultaneously predict a set of binary
+    attributes such as: grows in a tree, has stone fruit, is citric ...
+
   - valid representation :term:`multilabel` `y` is:
 
     - either dense (or sparse) :term:`binary` matrix of shape
       ``(n_samples, n_classes)`` with multiple active elements per row to denote
       that the sample belongs to multiple classes. Each column represents a class.
 
-  - *example:* based on an arbitrary set of features from fruit images, **Multilabel
-    classification** simultaneously predict a set of binary attributes such as:
-    grows in a tree, has stone fruit, is citric ...
 
 - **Multioutput regression** predicts multiple outputs that are all continuous
   variables. In other words, assigns each sample a set of target values.
 
+  *example:* based on an arbitrary set of features from fruit images, predicts a
+    set of :term:`contineous` variables such as: weight, sugar content,
+    calories, etc.
+
   - valid representation :term:`multilabel` `y` is:
 
     - dense matrix of shape ``(n_samples, n_classes)`` of floats. A column wise
       concatenation of :term:`continuous` variables.
 
-  - *example:* based on an arbitrary set of features from fruit images, predicts
-    a set of :term:`contineous` variables such as: weight, sugar content, calories, etc.
 
 - **Multioutput-multiclass classification**
   (also known as **multi-task classification**)
@@ -64,18 +68,17 @@ regression is also supported.
   task, which only considers binary classification, as well as a
   generalization of the multi-class classification task.
 
+  *example:* The set of labels can be different for each output variable. For
+    instance, a sample could be assigned "pear" for an output variable that
+    takes possible values in a finite set of species such as "pear", "apple";
+    and "blue" or "green" for a second output variable that takes possible
+    values in a finite set of colors such as "green", "red", "blue", "yellow"...
 
   - valid representation :term:`multilabel` `y` is:
 
     - dense matrix of shape ``(n_samples, n_classes)`` of floats. A column wise
       concatenation of 1d :term:`multiclass` variables.
 
-  - *example:*  The set of labels can be different for each output variable.
-    For instance, a sample could be assigned "pear" for an output variable that
-    takes possible values in a finite set of species such as "pear", "apple";
-    and "blue" or "green" for a second output variable that takes possible values
-    in a finite set of colors such as "green", "red", "blue", "yellow"...
-
   - Note that any classifiers handling multi-output
     multiclass or multi-task classification tasks,
     support the multi-label classification task as a special case.

From c5d4cc926ca60925de994cdf94e610f5bfe33f31 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Tue, 10 Sep 2019 18:04:42 +0200
Subject: [PATCH 06/25] rework multiclass explanations

---
 doc/modules/multiclass.rst | 101 +++++++++++++++++++++++--------------
 1 file changed, 64 insertions(+), 37 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 0c247dc2f0976..97e0057d5b1c8 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -17,29 +17,31 @@ The :mod:`sklearn.multiclass` module implements *meta-estimators* to solve
 by decomposing such problems into binary classification problems. ``multioutput``
 regression is also supported.
 
-- **Multiclass classification** produce single output that is categorical variable.
-  In other words, a single classification task with more than two classes.
-
-  *example:* classify a set of images of fruits which may be oranges, apples, or
-   pears. Multiclass classification makes the assumption that each sample is
-   assigned to one and only one label: a fruit can be either an apple or a pear
-   but not both at the same time.
-
-  - valid :term:`multiclass` representation for
+- **Multiclass classification**: classification task which labels each
+  sample as **one** of a number of classes, where the number of classes is
+  greater than 2. Each sample can only be labelled as one class. 
+
+  For example, classification of a set of images of fruit, where each image may
+  either be of an orange, an apples, or a pear. Multiclass classification makes
+  the assumption that each sample is assigned to one and only one label.
+  
+  - Valid :term:`multiclass` representations for
     :func:`~utils.multiclass.type_of_target` (`y`) are:
 
     - 1d or column vector containing more than two discrete values.
-    - sparse :term:`binary` matrix of shape ``(n_samples, n_classes)`` with a single element per row, where each column represents one class.
+    - sparse :term:`binary` matrix of shape ``(n_samples, n_classes)`` with a
+      single element per row, where each column represents one class.
 
 
-- **Multilabel classification** predict a set of binary attributes that can
-  either be true or false independently of one another. In other words, assigns
-  to each sample a set of target labels. (This task can also be seen as a binary
-  label multioutput task)
+- **Multilabel classification**: classification task which labels each sample
+  with a set of binary attributes (either True or False) independently of
+  one another. The number of binary attributes is greater or equal to 2.
 
-  *example:* based on an arbitrary set of features from fruit images,
-    **Multilabel classification** simultaneously predict a set of binary
-    attributes such as: grows in a tree, has stone fruit, is citric ...
+  For example, classification of 2 fruit attributes, crispy or not crispy and
+  sour or not sour, using features extracted from a set of images of fruit.
+  Each sample is an image of one fruit, labels for both binary attributes are
+  output for each sample and each attribute is labelled independently of the
+  other attribute.
 
   - valid representation :term:`multilabel` `y` is:
 
@@ -48,12 +50,12 @@ regression is also supported.
       that the sample belongs to multiple classes. Each column represents a class.
 
 
-- **Multioutput regression** predicts multiple outputs that are all continuous
-  variables. In other words, assigns each sample a set of target values.
+- **Multioutput regression**: predicts multiple numerical properties for each
+  sample. Each property is a continuous variable and the number of properties
+  to be predicted for each sample is greater or equal to 2.
 
-  *example:* based on an arbitrary set of features from fruit images, predicts a
-    set of :term:`contineous` variables such as: weight, sugar content,
-    calories, etc.
+  For example, prediction of weight, sugar content and number of calories using
+  features extracted from images of fruit. Each sample is one image of a fruit.
 
   - valid representation :term:`multilabel` `y` is:
 
@@ -62,27 +64,31 @@ regression is also supported.
 
 
 - **Multioutput-multiclass classification**
-  (also known as **multi-task classification**)
-  means that a single estimator has to handle several joint classification
-  tasks. This is both a generalization of the multi-label classification
-  task, which only considers binary classification, as well as a
-  generalization of the multi-class classification task.
-
-  *example:* The set of labels can be different for each output variable. For
-    instance, a sample could be assigned "pear" for an output variable that
-    takes possible values in a finite set of species such as "pear", "apple";
-    and "blue" or "green" for a second output variable that takes possible
-    values in a finite set of colors such as "green", "red", "blue", "yellow"...
+  (also known as **multitask classification**):
+  classification task which labels each sample with a set of **non-binary**
+  attributes. Both the number of attributes and the number of classes per
+  attribute is greater than 2. A single estimator thus handles several joint
+  classification tasks. This is both a generalization of the multi**label**
+  classification task, which only considers binary attributes, as well as a
+  generalization of the multi**class** classification task, where only one
+  attribute is considered.
+
+  For example, classification of the attributes "type of fruit" and "colour"
+  for a set of images of fruit. The attribute "type of fruit" has the possible
+  classes: "apple", "pear" and "orange". The attribute "colour" has the
+  possible classes: "green", "red", "yellow" and "orange". Each sample is an
+  image of a fruit, a label is output for both attributes and each label is
+  one of the possible classes of the corresponding attribute.
 
   - valid representation :term:`multilabel` `y` is:
 
     - dense matrix of shape ``(n_samples, n_classes)`` of floats. A column wise
       concatenation of 1d :term:`multiclass` variables.
 
-  - Note that any classifiers handling multi-output
-    multiclass or multi-task classification tasks,
-    support the multi-label classification task as a special case.
-    Multi-task classification is similar to the multi-output
+  - Note that any classifiers handling multioutput-multiclass
+   (also known as multitask classification) tasks,
+    support the multilabel classification task as a special case.
+    Multitask classification is similar to the multioutput
     classification task with different model formulations. For
     more information, see the relevant estimator documentation.
 
@@ -93,6 +99,27 @@ permit changing the way they handle more than two classes
 because this may have an effect on classifier performance
 (either in terms of generalization error or required computational resources).
 
+Summary
+-------
+
++-----------------+-------------+-------------+
+|                 | Number of   | Classes per | 
+|                 | attributes  | attribute   | 
++=================+=============+=============+
+| Multiclass      |  1          | >2          |
+| classification  |             |             |
++-----------------+-------------+-------------+
+| Multilabel      | >1          |  2          | 
+| classification  |             |             |
++-----------------+-------------+-------------+
+| Multioutput     | >1          | Continuous  |
+| regression      |             |             |
++-----------------+-------------+-------------+
+| Multioutput-    | >1          | >2          |
+| multiclass      |             |             |
+| classification  |             |             |
++-----------------+-------------+-------------+
+
 Below is a summary of the classifiers supported by scikit-learn
 grouped by strategy; you don't need the meta-estimators in this class
 if you're using one of these, unless you want custom multiclass behavior:

From 6405f116694e07650e2b95f97c0fdc5e0e303894 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Tue, 10 Sep 2019 19:20:27 +0200
Subject: [PATCH 07/25] add type column, clarify multiclass

---
 doc/modules/multiclass.rst | 44 +++++++++++++++++++-------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 97e0057d5b1c8..07291e3d79645 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -19,11 +19,12 @@ regression is also supported.
 
 - **Multiclass classification**: classification task which labels each
   sample as **one** of a number of classes, where the number of classes is
-  greater than 2. Each sample can only be labelled as one class. 
+  greater than 2. Each sample can only be labelled as one class.
 
   For example, classification of a set of images of fruit, where each image may
   either be of an orange, an apples, or a pear. Multiclass classification makes
-  the assumption that each sample is assigned to one and only one label.
+  the assumption that each sample is assigned to one and only one label - one
+  sample cannot for example be bother a pear and an an apple at the same time.
   
   - Valid :term:`multiclass` representations for
     :func:`~utils.multiclass.type_of_target` (`y`) are:
@@ -99,26 +100,25 @@ permit changing the way they handle more than two classes
 because this may have an effect on classifier performance
 (either in terms of generalization error or required computational resources).
 
-Summary
--------
-
-+-----------------+-------------+-------------+
-|                 | Number of   | Classes per | 
-|                 | attributes  | attribute   | 
-+=================+=============+=============+
-| Multiclass      |  1          | >2          |
-| classification  |             |             |
-+-----------------+-------------+-------------+
-| Multilabel      | >1          |  2          | 
-| classification  |             |             |
-+-----------------+-------------+-------------+
-| Multioutput     | >1          | Continuous  |
-| regression      |             |             |
-+-----------------+-------------+-------------+
-| Multioutput-    | >1          | >2          |
-| multiclass      |             |             |
-| classification  |             |             |
-+-----------------+-------------+-------------+
+**Summary**
+
++-----------------+-------------+-------------+------------------------------------------+
+|                 | Number of   | Classes per | Valid                                    |
+|                 | attributes  | attribute   | :func:`~utils.multiclass.type_of_target` |
++=================+=============+=============+==========================================+
+| Multiclass      |  1          | >2          | - 'multiclass'                           |
+| classification  |             |             | - sparse binary                          |
++-----------------+-------------+-------------+------------------------------------------+
+| Multilabel      | >1          |  2          | - 'multilabel-indicator'                 |
+| classification  |             |             | - dense or sparse binary                           |
++-----------------+-------------+-------------+------------------------------------------+
+| Multioutput     | >1          | Continuous  | - 'continuous-multioutput'               |
+| regression      |             |             |                                          |
++-----------------+-------------+-------------+------------------------------------------+
+| Multioutput-    | >1          | >2          | - 'multiclass-multioutput'               |
+| multiclass      |             |             |                                          |
+| classification  |             |             |                                          |
++-----------------+-------------+-------------+------------------------------------------+
 
 Below is a summary of the classifiers supported by scikit-learn
 grouped by strategy; you don't need the meta-estimators in this class

From 47c7b12f8c01f37608d99a422b40a8515c3fa46f Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Tue, 10 Sep 2019 19:22:37 +0200
Subject: [PATCH 08/25] fix format

---
 doc/modules/multiclass.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 07291e3d79645..f9ac1a194e039 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -87,7 +87,7 @@ regression is also supported.
       concatenation of 1d :term:`multiclass` variables.
 
   - Note that any classifiers handling multioutput-multiclass
-   (also known as multitask classification) tasks,
+    (also known as multitask classification) tasks,
     support the multilabel classification task as a special case.
     Multitask classification is similar to the multioutput
     classification task with different model formulations. For

From 316b4b157eb40985914fc44ae57bc17b3b738c51 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Tue, 10 Sep 2019 19:24:02 +0200
Subject: [PATCH 09/25] add clarification to table

---
 doc/modules/multiclass.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index f9ac1a194e039..e712d4705f9ff 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -109,7 +109,7 @@ because this may have an effect on classifier performance
 | Multiclass      |  1          | >2          | - 'multiclass'                           |
 | classification  |             |             | - sparse binary                          |
 +-----------------+-------------+-------------+------------------------------------------+
-| Multilabel      | >1          |  2          | - 'multilabel-indicator'                 |
+| Multilabel      | >1          |  2 (0 or 1) | - 'multilabel-indicator'                 |
 | classification  |             |             | - dense or sparse binary                           |
 +-----------------+-------------+-------------+------------------------------------------+
 | Multioutput     | >1          | Continuous  | - 'continuous-multioutput'               |

From beda4289f4e174d75ddca0e9ab2a52edea5efd7b Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Tue, 10 Sep 2019 19:27:16 +0200
Subject: [PATCH 10/25] clarify multioutput reg

---
 doc/modules/multiclass.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index e712d4705f9ff..8561f83215fad 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -56,7 +56,9 @@ regression is also supported.
   to be predicted for each sample is greater or equal to 2.
 
   For example, prediction of weight, sugar content and number of calories using
-  features extracted from images of fruit. Each sample is one image of a fruit.
+  features extracted from images of fruit. Each sample is one image of a fruit
+  and for each sample weight, sugar content and number of calories are all
+  output.
 
   - valid representation :term:`multilabel` `y` is:
 

From a5e008e872de83c058a46ff4fc0f8bc00cc1fd37 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Wed, 11 Sep 2019 11:26:28 +0200
Subject: [PATCH 11/25] fix rst table

---
 doc/modules/multiclass.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 8561f83215fad..39f2b9cd6f628 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -112,7 +112,7 @@ because this may have an effect on classifier performance
 | classification  |             |             | - sparse binary                          |
 +-----------------+-------------+-------------+------------------------------------------+
 | Multilabel      | >1          |  2 (0 or 1) | - 'multilabel-indicator'                 |
-| classification  |             |             | - dense or sparse binary                           |
+| classification  |             |             | - dense or sparse binary                 |
 +-----------------+-------------+-------------+------------------------------------------+
 | Multioutput     | >1          | Continuous  | - 'continuous-multioutput'               |
 | regression      |             |             |                                          |

From 6764b25a8a2873750f71ccfbaa713955cacf7f53 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Wed, 11 Sep 2019 11:32:33 +0200
Subject: [PATCH 12/25] clarify multiclass class

---
 doc/modules/multiclass.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 39f2b9cd6f628..67459b6061ebe 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -21,10 +21,12 @@ regression is also supported.
   sample as **one** of a number of classes, where the number of classes is
   greater than 2. Each sample can only be labelled as one class.
 
-  For example, classification of a set of images of fruit, where each image may
-  either be of an orange, an apples, or a pear. Multiclass classification makes
-  the assumption that each sample is assigned to one and only one label - one
-  sample cannot for example be bother a pear and an an apple at the same time.
+  For example, classification using features extracted from a set of images of
+  fruit, where each image may either be of an orange, an apples, or a pear.
+  Each image is one sample and is labelled as one of the 3 possible classes.
+  Multiclass classification makes the assumption that each sample is assigned
+  to one and only one label - one sample cannot, for example, be both a pear
+  and an apple at the same time.
   
   - Valid :term:`multiclass` representations for
     :func:`~utils.multiclass.type_of_target` (`y`) are:

From e8c22ac196c76779528554eff7b3568a34b2656c Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Wed, 11 Sep 2019 17:34:20 +0200
Subject: [PATCH 13/25] fix rst bolding

---
 doc/modules/multiclass.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 67459b6061ebe..fc0ceccc65dec 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -73,9 +73,9 @@ regression is also supported.
   classification task which labels each sample with a set of **non-binary**
   attributes. Both the number of attributes and the number of classes per
   attribute is greater than 2. A single estimator thus handles several joint
-  classification tasks. This is both a generalization of the multi**label**
+  classification tasks. This is both a generalization of the multi\ *label*
   classification task, which only considers binary attributes, as well as a
-  generalization of the multi**class** classification task, where only one
+  generalization of the multi\ *class* classification task, where only one
   attribute is considered.
 
   For example, classification of the attributes "type of fruit" and "colour"

From ef98a66ca2d0eb968faa3b177f613a1a168b1895 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Fri, 13 Sep 2019 13:26:02 +0200
Subject: [PATCH 14/25] trigger CI


From ebda0553c167ca9ec2bee6721ce2a93502673942 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Thu, 24 Oct 2019 13:27:18 +0200
Subject: [PATCH 15/25] address comments

---
 doc/modules/multiclass.rst | 90 ++++++++++++++++++++------------------
 1 file changed, 48 insertions(+), 42 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index fc0ceccc65dec..3f6d1ce208861 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -17,19 +17,18 @@ The :mod:`sklearn.multiclass` module implements *meta-estimators* to solve
 by decomposing such problems into binary classification problems. ``multioutput``
 regression is also supported.
 
-- **Multiclass classification**: classification task which labels each
-  sample as **one** of a number of classes, where the number of classes is
-  greater than 2. Each sample can only be labelled as one class.
+- **Multiclass classification**: classification task with more than two classes.
+  Each sample can only be labelled as one class.
 
   For example, classification using features extracted from a set of images of
-  fruit, where each image may either be of an orange, an apples, or a pear.
+  fruit, where each image may either be of an orange, an apple, or a pear.
   Each image is one sample and is labelled as one of the 3 possible classes.
   Multiclass classification makes the assumption that each sample is assigned
   to one and only one label - one sample cannot, for example, be both a pear
-  and an apple at the same time.
+  and an apple.
   
-  - Valid :term:`multiclass` representations for
-    :func:`~utils.multiclass.type_of_target` (`y`) are:
+  Valid :term:`multiclass` representations for
+  :func:`~utils.multiclass.type_of_target` (`y`) are:
 
     - 1d or column vector containing more than two discrete values.
     - sparse :term:`binary` matrix of shape ``(n_samples, n_classes)`` with a
@@ -37,33 +36,40 @@ regression is also supported.
 
 
 - **Multilabel classification**: classification task which labels each sample
-  with a set of binary attributes (either True or False) independently of
-  one another. The number of binary attributes is greater or equal to 2.
-
-  For example, classification of 2 fruit attributes, crispy or not crispy and
-  sour or not sour, using features extracted from a set of images of fruit.
-  Each sample is an image of one fruit, labels for both binary attributes are
-  output for each sample and each attribute is labelled independently of the
-  other attribute.
-
-  - valid representation :term:`multilabel` `y` is:
+  with a **set** of target labels. This can be thought of as predicting
+  properties of a sample that are not mutually exclusive. Formally, a value of
+  0 or 1 is assigned to each label, for every sample. It is thus comparable
+  to running 'n' binary classification tasks, for example with
+  :class:`sklearn.multiclass.OneVsRestClassifier`. Multilabel classification
+  differs in that only one classification model is trained whereas 'n'
+  classification models would be trained using the 'n' binary classification
+  tasks approach.
+
+  For example, prediction of taste using features extracted from a set of
+  images of fruit, where the possible taste labels are 'sour', 'sweet',
+  'juicy' and 'bitter'. Each image is one sample and is labelled with a
+  set of target labels, where the set can be any number of labels, ranging from
+  all 4 labels to none of the labels.
+
+  Valid representation :term:`multilabel` `y` is:
 
     - either dense (or sparse) :term:`binary` matrix of shape
       ``(n_samples, n_classes)`` with multiple active elements per row to denote
-      that the sample belongs to multiple classes. Each column represents a class.
+      that the sample belongs to multiple classes. Each column represents a 
+      class.
 
 
 - **Multioutput regression**: predicts multiple numerical properties for each
-  sample. Each property is a continuous variable and the number of properties
+  sample. Each property is a numerical variable and the number of properties
   to be predicted for each sample is greater or equal to 2.
 
-  For example, prediction of weight, sugar content and number of calories using
-  features extracted from images of fruit. Each sample is one image of a fruit
-  and for each sample weight, sugar content and number of calories are all
-  output.
-
-  - valid representation :term:`multilabel` `y` is:
+  For example, prediction of the surface area and volume fruit, using features
+  extracted from images of fruit. Each sample is one image of a piece of fruit
+  and for each sample a numerical value for surface area and volume are
+  predicted.
 
+  Valid representation :term:`multilabel` `y` is:
+  
     - dense matrix of shape ``(n_samples, n_classes)`` of floats. A column wise
       concatenation of :term:`continuous` variables.
 
@@ -71,21 +77,21 @@ regression is also supported.
 - **Multioutput-multiclass classification**
   (also known as **multitask classification**):
   classification task which labels each sample with a set of **non-binary**
-  attributes. Both the number of attributes and the number of classes per
-  attribute is greater than 2. A single estimator thus handles several joint
-  classification tasks. This is both a generalization of the multi\ *label*
-  classification task, which only considers binary attributes, as well as a
-  generalization of the multi\ *class* classification task, where only one
-  attribute is considered.
-
-  For example, classification of the attributes "type of fruit" and "colour"
-  for a set of images of fruit. The attribute "type of fruit" has the possible
-  classes: "apple", "pear" and "orange". The attribute "colour" has the
+  properties. Both the number of properties and the number of
+  classes per property is greater than 2. A single estimator thus
+  handles several joint classification tasks. This is both a generalization of
+  the multi\ *label* classification task, which only considers binary
+  attributes, as well as a generalization of the multi\ *class* classification
+  task, where only one property is considered.
+
+  For example, classification of the properties "type of fruit" and "colour"
+  for a set of images of fruit. The property "type of fruit" has the possible
+  classes: "apple", "pear" and "orange". The property "colour" has the
   possible classes: "green", "red", "yellow" and "orange". Each sample is an
-  image of a fruit, a label is output for both attributes and each label is
-  one of the possible classes of the corresponding attribute.
+  image of a fruit, a label is output for both properties and each label is
+  one of the possible classes of the corresponding property.
 
-  - valid representation :term:`multilabel` `y` is:
+  Valid representation :term:`multilabel` `y` is:
 
     - dense matrix of shape ``(n_samples, n_classes)`` of floats. A column wise
       concatenation of 1d :term:`multiclass` variables.
@@ -107,14 +113,14 @@ because this may have an effect on classifier performance
 **Summary**
 
 +-----------------+-------------+-------------+------------------------------------------+
-|                 | Number of   | Classes per | Valid                                    |
-|                 | attributes  | attribute   | :func:`~utils.multiclass.type_of_target` |
+|                 | Number of   | Target      | Valid                                    |
+|                 | targets     | cardinality | :func:`~utils.multiclass.type_of_target` |
 +=================+=============+=============+==========================================+
 | Multiclass      |  1          | >2          | - 'multiclass'                           |
-| classification  |             |             | - sparse binary                          |
+| classification  |             |             |                                          |
 +-----------------+-------------+-------------+------------------------------------------+
 | Multilabel      | >1          |  2 (0 or 1) | - 'multilabel-indicator'                 |
-| classification  |             |             | - dense or sparse binary                 |
+| classification  |             |             |                                          |
 +-----------------+-------------+-------------+------------------------------------------+
 | Multioutput     | >1          | Continuous  | - 'continuous-multioutput'               |
 | regression      |             |             |                                          |

From 9e56dba57e9bbef1cdfe0df310d086988c6016e6 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Thu, 24 Oct 2019 13:36:32 +0200
Subject: [PATCH 16/25] add multilabel example

---
 doc/modules/multiclass.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 3f6d1ce208861..55a237ca49cbc 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -49,7 +49,10 @@ regression is also supported.
   images of fruit, where the possible taste labels are 'sour', 'sweet',
   'juicy' and 'bitter'. Each image is one sample and is labelled with a
   set of target labels, where the set can be any number of labels, ranging from
-  all 4 labels to none of the labels.
+  all 4 labels to none of the labels. A good 'real-world' example is predicting
+  the topics relevant to a text document or video. The document or video may be
+  about 'religion', 'politics', 'finance' or 'education', or a subset of these
+  topic labels or even all of these topic labels.
 
   Valid representation :term:`multilabel` `y` is:
 

From be612b1f9cb846c7efe8a40b37f3e4447cf83a3c Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Wed, 6 Nov 2019 16:49:53 +0100
Subject: [PATCH 17/25] address comments

---
 doc/modules/multiclass.rst | 55 ++++++++++++++++++--------------------
 1 file changed, 26 insertions(+), 29 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 55a237ca49cbc..f82e6877dc820 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -39,11 +39,11 @@ regression is also supported.
   with a **set** of target labels. This can be thought of as predicting
   properties of a sample that are not mutually exclusive. Formally, a value of
   0 or 1 is assigned to each label, for every sample. It is thus comparable
-  to running 'n' binary classification tasks, for example with
+  to running 'n_labels' binary classification tasks, for example with
   :class:`sklearn.multiclass.OneVsRestClassifier`. Multilabel classification
-  differs in that only one classification model is trained whereas 'n'
-  classification models would be trained using the 'n' binary classification
-  tasks approach.
+  differs in that only one classification model is trained whereas 'n_labels'
+  classification models would be trained using the 'n_labels' binary
+  classification tasks approach.
 
   For example, prediction of taste using features extracted from a set of
   images of fruit, where the possible taste labels are 'sour', 'sweet',
@@ -54,27 +54,26 @@ regression is also supported.
   about 'religion', 'politics', 'finance' or 'education', or a subset of these
   topic labels or even all of these topic labels.
 
-  Valid representation :term:`multilabel` `y` is:
-
-    - either dense (or sparse) :term:`binary` matrix of shape
-      ``(n_samples, n_classes)`` with multiple active elements per row to denote
-      that the sample belongs to multiple classes. Each column represents a 
-      class.
+  Valid representation :term:`multilabel` `y` is either dense (or sparse)
+  :term:`binary` matrix of shape ``(n_samples, n_classes)`` with multiple
+  active elements per row to denote that the sample belongs to multiple classes.
+  Each column represents a class.
 
 
 - **Multioutput regression**: predicts multiple numerical properties for each
   sample. Each property is a numerical variable and the number of properties
-  to be predicted for each sample is greater or equal to 2.
+  to be predicted for each sample is greater or equal to 2. Some estimators
+  that support multioutput regression are faster than just running ``n_output``
+  estimators.
 
-  For example, prediction of the surface area and volume fruit, using features
-  extracted from images of fruit. Each sample is one image of a piece of fruit
-  and for each sample a numerical value for surface area and volume are
-  predicted.
+  For example, prediction of both wind speed and wind direction, in degrees,
+  using data obtained at a certain location. Each sample would be data
+  obtained at one location and both wind speed and directtion would be
+  output for each sample.
 
-  Valid representation :term:`multilabel` `y` is:
-  
-    - dense matrix of shape ``(n_samples, n_classes)`` of floats. A column wise
-      concatenation of :term:`continuous` variables.
+  Valid representation :term:`multilabel` `y` is dense matrix of shape
+  ``(n_samples, n_classes)`` of floats. A column wise concatenation of
+  :term:`continuous` variables.
 
 
 - **Multioutput-multiclass classification**
@@ -94,17 +93,15 @@ regression is also supported.
   image of a fruit, a label is output for both properties and each label is
   one of the possible classes of the corresponding property.
 
-  Valid representation :term:`multilabel` `y` is:
-
-    - dense matrix of shape ``(n_samples, n_classes)`` of floats. A column wise
-      concatenation of 1d :term:`multiclass` variables.
+  Valid representation :term:`multilabel` `y` is dense matrix of shape
+  ``(n_samples, n_classes)`` of floats. A column wise concatenation of 1d
+  :term:`multiclass` variables.
 
-  - Note that any classifiers handling multioutput-multiclass
-    (also known as multitask classification) tasks,
-    support the multilabel classification task as a special case.
-    Multitask classification is similar to the multioutput
-    classification task with different model formulations. For
-    more information, see the relevant estimator documentation.
+  Note that any classifiers handling multioutput-multiclass (also known as
+  multitask classification) tasks, support the multilabel classification task
+  as a special case. Multitask classification is similar to the multioutput
+  classification task with different model formulations. For more information,
+  see the relevant estimator documentation.
 
 
 All scikit-learn classifiers are capable of multiclass classification,

From 9898fedd5b902667da88e90cadcd4ad3b44d772d Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Thu, 7 Nov 2019 11:43:33 +0100
Subject: [PATCH 18/25] address jnothman's comments

---
 doc/modules/multiclass.rst | 49 ++++++++++++++++++--------------------
 1 file changed, 23 insertions(+), 26 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index f82e6877dc820..0b6ab8bcf24c5 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -35,34 +35,31 @@ regression is also supported.
       single element per row, where each column represents one class.
 
 
-- **Multilabel classification**: classification task which labels each sample
-  with a **set** of target labels. This can be thought of as predicting
-  properties of a sample that are not mutually exclusive. Formally, a value of
-  0 or 1 is assigned to each label, for every sample. It is thus comparable
-  to running 'n_labels' binary classification tasks, for example with
-  :class:`sklearn.multiclass.OneVsRestClassifier`. Multilabel classification
-  differs in that only one classification model is trained whereas 'n_labels'
-  classification models would be trained using the 'n_labels' binary
-  classification tasks approach.
-
-  For example, prediction of taste using features extracted from a set of
-  images of fruit, where the possible taste labels are 'sour', 'sweet',
-  'juicy' and 'bitter'. Each image is one sample and is labelled with a
-  set of target labels, where the set can be any number of labels, ranging from
-  all 4 labels to none of the labels. A good 'real-world' example is predicting
-  the topics relevant to a text document or video. The document or video may be
-  about 'religion', 'politics', 'finance' or 'education', or a subset of these
-  topic labels or even all of these topic labels.
-
-  Valid representation :term:`multilabel` `y` is either dense (or sparse)
-  :term:`binary` matrix of shape ``(n_samples, n_classes)`` with multiple
-  active elements per row to denote that the sample belongs to multiple classes.
-  Each column represents a class.
+- **Multilabel classification**: classification task labelling each sample with
+  ``x`` labels from ``n_classes`` possible classes, where ``x`` can be 0 to
+  ``n_classes`` inclusive. This can be thought of as predicting properties of a
+  sample that are not mutually exclusive. Formally, a binary output is assigned
+  to each class, for every sample. Positive classes are indicated with 1 and
+  negative classes with 0 or -1. It is thus comparable to running ``n_classes``
+  binary classification tasks, for example with
+  :class:`sklearn.multioutput.MultiOutputClassifier`. This approach treats
+  each label independently whereas multilabel classifiers *may* treat the
+  multiple classes simultaneously, accounting for correlated behaviour amoung
+  them.
+
+  For example, prediction of the topics relevant to a text document or video.
+  The document or video may be about one of 'religion', 'politics', 'finance'
+  or 'education', several of the topic classes or all of the topic classes.
+
+  Valid representation of :term:`multilabel` `y` is either dense (or sparse)
+  :term:`binary` matrix of shape ``(n_samples, n_classes)``. Each column
+  represents a class. The ``1``'s in each row denote the positive classes a
+  sample has been labelled with. 
 
 
 - **Multioutput regression**: predicts multiple numerical properties for each
   sample. Each property is a numerical variable and the number of properties
-  to be predicted for each sample is greater or equal to 2. Some estimators
+  to be predicted for each sample is greater than or equal to 2. Some estimators
   that support multioutput regression are faster than just running ``n_output``
   estimators.
 
@@ -71,7 +68,7 @@ regression is also supported.
   obtained at one location and both wind speed and directtion would be
   output for each sample.
 
-  Valid representation :term:`multilabel` `y` is dense matrix of shape
+  Valid representation of :term:`multilabel` `y` is dense matrix of shape
   ``(n_samples, n_classes)`` of floats. A column wise concatenation of
   :term:`continuous` variables.
 
@@ -93,7 +90,7 @@ regression is also supported.
   image of a fruit, a label is output for both properties and each label is
   one of the possible classes of the corresponding property.
 
-  Valid representation :term:`multilabel` `y` is dense matrix of shape
+  Valid representation of :term:`multilabel` `y` is dense matrix of shape
   ``(n_samples, n_classes)`` of floats. A column wise concatenation of 1d
   :term:`multiclass` variables.
 

From 3c97b20e9837b853067df257c7a6b2c1caec8d02 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Thu, 7 Nov 2019 16:07:56 +0100
Subject: [PATCH 19/25] add examples for each type

---
 doc/modules/multiclass.rst | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 0b6ab8bcf24c5..938d3bf298509 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -25,8 +25,12 @@ regression is also supported.
   Each image is one sample and is labelled as one of the 3 possible classes.
   Multiclass classification makes the assumption that each sample is assigned
   to one and only one label - one sample cannot, for example, be both a pear
-  and an apple.
-  
+  and an apple. An example of ``y`` for 3 samples:
+
+    >>> y = np.array(['apple', 'pear', 'apple', 'orange'])                               
+    >>> print(y)                                                                         
+    ['apple' 'pear' 'apple' 'orange']
+
   Valid :term:`multiclass` representations for
   :func:`~utils.multiclass.type_of_target` (`y`) are:
 
@@ -34,7 +38,6 @@ regression is also supported.
     - sparse :term:`binary` matrix of shape ``(n_samples, n_classes)`` with a
       single element per row, where each column represents one class.
 
-
 - **Multilabel classification**: classification task labelling each sample with
   ``x`` labels from ``n_classes`` possible classes, where ``x`` can be 0 to
   ``n_classes`` inclusive. This can be thought of as predicting properties of a
@@ -50,6 +53,13 @@ regression is also supported.
   For example, prediction of the topics relevant to a text document or video.
   The document or video may be about one of 'religion', 'politics', 'finance'
   or 'education', several of the topic classes or all of the topic classes.
+  An example of ``y`` for 3 samples:
+
+    >>> y = np.array([[1,0,0,1], [0,0,1,1], [0,0,0,0]])                                  
+    >>> print(y)                                                                         
+    [[1 0 0 1]
+    [0 0 1 1]
+    [0 0 0 0]]
 
   Valid representation of :term:`multilabel` `y` is either dense (or sparse)
   :term:`binary` matrix of shape ``(n_samples, n_classes)``. Each column
@@ -66,7 +76,13 @@ regression is also supported.
   For example, prediction of both wind speed and wind direction, in degrees,
   using data obtained at a certain location. Each sample would be data
   obtained at one location and both wind speed and directtion would be
-  output for each sample.
+  output for each sample. An example of ``y`` for 3 samples:
+
+    >>> y = np.array([[31.4, 94], [40.5, 109], [25.0, 30]])                              
+    >>> print(y)                                                                         
+    [[ 31.4  94. ]
+    [ 40.5 109. ]
+    [ 25.   30. ]]
 
   Valid representation of :term:`multilabel` `y` is dense matrix of shape
   ``(n_samples, n_classes)`` of floats. A column wise concatenation of
@@ -88,7 +104,14 @@ regression is also supported.
   classes: "apple", "pear" and "orange". The property "colour" has the
   possible classes: "green", "red", "yellow" and "orange". Each sample is an
   image of a fruit, a label is output for both properties and each label is
-  one of the possible classes of the corresponding property.
+  one of the possible classes of the corresponding property. An example of
+  ``y`` for 3 samples:
+
+    >>> y = np.array([['apple', 'green'], ['orange', 'orange'], ['pear', 'green']])      
+    >>> print(y)                                                                         
+    [['apple' 'green']
+    ['orange' 'orange']
+    ['pear' 'green']]
 
   Valid representation of :term:`multilabel` `y` is dense matrix of shape
   ``(n_samples, n_classes)`` of floats. A column wise concatenation of 1d

From 90132f54e8255566b70502336e471fa14583c183 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Thu, 7 Nov 2019 16:28:09 +0100
Subject: [PATCH 20/25] formatting, import numpy

---
 doc/modules/multiclass.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 938d3bf298509..24b55bbc840c5 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -27,6 +27,7 @@ regression is also supported.
   to one and only one label - one sample cannot, for example, be both a pear
   and an apple. An example of ``y`` for 3 samples:
 
+    >>> import numpy as np
     >>> y = np.array(['apple', 'pear', 'apple', 'orange'])                               
     >>> print(y)                                                                         
     ['apple' 'pear' 'apple' 'orange']
@@ -38,6 +39,7 @@ regression is also supported.
     - sparse :term:`binary` matrix of shape ``(n_samples, n_classes)`` with a
       single element per row, where each column represents one class.
 
+
 - **Multilabel classification**: classification task labelling each sample with
   ``x`` labels from ``n_classes`` possible classes, where ``x`` can be 0 to
   ``n_classes`` inclusive. This can be thought of as predicting properties of a

From 35c307e7981a7c411a2594734a11020d9bcf3b77 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Thu, 7 Nov 2019 16:40:04 +0100
Subject: [PATCH 21/25] amend to be 3 samples

---
 doc/modules/multiclass.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 24b55bbc840c5..cea9ca53f4af5 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -28,7 +28,7 @@ regression is also supported.
   and an apple. An example of ``y`` for 3 samples:
 
     >>> import numpy as np
-    >>> y = np.array(['apple', 'pear', 'apple', 'orange'])                               
+    >>> y = np.array(['apple', 'pear', 'apple'])                               
     >>> print(y)                                                                         
     ['apple' 'pear' 'apple' 'orange']
 

From 38d3bf69f011df0b6e1cdce5eab46b14c0635c06 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Thu, 7 Nov 2019 17:20:58 +0100
Subject: [PATCH 22/25] amend output to 3 samples

---
 doc/modules/multiclass.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index cea9ca53f4af5..5d06f2254c05f 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -30,7 +30,7 @@ regression is also supported.
     >>> import numpy as np
     >>> y = np.array(['apple', 'pear', 'apple'])                               
     >>> print(y)                                                                         
-    ['apple' 'pear' 'apple' 'orange']
+    ['apple' 'pear' 'apple']
 
   Valid :term:`multiclass` representations for
   :func:`~utils.multiclass.type_of_target` (`y`) are:

From d97ddbe0975e2543e86dc729ecf9f8fd481d037a Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Thu, 7 Nov 2019 20:52:34 +0100
Subject: [PATCH 23/25] add sparse examples

---
 doc/modules/multiclass.rst | 69 +++++++++++++++++++++++++-------------
 1 file changed, 45 insertions(+), 24 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 5d06f2254c05f..2c807e172ce0f 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -25,19 +25,32 @@ regression is also supported.
   Each image is one sample and is labelled as one of the 3 possible classes.
   Multiclass classification makes the assumption that each sample is assigned
   to one and only one label - one sample cannot, for example, be both a pear
-  and an apple. An example of ``y`` for 3 samples:
-
-    >>> import numpy as np
-    >>> y = np.array(['apple', 'pear', 'apple'])                               
-    >>> print(y)                                                                         
-    ['apple' 'pear' 'apple']
+  and an apple.
 
   Valid :term:`multiclass` representations for
   :func:`~utils.multiclass.type_of_target` (`y`) are:
 
-    - 1d or column vector containing more than two discrete values.
+    - 1d or column vector containing more than two discrete values. An
+      example of a vector ``y`` for 3 samples:
+
+        >>> import numpy as np
+        >>> y = np.array(['apple', 'pear', 'apple'])                               
+        >>> print(y)                                                                         
+        ['apple' 'pear' 'apple']
+
     - sparse :term:`binary` matrix of shape ``(n_samples, n_classes)`` with a
-      single element per row, where each column represents one class.
+      single element per row, where each column represents one class. An
+      example of a sparse :term:`binary` matrix ``y`` for 3 samples, where
+      the columns, in order, are orange, apple and pear:
+
+        >>> from scipy import y_sparse
+        >>> row_ind = np.array([0,1,2])                                                      
+        >>> col_ind = np.array([1,2,1])  
+        >>> y_sparse = sparse.csr_matrix((np.ones(3), (row_ind, col_ind)))                   
+        >>> print(y_sparse)                                                                  
+          (0, 1)	1.0
+          (1, 2)	1.0
+          (2, 1)	1.0
 
 
 - **Multilabel classification**: classification task labelling each sample with
@@ -55,7 +68,12 @@ regression is also supported.
   For example, prediction of the topics relevant to a text document or video.
   The document or video may be about one of 'religion', 'politics', 'finance'
   or 'education', several of the topic classes or all of the topic classes.
-  An example of ``y`` for 3 samples:
+
+  Valid representation of :term:`multilabel` `y` is either dense (or sparse)
+  :term:`binary` matrix of shape ``(n_samples, n_classes)``. Each column
+  represents a class. The ``1``'s in each row denote the positive classes a
+  sample has been labelled with. An example of a dense matrix ``y`` for 3
+  samples:
 
     >>> y = np.array([[1,0,0,1], [0,0,1,1], [0,0,0,0]])                                  
     >>> print(y)                                                                         
@@ -63,10 +81,14 @@ regression is also supported.
     [0 0 1 1]
     [0 0 0 0]]
 
-  Valid representation of :term:`multilabel` `y` is either dense (or sparse)
-  :term:`binary` matrix of shape ``(n_samples, n_classes)``. Each column
-  represents a class. The ``1``'s in each row denote the positive classes a
-  sample has been labelled with. 
+  An example of the same ``y`` in sparse matrix form:
+ 
+    >>> y_sparse = sparse.csr_matrix(y)                                                  
+    >>> print(y_sparse)                                                                  
+      (0, 0)	1
+      (0, 3)	1
+      (1, 2)	1
+      (1, 3)	1
 
 
 - **Multioutput regression**: predicts multiple numerical properties for each
@@ -78,7 +100,11 @@ regression is also supported.
   For example, prediction of both wind speed and wind direction, in degrees,
   using data obtained at a certain location. Each sample would be data
   obtained at one location and both wind speed and directtion would be
-  output for each sample. An example of ``y`` for 3 samples:
+  output for each sample.
+
+  Valid representation of :term:`multilabel` `y` is dense matrix of shape
+  ``(n_samples, n_classes)`` of floats. A column wise concatenation of
+  :term:`continuous` variables. An example of ``y`` for 3 samples:
 
     >>> y = np.array([[31.4, 94], [40.5, 109], [25.0, 30]])                              
     >>> print(y)                                                                         
@@ -86,10 +112,6 @@ regression is also supported.
     [ 40.5 109. ]
     [ 25.   30. ]]
 
-  Valid representation of :term:`multilabel` `y` is dense matrix of shape
-  ``(n_samples, n_classes)`` of floats. A column wise concatenation of
-  :term:`continuous` variables.
-
 
 - **Multioutput-multiclass classification**
   (also known as **multitask classification**):
@@ -106,8 +128,11 @@ regression is also supported.
   classes: "apple", "pear" and "orange". The property "colour" has the
   possible classes: "green", "red", "yellow" and "orange". Each sample is an
   image of a fruit, a label is output for both properties and each label is
-  one of the possible classes of the corresponding property. An example of
-  ``y`` for 3 samples:
+  one of the possible classes of the corresponding property.
+
+  Valid representation of :term:`multilabel` `y` is dense matrix of shape
+  ``(n_samples, n_classes)`` of floats. A column wise concatenation of 1d
+  :term:`multiclass` variables. An example of ``y`` for 3 samples:
 
     >>> y = np.array([['apple', 'green'], ['orange', 'orange'], ['pear', 'green']])      
     >>> print(y)                                                                         
@@ -115,10 +140,6 @@ regression is also supported.
     ['orange' 'orange']
     ['pear' 'green']]
 
-  Valid representation of :term:`multilabel` `y` is dense matrix of shape
-  ``(n_samples, n_classes)`` of floats. A column wise concatenation of 1d
-  :term:`multiclass` variables.
-
   Note that any classifiers handling multioutput-multiclass (also known as
   multitask classification) tasks, support the multilabel classification task
   as a special case. Multitask classification is similar to the multioutput

From 46a74d179a1ef836fd709447b74bfe1d23c5c1de Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Fri, 8 Nov 2019 09:56:18 +0100
Subject: [PATCH 24/25] name import correctly

---
 doc/modules/multiclass.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index 2c807e172ce0f..c058018571928 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -43,7 +43,7 @@ regression is also supported.
       example of a sparse :term:`binary` matrix ``y`` for 3 samples, where
       the columns, in order, are orange, apple and pear:
 
-        >>> from scipy import y_sparse
+        >>> from scipy import sparse
         >>> row_ind = np.array([0,1,2])                                                      
         >>> col_ind = np.array([1,2,1])  
         >>> y_sparse = sparse.csr_matrix((np.ones(3), (row_ind, col_ind)))                   

From ec95ceb894b328c8dd5fb1d2bb03f60a0effd069 Mon Sep 17 00:00:00 2001
From: Lucy Liu <jliu176@gmail.com>
Date: Tue, 19 Nov 2019 18:16:57 +0100
Subject: [PATCH 25/25] space formating

---
 doc/modules/multiclass.rst | 42 +++++++++++++++++++-------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/doc/modules/multiclass.rst b/doc/modules/multiclass.rst
index c058018571928..5613fc2334e73 100644
--- a/doc/modules/multiclass.rst
+++ b/doc/modules/multiclass.rst
@@ -34,8 +34,8 @@ regression is also supported.
       example of a vector ``y`` for 3 samples:
 
         >>> import numpy as np
-        >>> y = np.array(['apple', 'pear', 'apple'])                               
-        >>> print(y)                                                                         
+        >>> y = np.array(['apple', 'pear', 'apple'])
+        >>> print(y)
         ['apple' 'pear' 'apple']
 
     - sparse :term:`binary` matrix of shape ``(n_samples, n_classes)`` with a
@@ -44,10 +44,10 @@ regression is also supported.
       the columns, in order, are orange, apple and pear:
 
         >>> from scipy import sparse
-        >>> row_ind = np.array([0,1,2])                                                      
-        >>> col_ind = np.array([1,2,1])  
-        >>> y_sparse = sparse.csr_matrix((np.ones(3), (row_ind, col_ind)))                   
-        >>> print(y_sparse)                                                                  
+        >>> row_ind = np.array([0, 1, 2])
+        >>> col_ind = np.array([1, 2, 1])
+        >>> y_sparse = sparse.csr_matrix((np.ones(3), (row_ind, col_ind)))
+        >>> print(y_sparse)
           (0, 1)	1.0
           (1, 2)	1.0
           (2, 1)	1.0
@@ -75,16 +75,16 @@ regression is also supported.
   sample has been labelled with. An example of a dense matrix ``y`` for 3
   samples:
 
-    >>> y = np.array([[1,0,0,1], [0,0,1,1], [0,0,0,0]])                                  
-    >>> print(y)                                                                         
+    >>> y = np.array([[1, 0, 0, 1], [0, 0, 1, 1], [0, 0, 0, 0]])
+    >>> print(y)
     [[1 0 0 1]
-    [0 0 1 1]
-    [0 0 0 0]]
+     [0 0 1 1]
+     [0 0 0 0]]
 
   An example of the same ``y`` in sparse matrix form:
- 
-    >>> y_sparse = sparse.csr_matrix(y)                                                  
-    >>> print(y_sparse)                                                                  
+
+    >>> y_sparse = sparse.csr_matrix(y)
+    >>> print(y_sparse)
       (0, 0)	1
       (0, 3)	1
       (1, 2)	1
@@ -106,11 +106,11 @@ regression is also supported.
   ``(n_samples, n_classes)`` of floats. A column wise concatenation of
   :term:`continuous` variables. An example of ``y`` for 3 samples:
 
-    >>> y = np.array([[31.4, 94], [40.5, 109], [25.0, 30]])                              
-    >>> print(y)                                                                         
+    >>> y = np.array([[31.4, 94], [40.5, 109], [25.0, 30]])
+    >>> print(y)
     [[ 31.4  94. ]
-    [ 40.5 109. ]
-    [ 25.   30. ]]
+     [ 40.5 109. ]
+     [ 25.   30. ]]
 
 
 - **Multioutput-multiclass classification**
@@ -134,11 +134,11 @@ regression is also supported.
   ``(n_samples, n_classes)`` of floats. A column wise concatenation of 1d
   :term:`multiclass` variables. An example of ``y`` for 3 samples:
 
-    >>> y = np.array([['apple', 'green'], ['orange', 'orange'], ['pear', 'green']])      
-    >>> print(y)                                                                         
+    >>> y = np.array([['apple', 'green'], ['orange', 'orange'], ['pear', 'green']])
+    >>> print(y)
     [['apple' 'green']
-    ['orange' 'orange']
-    ['pear' 'green']]
+     ['orange' 'orange']
+     ['pear' 'green']]
 
   Note that any classifiers handling multioutput-multiclass (also known as
   multitask classification) tasks, support the multilabel classification task