add metric chinese api comments

docs/api/api_python/nn/metric/mindspore.nn.Accuracy.txt

@@ -0,0 +1,61 @@
+Class mindspore.nn.Accuracy(eval_type='classification')
+
+    计算'classification'单标签数据分类和'multilabel'多标签数据分类的正确率。
+
+    此类创建两个局部变量，预测正确的样本数和总样本数，用于计算预测值`y_pred`和真实标签`y`的匹配频率。
+    此频率最终作为正确率返回：是一个将预测正确的数目除以总数的幂等操作。
+
+
+    .. math::
+        \text{accuracy} =\frac{\text{true_positive} + \text{true_negative}}
+        {\text{true_positive} + \text{true_negative} + \text{false_positive} + \text{false_negative}}
+
+    参数：
+        eval_type (str)：评估的数据集的类型，支持'classification'和'multilabel'。'classification'为单标签分类场景，'multilabel'为多标签分类场景。
+
+            默认值：'classification'。
+
+    示例：
+        >>> import numpy as np
+        >>> from mindspore import nn, Tensor
+        >>>
+        >>> x = Tensor(np.array([[0.2, 0.5], [0.3, 0.1], [0.9, 0.6]]), mindspore.float32)
+        >>> y = Tensor(np.array([1, 0, 1]), mindspore.float32)
+        >>> metric = nn.Accuracy('classification')
+        >>> metric.clear()
+        >>> metric.update(x, y)
+        >>> accuracy = metric.eval()
+        >>> print(accuracy)
+        0.6666666666666666
+
+
+clear()
+内部评估结果清零。
+
+eval()
+
+        计算正确率。
+
+        返回：
+            Float，计算的结果。
+
+        异常：
+            RuntimeError：样本量为0。
+
+
+update(*inputs)
+
+        更新局部变量。计算预测值y_pred和标签y的匹配频率。
+        对于'classification'，如果预测的最大值的索引匹配真实的标签，预测正确；对于'multilabel'，如果预测值与真实标签匹配，预测正确。
+
+        参数：
+            inputs：预测值 `y_pred` 和真实标签 `y` ，`y_pred` 和 `y` 支持Tensor、list或numpy.ndarray类型。
+
+                对于'classification'情况，`y_pred`在大多数情况下由范围:math:`[0, 1]`中的浮点数组成，shape为:math:`(N, C)`，其中:math:`N`是样本数，:math:`C`是类别数。
+                                              `y` 由整数值组成，如果是one_hot编码格式，shape是:math:`(N,C)`；如果是类别索引，shape是:math:`(N,)`。
+
+                对于'multilabel'情况，`y_pred`和`y`只能是值为0或1的one-hot编码格式，其中值为1的索引表示正类别。`y_pred`和`y`的shape都是:math:`(N,C)`。
+
+
+        异常：
+            ValueError：inputs的数量不等于2。

docs/api/api_python/nn/metric/mindspore.nn.F1.txt

@@ -0,0 +1,20 @@
+Class mindspore.nn.F1
+
+    计算F1 score。F1是Fbeta的特殊情况，即beta为1。
+    有关更多详细信息，请参阅类:class:`mindspore.nn.Fbeta`。
+
+    .. math::
+        F_1=\frac{2\cdot true\_positive}{2\cdot true\_positive + false\_negative + false\_positive}
+
+    示例：
+        >>> import numpy as np
+        >>> from mindspore import nn, Tensor
+        >>>
+        >>> x = Tensor(np.array([[0.2, 0.5], [0.3, 0.1], [0.9, 0.6]]))
+        >>> y = Tensor(np.array([1, 0, 1]))
+        >>> metric = nn.F1()
+        >>> metric.update(x, y)
+        >>> result = metric.eval()
+        >>> print(result)
+        [0.66666667 0.66666667]
+    

docs/api/api_python/nn/metric/mindspore.nn.Fbeta.txt

@@ -0,0 +1,49 @@
+Class mindspore.nn.Fbeta(beta)
+
+    计算fbeta评分。
+
+    Fbeta评分是精度(Precision)和召回率(Recall)的加权平均值。
+
+    .. math::
+        F_\beta=\frac{(1+\beta^2) \cdot true\_positive}
+                {(1+\beta^2) \cdot true\_positive +\beta^2 \cdot false\_negative + false\_positive}
+
+    参数：
+        beta (Union[float, int])：F-measure中的beta系数 。
+
+    示例：
+        >>> import numpy as np
+        >>> from mindspore import nn, Tensor
+        >>>
+        >>> x = Tensor(np.array([[0.2, 0.5], [0.3, 0.1], [0.9, 0.6]]))
+        >>> y = Tensor(np.array([1, 0, 1]))
+        >>> metric = nn.Fbeta(1)
+        >>> metric.clear()
+        >>> metric.update(x, y)
+        >>> fbeta = metric.eval()
+        >>> print(fbeta)
+        [0.66666667 0.66666667]
+
+
+clear()
+内部评估结果清零。
+
+eval(average=False)
+
+        计算fbeta结果。
+
+        参数：
+            average (bool)：是否计算fbeta平均值。默认值：False。
+
+        返回：
+            numpy.ndarray或numpy.float64，计算结果。
+
+
+update(*inputs)
+
+        使用预测值 `y_pred` 和真实标签 `y` 更新内部评估结果。
+
+        参数：
+            inputs：`y_pred` 和 `y` 。`y_pred` 和 `y` 支持Tensor、list或numpy.ndarray类型。
+                通常情况下，`y_pred`是0到1之间的浮点数列表，shape为:math:`(N, C)`，其中:math:`N`是样本数，:math:`C`是类别数。
+                                   `y` 是整数值，如果使用one-hot编码，则shape为:math:`(N,C)`；如果使用类别索引，shape是:math:`(N,)`。

docs/api/api_python/nn/metric/mindspore.nn.Loss.txt

@@ -0,0 +1,44 @@
+Class mindspore.nn.Loss
+
+    计算loss的平均值。如果每:math:`n` 次迭代调用一次 `update` 方法，则评估结果为：
+
+
+    .. math::
+        loss = \frac{\sum_{k=1}^{n}loss_k}{n}
+
+    示例：
+        >>> import numpy as np
+        >>> from mindspore import nn, Tensor
+        >>>
+        >>> x = Tensor(np.array(0.2), mindspore.float32)
+        >>> loss = nn.Loss()
+        >>> loss.clear()
+        >>> loss.update(x)
+        >>> result = loss.eval()
+
+
+clear()
+内部评估结果清零。
+
+eval()
+
+        计算loss的平均值。
+
+        返回：
+            Float，loss的平均值。
+
+        异常：
+            RuntimeError：样本总数为0。
+
+
+update(*inputs)
+
+        更新内部评估结果。
+
+        参数：
+            inputs：输入只包含一个元素，且该元素为loss。loss的维度必须为0或1。
+
+
+        异常：
+            ValueError：`inputs` 的长度不为1。
+            ValueError：`inputs` 的维度不为0或1。

docs/api/api_python/nn/metric/mindspore.nn.MAE.txt

@@ -0,0 +1,49 @@
+Class mindspore.nn.MAE
+
+    计算平均绝对误差（MAE）。
+
+    创建了一个用于测量输入:math:`x`和目标:math:`y`各元素之间的平均绝对误差（MAE）的标准。
+
+    .. math::
+        \text{MAE} = \frac{\sum_{i=1}^n \|y_i - x_i\|}{n}
+
+    这里，:math:`n`是bach size。
+
+    示例：
+        >>> import numpy as np
+        >>> from mindspore import nn, Tensor
+        >>>
+        >>> x = Tensor(np.array([0.1, 0.2, 0.6, 0.9]), mindspore.float32)
+        >>> y = Tensor(np.array([0.1, 0.25, 0.7, 0.9]), mindspore.float32)
+        >>> error = nn.MAE()
+        >>> error.clear()
+        >>> error.update(x, y)
+        >>> result = error.eval()
+        >>> print(result)
+        0.037499990314245224
+
+
+clear()
+内部评估结果清零。
+
+eval()
+
+        计算平均绝对差（MAE）。
+
+        返回：
+            numpy.float64，计算结果。
+
+        异常：
+            RuntimeError：样本总数为0。
+
+
+update(*inputs)
+
+        使用预测值:math:`y_{pred}`和真实值:math:`y`更新局部变量。
+
+        参数：
+            inputs：输入`y_pred`和`y`来计算MAE，其中`y_pred`和`y`的shape都是N-D，它们的shape相同。
+
+
+        异常：
+            ValueError：`inputs` 的数量不等于2。

docs/api/api_python/nn/metric/mindspore.nn.MSE.txt

@@ -0,0 +1,46 @@
+Class mindspore.nn.MSE
+
+    测量均方差（MSE）。
+
+    创建用于计算输入:math:`x`和目标:math:`y`中的每个元素的均方差（L2范数平方）的标准。
+
+    .. math::
+        \text{MSE}(x,\ y) = \frac{\sum_{i=1}^n(y_i - x_i)^2}{n}
+
+    其中，:math:`n` 为batch size。
+
+    示例：
+        >>> import numpy as np
+        >>> from mindspore import nn, Tensor
+        >>>
+        >>> x = Tensor(np.array([0.1, 0.2, 0.6, 0.9]), mindspore.float32)
+        >>> y = Tensor(np.array([0.1, 0.25, 0.5, 0.9]), mindspore.float32)
+        >>> error = nn.MSE()
+        >>> error.clear()
+        >>> error.update(x, y)
+        >>> result = error.eval()
+
+
+clear()
+清除内部评估结果。
+
+eval()
+
+        计算均方差（MSE）。
+
+        返回：
+            numpy.float64，计算结果。
+
+        异常：
+            RuntimeError：样本数为0。
+
+
+update(*inputs)
+
+        使用预测值:math:`y_{pred}`和真实值:math:`y`更新局部变量。。
+
+        参数：
+            输入：输入`y_pred`和`y`用于计算MSE，其中`y_pred`和`y`shape都为N-D，它们的shape相同。
+
+        异常：
+            ValueError：`inputs` 的数量不等于2。

docs/api/api_python/nn/metric/mindspore.nn.Precision.txt

@@ -0,0 +1,57 @@
+Class mindspore.nn.Precision(eval_type='classification')
+
+    计算'classification'单标签数据分类和'multilabel'多标签数据分类的精度。
+
+    此函数创建两个局部变量:math:`\text{true_positive}`和:math:`\text{false_positive}` 用于计算精度。计算方式为:math:`\text{true_positive}`除以:math:`\text{true_positive}`与:math:`\text{false_positive}`的和，是一个幂等操作，此值最终作为精度返回。
+
+    .. math::
+        \text{precision} = \frac{\text{true_positive}}{\text{true_positive} + \text{false_positive}}
+
+    注：
+        在多标签情况下，:math:`y`和:math:`y_{pred}`的元素必须为0或1。
+
+    参数：
+        eval_type （str）：支持'classification'和'multilabel'。默认值：'classification'。
+
+    示例：
+        >>> import numpy as np
+        >>> from mindspore import nn, Tensor
+        >>>
+        >>> x = Tensor(np.array([[0.2, 0.5], [0.3, 0.1], [0.9, 0.6]]))
+        >>> y = Tensor(np.array([1, 0, 1]))
+        >>> metric = nn.Precision('classification')
+        >>> metric.clear()
+        >>> metric.update(x, y)
+        >>> precision = metric.eval()
+        >>> print(precision)
+        [0.5 1. ]
+
+
+
+clear()
+内部评估结果清零。
+
+eval(average=False)
+
+        计算精度。
+
+        参数：
+            average (bool)：指定是否计算平均精度。默认值：False。
+
+        返回：
+            numpy.float64，计算结果。
+
+
+update(*inputs)
+
+        使用预测值`y_pred`和真实标签`y`更新局部变量。
+
+        参数：
+            inputs：输入`y_pred`和`y`。`y_pred` 和 `y` 支持Tensor、list或numpy.ndarray类型。
+                对于'classification'情况，`y_pred`在大多数情况下由范围:math:`[0, 1]`中的浮点数组成，shape为:math:`(N, C)`，其中:math:`N`是样本数，:math:`C`是类别数。
+                                              `y` 由整数值组成，如果是one_hot编码格式，shape是:math:`(N,C)`；如果是类别索引，shape是:math:`(N,)`。
+
+                对于'multilabel'情况，`y_pred`和`y`只能是值为0或1的one-hot编码格式，其中值为1的索引表示正类别。`y_pred`和`y`的shape都是:math:`(N,C)`。
+
+        异常：
+            ValueError：inputs数量不是2。

docs/api/api_python/nn/metric/mindspore.nn.Recall.txt

@@ -0,0 +1,57 @@
+Class mindspore.nn.Recall(eval_type='classification')
+
+    计算'classification'单标签数据分类和'multilabel'多标签数据分类的召回率。
+
+    recall类创建两个局部变量:math:`\text{true_positive}`和:math:`\text{false_negative}`用于计算召回率。计算方式为:math:`\text{true_positive}`除以:math:`\text{true_positive}`与:math:'\text{false_negative}'的和，是一个幂等操作，此值最终作为召回返回。
+
+    .. math::
+        \text{recall} = \frac{\text{true_positive}}{\text{true_positive} + \text{false_negative}}
+
+    注：
+        在多标签情况下，:math:`y`和:math:`y_{pred}`的元素必须为0或1。
+
+    参数：
+        eval_type （str）：支持'classification'和'multilabel'。默认值：'classification'。
+
+    示例：
+        >>> import numpy as np
+        >>> from mindspore import nn, Tensor
+        >>>
+        >>> x = Tensor(np.array([[0.2, 0.5], [0.3, 0.1], [0.9, 0.6]]))
+        >>> y = Tensor(np.array([1, 0, 1]))
+        >>> metric = nn.Recall('classification')
+        >>> metric.clear()
+        >>> metric.update(x, y)
+        >>> recall = metric.eval()
+        >>> print(recall)
+        [1. 0.5]
+
+
+clear()
+内部评估结果清零。
+
+eval(average=False)
+
+        计算召回率。
+
+        参数：
+            average (bool)：指定是否计算平均召回率。默认值：False。
+
+        返回：
+            numpy.float64，计算结果。
+
+
+update(*inputs)
+
+        使用预测值`y_pred`和真实标签`y`更新局部变量。
+
+        参数：
+            inputs：输入`y_pred`和`y`。`y_pred` 和 `y` 支持Tensor、list或numpy.ndarray类型。
+                对于'classification'情况，`y_pred`在大多数情况下由范围:math:`[0, 1]`中的浮点数组成，shape为:math:`(N, C)`，其中:math:`N`是样本数，:math:`C`是类别数。
+                                              `y` 由整数值组成，如果是one_hot编码格式，shape是:math:`(N,C)`；如果是类别索引，shape是:math:`(N,)`。
+
+                对于'multilabel'情况，`y_pred`和`y`只能是值为0或1的one-hot编码格式，其中值为1的索引表示正类别。`y_pred`和`y`的shape都是:math:`(N,C)`。
+
+
+        异常：
+            ValueError：inputs数量不是2。

docs/api/api_python/nn/metric/mindspore.nn.Top1CategoricalAccuracy.txt

@@ -0,0 +1,15 @@
+Class mindspore.nn.Top1CategoricalAccuracy
+
+    计算top-1分类正确率。此类是TopKCategoricalAccuracy的特殊类。
+    有关更多详细信息，请参阅:class:`TopKCategoricalAccuracy`。
+
+    示例：
+        >>> x = Tensor(np.array([[0.2, 0.5, 0.3, 0.6, 0.2], [0.1, 0.35, 0.5, 0.2, 0.],
+        ...         [0.9, 0.6, 0.2, 0.01, 0.3]]), mindspore.float32)
+        >>> y = Tensor(np.array([2, 0, 1]), mindspore.float32)
+        >>> topk = nn.Top1CategoricalAccuracy()
+        >>> topk.clear()
+        >>> topk.update(x, y)
+        >>> output = topk.eval()
+        >>> print(output)
+        0.0

docs/api/api_python/nn/metric/mindspore.nn.Top5CategoricalAccuracy.txt

@@ -0,0 +1,15 @@
+Class mindspore.nn.Top5CategoricalAccuracy
+
+    计算top-5分类正确率。此类是TopKCategoricalAccuracy的特殊类。
+    有关更多详细信息，请参阅:class:`TopKCategoricalAccuracy`。
+
+    示例：
+        >>> x = Tensor(np.array([[0.2, 0.5, 0.3, 0.6, 0.2], [0.1, 0.35, 0.5, 0.2, 0.],
+        ...            [0.9, 0.6, 0.2, 0.01, 0.3]]), mindspore.float32)
+        >>> y = Tensor(np.array([2, 0, 1]), mindspore.float32)
+        >>> topk = nn.Top5CategoricalAccuracy()
+        >>> topk.clear()
+        >>> topk.update(x, y)
+        >>> output = topk.eval()
+        >>> print(output)
+        1.0

docs/api/api_python/nn/metric/mindspore.nn.TopKCategoricalAccuracy.txt

@@ -0,0 +1,48 @@
+Class mindspore.nn.TopKCategoricalAccuracy(k)
+
+    计算top-k分类正确率。
+
+    注：
+        `update`方法需要接收满足:math:`(y_{pred}, y)`格式的输入。如果某些样本具有相同的正确率，则将选择第一个样本。
+
+    参数：
+        k (int)：指定要计算的top-k分类正确率。
+
+    异常：
+        TypeError：`k`不是int。
+        ValueError：`k`小于1。
+
+    示例：
+        >>> import numpy as np
+        >>> from mindspore import nn, Tensor
+        >>>
+        >>> x = Tensor(np.array([[0.2, 0.5, 0.3, 0.6, 0.2], [0.1, 0.35, 0.5, 0.2, 0.],
+        ...         [0.9, 0.6, 0.2, 0.01, 0.3]]), mindspore.float32)
+        >>> y = Tensor(np.array([2, 0, 1]), mindspore.float32)
+        >>> topk = nn.TopKCategoricalAccuracy(3)
+        >>> topk.clear()
+        >>> topk.update(x, y)
+        >>> output = topk.eval()
+        >>> print(output)
+        0.6666666666666666
+
+
+clear()
+内部评估结果清零。
+
+eval()
+
+        计算top-k分类正确率。
+
+        返回：
+            numpy.float64，计算结果。
+
+
+update(*inputs)
+
+        使用预测值`y_pred`和真实标签`y`更新局部变量。
+
+        参数：
+            inputs：输入`y_pred`和`y`。`y_pred` 和 `y` 支持Tensor、list或numpy.ndarray类型。
+                `y_pred`在大多数情况下由范围:math:`[0, 1]`中的浮点数组成，shape为 :math:`(N, C)`，其中:math:`N`是样本数，:math:`C`是类别数。
+                `y` 由整数值组成。如果使用one-hot编码，则shape为:math:`(N, C)`；如果使用类别索引，shape是:math:`(N,)`。

docs/api/api_python/nn/metric/mindspore.nn.get_metric_fn.txt

@@ -0,0 +1,14 @@
+mindspore.nn.get_metric_fn(name, *args, **kwargs)
+
+    根据输入的 `name` 获取metric的方法。
+
+    参数：
+        name (str)：metric的方法名，可以通过`mindspore.nn.names`接口获取。
+        args：metric函数的参数。
+        kwargs：metric函数的关键字参数。
+
+    返回：
+        metric对象，metric方法的类实例。
+
+    示例：
+        >>> metric = nn.get_metric_fn('precision', eval_type='classification')

docs/api/api_python/nn/metric/mindspore.nn.names.txt

@@ -0,0 +1,7 @@
+mindspore.nn.names()
+
+    获取所有metric的名称。
+
+    返回：
+        List，所有metric的名称列表。
+    

docs/api/api_python/nn/metric/mindspore.nn.rearrange_inputs.txt

@@ -0,0 +1,33 @@
+mindspore.nn.rearrange_inputs(func)
+
+    此装饰器用于根据类的`indexes`属性对输入重新排列。
+
+    此装饰器目前用于 :class:`mindspore.nn.Metric` 类的 `update` 方法。
+
+    示例：
+        >>> class RearrangeInputsExample:
+        ...     def __init__(self):
+        ...         self._indexes = None
+        ...
+        ...     @property
+        ...     def indexes(self):
+        ...         return getattr(self, '_indexes', None)
+        ...
+        ...     def set_indexes(self, indexes):
+        ...         self._indexes = indexes
+        ...         return self
+        ...
+        ...     @rearrange_inputs
+        ...     def update(self, *inputs):
+        ...         return inputs
+        >>>
+        >>> rearrange_inputs_example = RearrangeInputsExample().set_indexes([1, 0])
+        >>> outs = rearrange_inputs_example.update(5, 9)
+        >>> print(outs)
+        (9, 5)
+
+    参数：
+        func (Callable): 要装饰的候选函数，其输入将被重新排列。
+
+    返回：
+        Callable，用于在函数之间调换输入。

mindspore/nn/cell.py

@@ -42,7 +42,7 @@ class Cell(Cell_):
     """
     Base class for all neural networks.
 
-    A 'Cell' could be a single neural network cell, such as  :class:`mindspore.nn.Conv2d`,  :class:`mindspore.nn.ReLU,
+    A 'Cell' could be a single neural network cell, such as  :class:`mindspore.nn.Conv2d`,  :class:`mindspore.nn.ReLU`,
     :class:`mindspore.nn.BatchNorm`, etc. or a composition of cells to constructing a network.
 
     Note:

mindspore/nn/metrics/__init__.py

@@ -108,7 +108,7 @@ def get_metric_fn(name, *args, **kwargs):
     Gets the metric method based on the input name.
 
     Args:
-        name (str): The name of metric method. Refer to the '__factory__'
+        name (str): The name of metric method. Names can be obtained by `mindspore.nn.names` .
             object for the currently supported metrics.
         args: Arguments for the metric function.
         kwargs: Keyword arguments for the metric function.

mindspore/nn/metrics/error.py

@@ -29,9 +29,6 @@ class MAE(Metric):
 
     where :math:`n` is batch size.
 
-    Note:
-        The method `update` must be called with the form `update(y_pred, y)`.
-
     Examples:
         >>> import numpy as np
         >>> from mindspore import nn, Tensor

mindspore/nn/metrics/mean_surface_distance.py

@@ -50,8 +50,8 @@ class MeanSurfaceDistance(Metric):
                           Default: "euclidean".
         symmetric (bool): Whether to calculate the Mean Surface Distance between y_pred and y.
                           If False, it only calculates :math: `AvgSurDis(y_pred\rightarrow y)`,
-                           otherwise, the mean of  distance form `y_pred` to `y` and from `y` to `y_pred`, i.e.
-                           :math: `MeanSurDis(A \leftrightarrow B)`, will be returned. Default: False.
+                          otherwise, the mean of  distance form `y_pred` to `y` and from `y` to `y_pred`, i.e.
+                          :math: `MeanSurDis(A \leftrightarrow B)`, will be returned. Default: False.
 
     Supported Platforms:
         ``Ascend`` ``GPU`` ``CPU``
@@ -59,7 +59,7 @@ class MeanSurfaceDistance(Metric):
     Examples:
         >>> import numpy as np
 
-        >>> from mindspore imporst nn, Tensor
+        >>> from mindspore import nn, Tensor
         >>>
         >>> x = Tensor(np.array([[3, 0, 1], [1, 3, 0], [1, 0, 2]]))
         >>> y = Tensor(np.array([[0, 2, 1], [1, 2, 1], [0, 0, 1]]))

mindspore/nn/metrics/root_mean_square_surface_distance.py

@@ -35,7 +35,7 @@ class RootMeanSquareDistance(Metric):
         RmsSurDis(B \rightarrow A) = \sqrt{\frac{\sum_{s_{B}  \in S(B)}^{} {\text{dis}^2  \left ( s_{B}, S(A)
         \right )} }{\left | S(B) \right |}}
 
-    Where the \|\|\*\|\| denotes a distance measure.\ |\*\| denotes the number of elements.
+    Where the \|\|\*\|\| denotes a distance measure. \|\*\| denotes the number of elements.
 
     The Root Mean Square Surface Distance form set(B) to set(A) and from set(A) to set(B) is: