DOC put the narrative documentation of roc_curve and roc_auc_score in one place

doc/modules/model_evaluation.rst

@@ -268,27 +268,6 @@ and with a list of labels format:
     for an example of accuracy score usage using permutations of
     the dataset.
 
-Area under the ROC curve
-.........................
-
-The :func:`roc_auc_score` function computes the area under the receiver
-operating characteristic (ROC) curve.
-
-This function requires the true binary value and the target scores, which can
-either be probability estimates of the positive class, confidence values, or
-binary decisions.
-
-  >>> import numpy as np
-  >>> from sklearn.metrics import roc_auc_score
-  >>> y_true = np.array([0, 0, 1, 1])
-  >>> y_scores = np.array([0.1, 0.4, 0.35, 0.8])
-  >>> roc_auc_score(y_true, y_scores)
-  0.75
-
-For more information see the
-`Wikipedia article on AUC
-<http://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_curve>`_
-and the :ref:`roc_metrics` section.
 
 .. _average_precision_metrics:
 
@@ -713,7 +692,7 @@ with a svm classifier::
 
 
 Log loss
---------
+........
 The log loss, also called logistic regression loss or cross-entropy loss,
 is a loss function defined on probability estimates.
 It is commonly used in (multinomial) logistic regression and neural networks,
@@ -795,7 +774,7 @@ function:
 .. _roc_metrics:
 
 Receiver operating characteristic (ROC)
-........................................
+.......................................
 
 The function :func:`roc_curve` computes the `receiver operating characteristic
 curve, or ROC curve (quoting
@@ -809,6 +788,9 @@ Wikipedia) <http://en.wikipedia.org/wiki/Receiver_operating_characteristic>`_:
   positive rate), at various threshold settings. TPR is also known as
   sensitivity, and FPR is one minus the specificity or true negative rate."
 
+This function requires the true binary
+value and the target scores, which can either be probability estimates of the
+positive class, confidence values, or binary decisions.
 Here a small example of how to use the :func:`roc_curve` function::
 
     >>> import numpy as np
@@ -823,6 +805,19 @@ Here a small example of how to use the :func:`roc_curve` function::
     >>> thresholds
     array([ 0.8 ,  0.4 ,  0.35,  0.1 ])
 
+The :func:`roc_auc_score` function computes the area under the receiver
+operating characteristic (ROC) curve, which is also denoted by
+AUC or AUROC.  By computing the
+area under the roc curve, the curve information is summarized in one number.
+For more information see the `Wikipedia article on AUC
+<http://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_curve>`_.
+
+  >>> import numpy as np
+  >>> from sklearn.metrics import roc_auc_score
+  >>> y_true = np.array([0, 0, 1, 1])
+  >>> y_scores = np.array([0.1, 0.4, 0.35, 0.8])
+  >>> roc_auc_score(y_true, y_scores)
+  0.75
 
 The following figure shows an example of such ROC curve.