Update paddle/metrics (#2614) (#2617)

* Update paddle/metrics

* Fix format

* Update Metric format

doc/paddle/api/paddle/metric/Accuracy_cn.rst

-.. _cn_api_fluid_metrics_Accuracy:
-
-Accuracy
--------------------------------
-.. py:class:: paddle.fluid.metrics.Accuracy(name=None)
-
-
-
-
-该接口用来计算多个mini-batch的平均准确率。Accuracy对象有两个状态value和weight。Accuracy的定义参照 https://en.wikipedia.org/wiki/Accuracy_and_precision 。
-
-参数:
-    - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
-
-返回：初始化后的 ``Accuracy`` 对象
-
-返回类型：Accuracy
-
-**代码示例**
-
-.. code-block:: python
-
-        import paddle.fluid as fluid
-        # 假设有batch_size = 128
-        batch_size=128
-        accuracy_manager = fluid.metrics.Accuracy()
-        # 假设第一个batch的准确率为0.9
-        batch1_acc = 0.9
-        accuracy_manager.update(value = batch1_acc, weight = batch_size)
-        print("expect accuracy: %.2f, get accuracy: %.2f" % (batch1_acc, accuracy_manager.eval()))
-        # 假设第二个batch的准确率为0.8
-        batch2_acc = 0.8
-        accuracy_manager.update(value = batch2_acc, weight = batch_size)
-        #batch1和batch2的联合准确率为(batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2
-        print("expect accuracy: %.2f, get accuracy: %.2f" % ((batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2, accuracy_manager.eval()))
-        #重置accuracy_manager
-        accuracy_manager.reset()
-        #假设第三个batch的准确率为0.8
-        batch3_acc = 0.8
-        accuracy_manager.update(value = batch3_acc, weight = batch_size)
-        print("expect accuracy: %.2f, get accuracy: %.2f" % (batch3_acc, accuracy_manager.eval()))
-
-.. py:method:: update(value, weight)
-
-该函数使用输入的(value, weight)来累计更新Accuracy对象的对应状态，更新方式如下：
-
-    .. math::
-                   \\ \begin{array}{l}{\text { self. value }+=\text { value } * \text { weight }} \\ {\text { self. weight }+=\text { weight }}\end{array} \\
-
-参数：    
-    - **value** (float|numpy.array) – mini-batch的正确率
-    - **weight** (int|float) – mini-batch的大小
-
-返回：无
-
-.. py:method:: eval()
-
-该函数计算并返回累计的mini-batches的平均准确率。
-
-返回：累计的mini-batches的平均准确率
-
-返回类型：float或numpy.array
-

doc/paddle/api/paddle/metric/Auc_cn.rst

-.. _cn_api_fluid_metrics_Auc:
-
-Auc
--------------------------------
-.. py:class:: paddle.fluid.metrics.Auc(name, curve='ROC', num_thresholds=4095)
-
-
-
-
-**注意**：目前只用Python实现Auc，可能速度略慢
-
-该接口计算Auc，在二分类(binary classification)中广泛使用。相关定义参考 https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 。
-
-该接口创建四个局部变量true_positives, true_negatives, false_positives和false_negatives，用于计算Auc。为了离散化AUC曲线，使用临界值的线性间隔来计算召回率和准确率的值。用false positive的召回值高度计算ROC曲线面积，用recall的准确值高度计算PR曲线面积。
-
-参数：
-    - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
-    - **curve** (str) - 将要计算的曲线名的详情，曲线包括ROC（默认）或者PR（Precision-Recall-curve）。
-
-返回：初始化后的 ``Auc`` 对象
-
-返回类型：Auc
-
-**代码示例**：
-
-.. code-block:: python
-
-    import paddle.fluid as fluid
-    import numpy as np
-    # 初始化auc度量
-    auc_metric = fluid.metrics.Auc("ROC")
-
-    # 假设batch_size为128
-    batch_num = 100
-    batch_size = 128
-
-    for batch_id in range(batch_num):
-        
-        class0_preds = np.random.random(size = (batch_size, 1))
-        class1_preds = 1 - class0_preds
-         
-        preds = np.concatenate((class0_preds, class1_preds), axis=1)
-         
-        labels = np.random.randint(2, size = (batch_size, 1))
-        auc_metric.update(preds = preds, labels = labels)
-        
-        # 应为一个接近0.5的值，因为preds是随机指定的
-        print("auc for iteration %d is %.2f" % (batch_id, auc_metric.eval()))
-
-.. py:method:: update(preds, labels)
-
-用给定的预测值和标签更新Auc曲线。
-
-参数： 
-    - **preds** (numpy.array) - 维度为[batch_size, 2]，preds[i][j]表示将实例i划分为类别j的概率。
-    - **labels** (numpy.array) - 维度为[batch_size, 1]，labels[i]为0或1，代表实例i的标签。
-
-返回：无
-
-.. py:method:: eval()
-
-该函数计算并返回Auc值。
-
-返回：Auc值
-
-返回类型：float
-

doc/paddle/api/paddle/metric/metrics/Accuracy_cn.rst

@@ -5,17 +5,16 @@ Accuracy
 
 .. py:class:: paddle.metric.Accuracy()
 
+计算准确率(accuracy)。
 
-    Encapsulates accuracy metric logic.
-
-    参数
+参数：
 :::::::::
-        topk (int|tuple(int)): Number of top elements to look at
-            for computing accuracy. Default is (1,).
-        name (str, optional): String name of the metric instance. Default
-            is `acc`.
+    - **topk** (int|tuple(int)) - 计算准确率的top个数，默认是1。
+    - **name** (str, optional) - metric实例的名字，默认是'acc'。
+
+**代码示例**：
 
-    Example by standalone:
+    # 独立使用示例:
         
         .. code-block:: python
 
@@ -37,7 +36,7 @@ Accuracy
             print(res) # 0.75
 
 
-    Example with Model API:
+    # 在Model API中的示例:
         
         .. code-block:: python
 
@@ -57,3 +56,51 @@ Accuracy
             model.fit(train_dataset, batch_size=64)
 
 
+.. py:function:: compute(pred, label, *args)
+
+计算top-k（topk中的最大值）的索引。
+
+参数：
+:::::::::
+    - **pred**  (Tensor) - 预测结果为是float64或float32类型的Tensor。
+    - **label**  (Tensor) - 真实的标签值是一个2D的Tensor，shape为[batch_size, 1], 数据类型为int64。
+
+返回: 一个Tensor，shape是[batch_size, topk], 值为0或1，1表示预测正确.
+
+
+.. py:function:: update(pred, label, *args)
+
+更新metric的状态（正确预测的个数和总个数），以便计算累积的准确率。返回当前step的准确率。
+
+参数:
+:::::::::
+    - **correct** (numpy.array | Tensor): 一个值为0或1的Tensor，shape是[batch_size, topk]。
+
+返回: 当前step的准确率。
+
+
+.. py:function:: reset()
+
+清空状态和计算结果。
+
+返回
+:::::::::
+  无
+
+
+.. py:function:: accumulate()
+
+累积的统计指标，计算和返回准确率。
+
+返回
+:::::::::
+  准确率，一般是个标量 或 多个标量，和topk的个数一致。
+
+
+.. py:function:: name()
+
+返回Metric实例的名字, 参考上述name，默认是'acc'。
+
+返回
+:::::::::
+  评估的名字，string类型。

doc/paddle/api/paddle/metric/metrics/Auc_cn.rst

@@ -5,32 +5,23 @@ Auc
 
 .. py:class:: paddle.metric.Auc()
 
+**注意**：目前只用Python实现Auc，可能速度略慢
 
-    The auc metric is for binary classification.
-    Refer to https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve.
-    Please notice that the auc metric is implemented with python, which may be a little bit slow.
+该接口计算Auc，在二分类(binary classification)中广泛使用。相关定义参考 https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 。
 
-    The `auc` function creates four local variables, `true_positives`,
-    `true_negatives`, `false_positives` and `false_negatives` that are used to
-    compute the AUC. To discretize the AUC curve, a linearly spaced set of
-    thresholds is used to compute pairs of recall and precision values. The area
-    under the ROC-curve is therefore computed using the height of the recall
-    values by the false positive rate, while the area under the PR-curve is the
-    computed using the height of the precision values by the recall.
+该接口创建四个局部变量true_positives, true_negatives, false_positives和false_negatives，用于计算Auc。为了离散化AUC曲线，使用临界值的线性间隔来计算召回率和准确率的值。用false positive的召回值高度计算ROC曲线面积，用recall的准确值高度计算PR曲线面积。
 
-    参数
+
+参数：
 :::::::::
-        curve (str): Specifies the mode of the curve to be computed,
-            'ROC' or 'PR' for the Precision-Recall-curve. Default is 'ROC'.
-        num_thresholds (int): The number of thresholds to use when
-            discretizing the roc curve. Default is 4095.
-            'ROC' or 'PR' for the Precision-Recall-curve. Default is 'ROC'.
-        name (str, optional): String name of the metric instance. Default
-            is `auc`.
+    - **curve** (str) - 将要计算的曲线名的模式，包括'ROC'（默认）或者'PR'（Precision-Recall-curve）。
+    - **num_thresholds** (int) - 离散化AUC曲线的整数阈值数，默认是4095。
+    - **name** (str，可选) – metric实例的名字，默认是'auc'。
+
+**代码示例**：
 
-    "NOTE: only implement the ROC curve type via Python now."
+    # 独立使用示例:
 
-    Example by standalone:
         .. code-block:: python
 
             import numpy as np
@@ -49,7 +40,7 @@ Auc
             res = m.accumulate()
 
 
-    Example with Model API:
+    # 在Model API中的示例:
         
         .. code-block:: python
 
@@ -87,3 +78,35 @@ Auc
             data = Data()
             model.fit(data, batch_size=16)
     
+
+.. py:function:: update(pred, label, *args)
+
+更新AUC计算的状态。
+
+参数:
+:::::::::
+    - **preds** (numpy.array | Tensor): 一个shape为[batch_size, 2]的Numpy数组或Tensor，preds[i][j]表示第i个样本类别为j的概率。
+    - **labels** (numpy.array | Tensor): 一个shape为[batch_size, 1]的Numpy数组或Tensor，labels[i]是0或1，表示第i个样本的类别。
+
+返回: 无。
+
+
+.. py:function:: reset()
+
+清空状态和计算结果。
+
+返回：无
+
+
+.. py:function:: accumulate()
+
+累积的统计指标，计算和返回AUC值。
+
+返回：AUC值，一个标量。
+
+
+.. py:function:: name()
+
+返回Metric实例的名字, 参考上述的name，默认是'auc'。
+
+返回: 评估的名字，string类型。

doc/paddle/api/paddle/metric/metrics/Metric_cn.rst

@@ -6,22 +6,27 @@ Metric
 .. py:class:: paddle.metric.Metric()
 
 
-    Base class for metric, encapsulates metric logic and APIs
-    Usage:
+评估器metric的基类。
+
+用法:
+    
+    .. code-block:: text
 
         m = SomeMetric()
         for prediction, label in ...:
             m.update(prediction, label)
         m.accumulate()
     
-    Advanced usage for :code:`compute`:
+:code:`compute` 接口的进阶用法:
+
+在 :code:`compute` 中可以使用PaddlePaddle内置的算子进行评估器的状态，而不是通过
+Python/NumPy, 这样可以加速计算。:code:`update` 接口将 :code:`compute` 的输出作为
+输入，内部采用Python/NumPy计算。
+
+:code: `Metric` 计算流程如下 （在{}中的表示模型和评估器的计算）:
+
+    .. code-block:: text
 
-    Metric calculation can be accelerated by calculating metric states
-    from model outputs and labels by build-in operators not by Python/NumPy
-    in :code:`compute`, metric states will be fetched as NumPy array and
-    call :code:`update` with states in NumPy format.
-    Metric calculated as follows (operations in Model and Metric are
-    indicated with curly brackets, while data nodes not):
              inputs & labels              || ------------------
                    |                      ||
                 {model}                   ||
@@ -37,18 +42,16 @@ Metric
           metric states(numpy)            ||    numpy data
                    |                      ||
             {Metric.update}               \/ ------------------
-    代码示例
-:::::::::
-        
-        For :code:`Accuracy` metric, which takes :code:`pred` and :code:`label`
-        as inputs, we can calculate the correct prediction matrix between
-        :code:`pred` and :code:`label` in :code:`compute`.
-        For examples, prediction results contains 10 classes, while :code:`pred`
-        shape is [N, 10], :code:`label` shape is [N, 1], N is mini-batch size,
-        and we only need to calculate accurary of top-1 and top-5, we could
-        calculate the correct prediction matrix of the top-5 scores of the
-        prediction of each sample like follows, while the correct prediction
-        matrix shape is [N, 5].
+
+**代码示例**
+
+以 计算正确率的 :code: `Accuracy` 为例，该评估器的输入为 :code: `pred` 和
+:code: `label`, 可以在 :code:`compute` 中通过 :code: `pred` 和 :code: `label`
+先计算正确预测的矩阵。 例如，预测结果包含10类，:code: `pred` 的shape是[N, 10]，
+:code: `label` 的shape是[N, 1], N是batch size，我们需要计算top-1和top-5的准
+确率，可以在:code: `compute` 中计算每个样本的top-5得分，正确预测的矩阵的shape
+是[N, 5].
+
         
     .. code-block:: python
         def compute(pred, label):
@@ -58,10 +61,8 @@ Metric
             correct = pred == label
             return paddle.cast(correct, dtype='float32')
 
-        With the :code:`compute`, we split some calculations to OPs (which
-        may run on GPU devices, will be faster), and only fetch 1 tensor with
-        shape as [N, 5] instead of 2 tensors with shapes as [N, 10] and [N, 1].
-        :code:`update` can be define as follows:
+在:code:`compute` 中的计算，使用内置的算子(可以跑在GPU上，是的速度更快)。
+作为:code:`update` 的输入，该接口计算如下: 
 
     .. code-block:: python
         def update(self, correct):
@@ -74,3 +75,45 @@ Metric
                 self.count[i] += num_samples
             return accs
 
+.. py:function:: reset()
+
+清空状态和计算结果。
+
+返回：无
+
+
+.. py:function:: update(*args)
+
+
+更新状态。如果定义了:code:`compute` ，:code:`update` 的输入是:code:`compute` 的输出。
+如果没有定义，则输入是网络的输出**output**和标签**label**，
+如: :code:`update(output1, output2, ..., label1, label2,...)` .
+
+也可以参考 :code:`update` 。
+
+
+.. py:function:: accumulate()
+
+累积的统计指标，计算和返回评估结果。
+
+返回：评估结果，一般是个标量 或 多个标量。
+
+
+.. py:function:: name()
+
+返回Metric的名字, 一般通过__init__构造函数传入。
+
+返回: 评估的名字，string类型。
+
+
+.. py:function:: compute()
+
+此接口可以通过PaddlePaddle内置的算子计算metric的状态，可以加速metric的计算，
+为可选的高阶接口。
+
+如果这个接口定义了，输入是网络的输出 **outputs** 和 标签 **labels** , 定义如:
+:code:`compute(output1, output2, ..., label1, label2,...)` 。
+如果这个接口没有定义, 默认的行为是直接将输入参数返回给 :code: `update` ，则其
+定义如: :code:`update(output1, output2, ..., label1, label2,...)` 。
+
+也可以参考 :code:`compute` 。

doc/paddle/api/paddle/metric/metrics/Precision_cn.rst

@@ -6,19 +6,19 @@ Precision
 .. py:class:: paddle.metric.Precision()
 
 
-    Precision (also called positive predictive value) is the fraction of
-    relevant instances among the retrieved instances. Refer to
-    https://en.wikipedia.org/wiki/Evaluation_of_binary_classifiers
+精确率Precision(也称为 positive predictive value,正预测值)是被预测为正样例中实际为正的比例。 https://en.wikipedia.org/wiki/Evaluation_of_binary_classifiers 该类管理二分类任务的precision分数。
 
-    Noted that this class manages the precision score only for binary
-    classification task.
+**注意**：这个metric只能用来评估二分类。
 
-    参数
+
+参数:
 :::::::::
-        name (str, optional): String name of the metric instance.
-            Default is `precision`.
+    - **name** (str，可选) – metric实例的名字，默认是'precision'。
+
+
+**代码示例**
 
-    Example by standalone:
+    # 独立使用示例:
         
         .. code-block:: python
 
@@ -33,8 +33,7 @@ Precision
             res = m.accumulate()
             print(res) # 1.0
 
-
-    Example with Model API:
+    # 在Model API中的示例:
         
         .. code-block:: python
 
@@ -71,3 +70,35 @@ Precision
             data = Data()
             model.fit(data, batch_size=16)
     
+
+.. py:function:: update(preds, labels, *args)
+
+更新Precision的状态。
+
+参数:
+:::::::::
+    - **preds** (numpy.array | Tensor): 预测输出结果通常是sigmoid函数的输出，是一个数据类型为float64或float32的向量。
+    - **labels** (numpy.array | Tensor): 真实标签的shape和:code: `preds` 相同，数据类型为int32或int64。
+
+返回: 无。
+
+
+.. py:function:: reset()
+
+清空状态和计算结果。
+
+返回：无
+
+
+.. py:function:: accumulate()
+
+累积的统计指标，计算和返回precision值。
+
+返回：precision值，一个标量。
+
+
+.. py:function:: name()
+
+返回Metric实例的名字, 参考上述的name，默认是'precision'。
+
+返回: 评估的名字，string类型。

doc/paddle/api/paddle/metric/metrics/Recall_cn.rst

@@ -6,22 +6,19 @@ Recall
 .. py:class:: paddle.metric.Recall()
 
 
-    Recall (also known as sensitivity) is the fraction of
-    relevant instances that have been retrieved over the
-    total amount of relevant instances
+召回率Recall（也称为敏感度）是指得到的相关实例数占相关实例总数的比例。https://en.wikipedia.org/wiki/Precision_and_recall 该类管理二分类任务的召回率。
 
-    Refer to:
-    https://en.wikipedia.org/wiki/Precision_and_recall
+**注意**：这个metric只能用来评估二分类。
 
-    Noted that this class manages the recall score only for
-    binary classification task.
 
-    参数
+参数
 :::::::::
-        name (str, optional): String name of the metric instance.
-            Default is `recall`.
+    - **name** (str，可选) – metric实例的名字，默认是'recall'。
 
-    Example by standalone:
+
+**代码示例**
+
+    # 独立使用示例:
         
         .. code-block:: python
 
@@ -36,8 +33,7 @@ Recall
             res = m.accumulate()
             print(res) # 2.0 / 3.0
 
-
-    Example with Model API:
+    # 在Model API中的示例:
         
         .. code-block:: python
 
@@ -74,3 +70,35 @@ Recall
             data = Data()
             model.fit(data, batch_size=16)
     
+
+.. py:function:: update(preds, labels, *args)
+
+更新Recall的状态。
+
+参数:
+:::::::::
+    - **preds** (numpy.array | Tensor): 预测输出结果通常是sigmoid函数的输出，是一个数据类型为float64或float32的向量。
+    - **labels** (numpy.array | Tensor): 真实标签的shape和:code: `preds` 相同，数据类型为int32或int64。
+
+返回: 无。
+
+
+.. py:function:: reset()
+
+清空状态和计算结果。
+
+返回：无
+
+
+.. py:function:: accumulate()
+
+累积的统计指标，计算和返回recall值。
+
+返回：precision值，一个标量。
+
+
+.. py:function:: name()
+
+返回Metric实例的名字, 参考上述的name，默认是'recall'。
+
+返回: 评估的名字，string类型。