From aa14a89ddd53ccecaaaac0bbcfb5fa654f5d0cbc Mon Sep 17 00:00:00 2001
From: Chunyu Zhang <saxon.zh@gmail.com>
Date: Fri, 18 Sep 2020 18:53:54 +0800
Subject: [PATCH] add zh-CN doc for paddle.metric.accuracy & paddle.metric.auc
 (#2657)

---
 doc/paddle/api/not_display_doc_list          |  2 -
 doc/paddle/api/paddle/metric/accuracy_cn.rst | 53 +++++++++++++++
 doc/paddle/api/paddle/metric/auc_cn.rst      | 71 ++++++++++++++++++++
 3 files changed, 124 insertions(+), 2 deletions(-)
 create mode 100644 doc/paddle/api/paddle/metric/accuracy_cn.rst
 create mode 100644 doc/paddle/api/paddle/metric/auc_cn.rst

diff --git a/doc/paddle/api/not_display_doc_list b/doc/paddle/api/not_display_doc_list
index 4b4521eb1..d29ca804f 100644
--- a/doc/paddle/api/not_display_doc_list
+++ b/doc/paddle/api/not_display_doc_list
@@ -1,5 +1,3 @@
 paddle.utils
 paddle.incubate
 paddle.hapi.progressbar.ProgressBar
-paddle.metric.accuracy
-paddle.metric.auc
diff --git a/doc/paddle/api/paddle/metric/accuracy_cn.rst b/doc/paddle/api/paddle/metric/accuracy_cn.rst
new file mode 100644
index 000000000..0ef4deb37
--- /dev/null
+++ b/doc/paddle/api/paddle/metric/accuracy_cn.rst
@@ -0,0 +1,53 @@
+.. _cn_api_paddle_metric_accuracy:
+
+accuracy
+-------------------------------
+
+.. py:function:: paddle.metric.accuracy(input, label, k=1, correct=None, total=None)
+
+accuracy layer。 参考 https://en.wikipedia.org/wiki/Precision_and_recall
+
+使用输入和标签计算准确率。 如果正确的标签在topk个预测值里，则计算结果加1。注意：输出正确率的类型由input类型决定，input和lable的类型可以不一样。
+
+参数
+:::::::::
+
+    - **input** (Tensor|LoDTensor)-数据类型为float32,float64。输入为网络的预测值。shape为 ``[sample_number, class_dim]`` 。
+    - **label** (Tensor|LoDTensor)-数据类型为int64，int32。输入为数据集的标签。shape为 ``[sample_number, 1]`` 。
+    - **k** (int64|int32) - 取每个类别中k个预测值用于计算。
+    - **correct** (int64|int32)-正确预测值的个数。
+    - **total** (int64|int32)-总共的预测值。
+
+返回
+:::::::::
+
+    ``Tensor``，计算出来的正确率，数据类型为float32的Tensor。
+
+代码示例
+:::::::::
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    import numpy as np
+
+    data = fluid.layers.data(name="input", shape=[-1, 32, 32], dtype="float32")
+    label = fluid.layers.data(name="label", shape=[-1,1], dtype="int")
+    fc_out = fluid.layers.fc(input=data, size=10)
+    predict = fluid.layers.softmax(input=fc_out)
+    result = fluid.layers.accuracy(input=predict, label=label, k=5)
+
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+
+    exe.run(fluid.default_startup_program())
+    x = np.random.rand(3, 32, 32).astype("float32")
+    y = np.array([[1],[0],[1]])
+    output= exe.run(feed={"input": x,"label": y},
+                     fetch_list=[result[0]])
+    print(output)
+    
+    """
+    Output:
+    [array([0.6666667], dtype=float32)]
+    """
diff --git a/doc/paddle/api/paddle/metric/auc_cn.rst b/doc/paddle/api/paddle/metric/auc_cn.rst
new file mode 100644
index 000000000..092380aeb
--- /dev/null
+++ b/doc/paddle/api/paddle/metric/auc_cn.rst
@@ -0,0 +1,71 @@
+.. _cn_api_paddle_metric_auc:
+
+auc
+-------------------------------
+
+.. py:function:: paddle.metric.auc(input, label, curve='ROC', num_thresholds=200, topk=1, slide_steps=1)
+
+**Area Under the Curve(AUC) Layer**
+
+该层根据前向输出和标签计算AUC，在二分类(binary classification)估计中广泛使用。
+
+注：如果输入标注包含一种值，只有0或1两种情况，数据类型则强制转换成布尔值。相关定义可以在这里: https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 找到
+
+有两种可能的曲线：
+
+1. ROC:受试者工作特征曲线
+
+2. PR:准确率召回率曲线
+
+参数：
+:::::::::
+
+    - **input** (Tensor|LoDTensor) - 数据类型为float32，float64。浮点二维变量，值的范围为[0,1]。每一行降序排列。该输入为网络预测值的输入。
+    - **label** (Tensor|LoDTensor) - 数据类型为int32，int64。二维整型变量，为训练数据的标签。
+    - **curve** (str) - 曲线类型，可以为 ``ROC`` 或 ``PR``，默认 ``ROC``。
+    - **num_thresholds** (int) - 将roc曲线离散化时使用的临界值数。默认200。
+    - **topk** (int) -  取topk的输出值用于计算。
+    - **slide_steps** (int) - 当计算batch auc时，不仅用当前步也用于先前步。slide_steps=1，表示用当前步；slide_steps = 3表示用当前步和前两步；slide_steps = 0，则用所有步。
+
+返回：
+:::::::::
+
+   ``Tensor``, 代表当前AUC的一个元组, 数据类型为float32或float64的Tensor。
+   返回的元组为auc_out, batch_auc_out, [batch_stat_pos, batch_stat_neg, stat_pos, stat_neg]。
+   auc_out为准确率的结果。
+   batch_auc_out为batch准确率的结果。
+   batch_stat_pos为batch计算时label=1的统计值
+   batch_stat_neg为batch计算时label=0的统计值
+   stat_pos计算时label=1的统计值
+   stat_neg为计算时label=0的统计值
+
+
+代码示例：
+:::::::::
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    import numpy as np
+
+    data = fluid.layers.data(name="input", shape=[-1, 32,32], dtype="float32")
+    label = fluid.layers.data(name="label", shape=[1], dtype="int")
+    fc_out = fluid.layers.fc(input=data, size=2)
+    predict = fluid.layers.softmax(input=fc_out)
+    result=fluid.layers.auc(input=predict, label=label)
+
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+
+    exe.run(fluid.default_startup_program())
+    x = np.random.rand(3,32,32).astype("float32")
+    y = np.array([1,0,1])
+    output= exe.run(feed={"input": x,"label": y},
+                     fetch_list=[result[0]])
+    print(output)
+    """
+    output:
+    [array([0.5])]
+    """
+
+
-- 
GitLab