mindspore-Ecosystem
/
mindspore
21
0
Fork 27
Code Issues Pull Requests 6 Projects Releases Wiki Activity

add metric chinese api comments

This commit is contained in:
liutongtong 2021-11-29 15:11:04 +08:00
parent 7453933e3c
commit 498da0eded
19 changed files with 521 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/api/api_python/nn/metric/mindspore.nn.Accuracy.txt Normal file
View File

@ -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。

20
docs/api/api_python/nn/metric/mindspore.nn.F1.txt Normal file
View File

@ -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]

49
docs/api/api_python/nn/metric/mindspore.nn.Fbeta.txt Normal file
View File

@ -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,)`。

44
docs/api/api_python/nn/metric/mindspore.nn.Loss.txt Normal file
View File

@ -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。

49
docs/api/api_python/nn/metric/mindspore.nn.MAE.txt Normal file
View File

@ -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。

46
docs/api/api_python/nn/metric/mindspore.nn.MSE.txt Normal file
View File

@ -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。

57
docs/api/api_python/nn/metric/mindspore.nn.Precision.txt Normal file
View File

@ -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。

57
docs/api/api_python/nn/metric/mindspore.nn.Recall.txt Normal file
View File

@ -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。

15
docs/api/api_python/nn/metric/mindspore.nn.Top1CategoricalAccuracy.txt Normal file
View File

@ -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

15
docs/api/api_python/nn/metric/mindspore.nn.Top5CategoricalAccuracy.txt Normal file
View File

@ -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

48
docs/api/api_python/nn/metric/mindspore.nn.TopKCategoricalAccuracy.txt Normal file
View File

@ -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,)`。

14
docs/api/api_python/nn/metric/mindspore.nn.get_metric_fn.txt Normal file
View File

@ -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')

7
docs/api/api_python/nn/metric/mindspore.nn.names.txt Normal file
View File

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

33
docs/api/api_python/nn/metric/mindspore.nn.rearrange_inputs.txt Normal file
View File

@ -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，用于在函数之间调换输入。

2
mindspore/nn/cell.py
View File

@ -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:

2
mindspore/nn/metrics/__init__.py
View File

@ -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.

3
mindspore/nn/metrics/error.py
View File

@ -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

6
mindspore/nn/metrics/mean_surface_distance.py
View File

@ -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]]))

2
mindspore/nn/metrics/root_mean_square_surface_distance.py
View File

@ -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: