add chinese api

This commit is contained in:
liutongtong 2022-02-14 11:35:00 +08:00
parent ab4dcf81d1
commit 0747dead48
15 changed files with 397 additions and 21 deletions

View File

@ -0,0 +1,16 @@
mindspore.nn.GetNextSingleOp
=============================
.. py:class:: mindspore.nn.GetNextSingleOp(dataset_types, dataset_shapes, queue_name)
用于获取下一条数据的Cell。更详细的信息请参考 `mindspore.ops.GetNext`
**参数:**
- **dataset_types** (list[:class:`mindspore.dtype`]) - 数据集类型。
- **dataset_shapes** (list[tuple[int]]) - 数据集的shape。
- **queue_name** (str) - 待获取数据的队列名称。
**输出:**
tuple[Tensor],从数据集中获取的数据。

View File

@ -0,0 +1,20 @@
mindspore.nn.GraphCell
======================
.. py:class:: mindspore.nn.GraphCell(graph)
运行从MindIR加载的计算图。
此功能仍在开发中。目前 `GraphCell` 不支持修改图结构在导出MindIR时只能使用shape和类型与输入相同的数据。
**参数:**
- **graph** (object) - 从MindIR加载的编译图。
- **params_init** (dict) - 需要在图中初始化的参数。key为参数名称类型为字符串value为 Tensor 或 Parameter。如果参数名在图中已经存在则更新其值如果不存在则忽略。默认值None。
**异常:**
- **TypeError** 如果图不是FuncGraph类型。
- **TypeError** 如果 `params_init` 不是字典。
- **TypeError** 如果 `params_init` 的key不是字符串。
- **TypeError** 如果 `params_init` 的value既不是 Tensor也不是Parameter。

View File

@ -0,0 +1,51 @@
mindspore.nn.HausdorffDistance
============================================
.. py:class:: mindspore.nn.HausdorffDistance(distance_metric='euclidean', percentile=None, directed=False, crop=True)
计算Hausdorff距离。Hausdorff距离是两个点集之间两点的最小距离的最大值度量了两个点集间的最大不匹配程度。
给定两个集合A和BA和B之间的Hausdorff距离定义如下
.. math::
H(A, B) = \text{max}[h(A, B), h(B, A)]
h(A, B) = \underset{a \in A}{\text{max}}\{\underset{b \in B}{\text{min}} \rVert a - b \rVert \}
h(B, A) = \underset{b \in B}{\text{max}}\{\underset{a \in A}{\text{min}} \rVert b - a \rVert \}
其中h(A, B)表示对A中的每个点a找到B集合里的最近点这些最短距离的最大值为从A到B的单向Hausdorff距离同理h(B, A)为集合B到集合A中最近点的最大距离。Hausdoff距离是有方向性的通常情况下h(A, B)不等于h(B, A)。H(A, B)为双向Hausdorff距离。
**参数:**
- **distance_metric** (string):支持如下三种距离计算方法:"euclidean"、"chessboard" 或 "taxicab"。默认值:"euclidean"。
- **percentile** (float)0到100之间的浮点数。指定最终返回的Hausdorff距离的百分位数。默认值None。
- **directed** (bool)如果为True为单向Hausdorff距离只计算h(y_pred, y)距离如果为False为双向Hausdorff距离计算max(h(y_pred, y), h(y, y_pred))。默认值False。
- **crop** (bool)是否裁剪输入图像仅保留foregrounds。为了保证y_pred和y的shape匹配使用(y_pred | y)即两图像的并集来确定bounding box。默认值True。
.. py:method:: clear()
内部评估结果清零。
.. py:method:: eval()
计算定向或非定向Hausdorff距离。
**返回:**
numpy.float64计算得到的Hausdorff距离。
**异常:**
- **RuntimeError** - 如果没有先调用update方法。
.. py:method:: update(*inputs)
使用 `y_pred``y``label_idx` 更新内部评估结果。
**参数:**
- inputs`y_pred``y``label_idx``y_pred``y` 为Tensor list或numpy.ndarray`y_pred` 是预测的二值图像,`y` 是实际的二值图像。`label_idx` 的数据类型为int或float表示像素点的类别值。
**异常:**
- **ValueError** - 输入的数量不等于3。

View File

@ -0,0 +1,63 @@
mindspore.nn.MeanSurfaceDistance
===============================================
.. py:class:: mindspore.nn.MeanSurfaceDistance(symmetric=False, distance_metric='euclidean')
计算从 `y_pred``y` 的平均表面距离。通常情况下,用来衡量分割任务中,预测情况和真实情况之间的差异度。
给定两个集合A和BS(A)表示A的表面像素任意v到S(A)的最短距离定义为:
.. math::
{\text{dis}}\left (v, S(A)\right ) = \underset{s_{A} \in S(A)}{\text{min }}\rVert v - s_{A} \rVert
从集合B到集合A的平均表面距离(Average Surface Distance)为:
.. math::
AvgSurDis(B \rightarrow A) = \frac{\sum_{s_{B} \in S(B)}^{} {\text{dis} \left
( s_{B}, S(A) \right )} } {\left | S(B) \right |}
其中 \|\|\*\|\| 表示距离度量。 \|\*\| 表示元素的数量。
从集合B到集合A以及从集合A到集合B的表面距离平均值为
.. math::
MeanSurDis(A \leftrightarrow B) = \frac{\sum_{s_{A} \in S(A)}^{} {\text{dis} \left ( s_{A}, S(B) \right )}
+ \sum_{s_{B} \in S(B)}^{} {\text{dis} \left ( s_{B}, S(A) \right )} }{\left | S(A) \right | +
\left | S(B) \right |}
**参数:**
- **distance_metric** (string) - 支持如下三种距离计算方法:"euclidean"、"chessboard"或"taxicab"。默认值:"euclidean"。
- **symmetric** (bool) - 是否计算 `y_pred``y` 之间的对称平均平面距离。如果为False计算方式为 :math:`AvgSurDis(y_pred\rightarrow y)` , 如果为True计算方式为 :math:`MeanSurDis(y_pred \leftrightarrow y)` 。默认值False。
.. py:method:: clear()
内部评估结果清零。
.. py:method:: eval()
计算平均表面距离。
**返回:**
numpy.float64计算得到的平均表面距离值。
**异常:**
- **RuntimeError** - 如果没有先调用update方法。
.. py:method:: update(*inputs)
使用 `y_pred``y``label_idx` 更新内部评估结果。
**参数:**
- **inputs** - `y_pred``y``label_idx``y_pred``y` 为Tensorlist或numpy.ndarray`y_pred` 是预测的二值图像。`y` 是实际的二值图像。`label_idx` 数据类型为int或float表示像素点的类别值。
**异常:**
- **ValueError** - 输入的数量不等于3。
- **TypeError** - `label_idx` 的数据类型不是int或float。
- **ValueError** - `label_idx` 的值不在y_pred或y中。
- **ValueError** - `y_pred``y` 的shape不同。

View File

@ -0,0 +1,48 @@
mindspore.nn.OcclusionSensitivity
=============================================
.. py:class:: mindspore.nn.OcclusionSensitivity(pad_val=0.0, margin=2, n_batch=128, b_box=None)
用于计算神经网络对给定图像的遮挡灵敏度Occlusion Sensitivity表示了图像的哪些部分对神经网络的分类决策最重要。
遮挡敏感度是指神经网络对图像的类别预测概率如何随着图像被遮挡部分的变化而变化。遮挡敏感度值越高,意味着模型对类别预测的概率值下降越大,说明遮挡区域在神经网络的分类决策过程中越重要。
**参数:**
- **pad_val** (float) - 图像中被遮挡部分的填充值。默认值0.0。
- **margin** (Union[int, Sequence]) - 在要遮挡的像素点周围设置的长方体/立方体。默认值2。
- **n_batch** (int) - 一个batch中样本的数量。默认值128。
- **b_box** (Sequence) - 图像中目标区域的边界框(Bounding box),输出图像的大小与之一致。对每个样本的所有维度设置最小值和最大值:``[min1, max1, min2, max2,...]``。如果未设置此入参输出图像将与输入图像的大小一致如果设置此入参输出图像将被裁剪为此大小。默认值None。
.. py:method:: clear()
内部评估结果清零。
.. py:method:: eval()
计算遮挡敏感度。
**返回:**
numpy ndarray。计算得到的遮挡敏感度值。
**异常:**
- **RuntimeError** - 如果没有先调用update方法则会报错。
.. py:method:: update(*inputs)
更新inputs包括 `model``y_pred``label`
**参数:**
- **inputs** - `y_pred``label` 为Tensorlist或numpy.ndarray`y_pred` 是要测试的图像一般为2D或3D`label` 是用于检测神经网络预测值变化的类别标签,通常情况下为真实标签。`model` 为神经网络模型。
**异常:**
- **ValueError** - 输入数量不是3。
- **RuntimeError** - `y_pred.shape[0]` 不是1。
- **RuntimeError** - 标签数量与batch数量不同。

View File

@ -0,0 +1,24 @@
mindspore.nn.ParameterUpdate
=========================================
.. py:class:: mindspore.nn.ParameterUpdate(param)
更新参数的Cell。
使用输入的 `Tensor` 值更新 `param` 的值。
**参数:**
- **param** (Parameter) - 输入的参数。
**输入:**
- **x** Tensor- shape和类型与 `param` 相同的Tensor。
**输出:**
Tensor输入 `x`
**异常:**
- **KeyError** - 指定名称的参数不存在。

View File

@ -0,0 +1,44 @@
mindspore.nn.Perplexity
===========================
.. py:class:: mindspore.nn.Perplexity(ignore_label=None)
计算困惑度perplexity。困惑度是衡量一个概率分布或语言模型好坏的标准。低困惑度表明语言模型可以很好地预测样本。计算方式如下
.. math::
PP(W)=P(w_{1}w_{2}...w_{N})^{-\frac{1}{N}}=\sqrt[N]{\frac{1}{P(w_{1}w_{2}...w_{N})}}
**参数:**
- **ignore_label** (int) - 计数时要忽略的无效标签的索引。如果设置为None它将包括所有条目。默认值-1。
.. py:method:: clear()
内部评估结果清零。
.. py:method:: eval()
返回当前评估结果。
**返回:**
numpy.float64计算得到的困惑度结果。
**异常:**
- **RuntimeError** - 样本量为0。
.. py:method:: update(*inputs)
使用 :math:`preds`:math:`labels` 更新内部评估结果。
**参数:**
- **inputs** - 输入 `preds``labels``preds``labels` 是Tensor、list或numpy.ndarray。 `preds` 是预测值, `labels` 是数据的标签。 `preds``labels` 的shape都是:math:`(N, C)`
**异常:**
- **ValueError** - 输入数量不是2。
- **RuntimeError** - 预测值和标签的长度不同。
- **RuntimeError** - 预测值和标签的shape不同。

View File

@ -0,0 +1,39 @@
mindspore.nn.ROC
=====================
.. py:class:: mindspore.nn.ROC(class_num=None, pos_label=None)
计算ROC曲线。适用于求解二分类和多分类问题。在多分类的情况下将基于one-vs-the-rest的方法进行计算。
**参数:**
- **class_num** (int) - 类别数。对于二分类问题此入参可以不设置。默认值None。
- **pos_label** (int) - 正类的类别值。二进制问题中默认为1多分类问题中不应设置此参数因为它将在[0,num_classes-1]范围内迭代更改。默认值None。
.. py:method:: clear()
内部评估结果清零。
.. py:method:: eval()
计算ROC曲线。
**返回:**
tuple`fpr``tpr``thresholds` 组成。
- **fpr** (np.array) - 假正率。二分类情况下返回不同阈值下的fpr多分类情况下则为fpr的列表列表的每个元素代表一个类别。
- **tps** (np.array) - 真正率。二分类情况下返回不同阈值下的tps多分类情况下则为tps的列表列表的每个元素代表一个类别。
- **thresholds** (np.array) - 用于计算假正率和真正率的阈值。
**异常:**
- **RuntimeError** - 如果没有先调用update方法则会报错。
.. py:method:: 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,)`

View File

@ -0,0 +1,64 @@
mindspore.nn.RootMeanSquareDistance
======================================
.. py:class:: mindspore.nn.RootMeanSquareDistance(symmetric=False, distance_metric='euclidean')
计算从 `y_pred``y` 的均方根表面距离。
给定两个集合A和BS(A)表示A的表面像素任意v到S(A)的最短距离定义为:
.. math::
{\text{dis}}\left (v, S(A)\right ) = \underset{s_{A} \in S(A)}{\text{min }}\rVert v - s_{A} \rVert
从集合B到集合A的均方根表面距离(Root Mean Square Surface Distance)为:
.. math::
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 |}}
其中 \|\|\*\|\| 表示距离度量。 \|\*\| 表示元素的数量。
从集合B到集合A以及从集合A到集合B的表面距离平均值为
.. math::
RmsSurDis(A \leftrightarrow B) = \sqrt{\frac{\sum_{s_{A} \in S(A)}^{} {\text{dis} \left ( s_{A},
S(B) \right ) ^{2}} + \sum_{s_{B} \in S(B)}^{} {\text{dis} \left ( s_{B}, S(A) \right ) ^{2}}}{\left | S(A)
\right | + \left | S(B) \right |}}
**参数:**
- **distance_metric** (string) - 支持如下三种距离计算方法:"euclidean"、"chessboard" 或 "taxicab"。默认值:"euclidean"。
- **symmetric** (bool) - 是否计算 `y_pred``y` 之间的对称平均平面距离。如果为False计算方式为 :math:`RmsSurDis(y_pred, y)`, 如果为True计算方式为 :math:`RmsSurDis(y_pred \leftrightarrow y)`。默认值False。
.. py:method:: clear()
内部评估结果清零。
.. py:method:: eval()
计算均方根表面距离。
**返回:**
numpy.float64计算得到的均方根表面距离值。
**异常:**
- **RuntimeError** - 如果没有先调用update方法则会报错。
.. py:method:: update(*inputs)
使用 `y_pred``y``label_idx` 更新内部评估结果。
**参数:**
- **inputs** - `y_pred``y``label_idx``y_pred``y` 为Tensorlist或numpy.ndarray`y_pred` 是预测的二值图像。`y` 是实际的二值图像。`label_idx` 数据类型为int或float表示像素点的类别值。
**异常:**
- **ValueError** - 输入的数量不等于3。
- **TypeError** - `label_idx` 的数据类型不是int或float。
- **ValueError** - `label_idx` 的值不在y_pred或y中。
- **ValueError** - `y_pred``y` 的shape不同。

View File

@ -73,7 +73,7 @@ class HausdorffDistance(Metric):
\begin{array}{ll} \\
H(A, B) = \text{max}[h(A, B), h(B, A)]\\
h(A, B) = \underset{a \in A}{\text{max}}\{\underset{b \in B}{\text{min}} \rVert a - b \rVert \}\\
h(A, B) = \underset{b \in B}{\text{max}}\{\underset{a \in A}{\text{min}} \rVert b - a \rVert \}
h(B, A) = \underset{b \in B}{\text{max}}\{\underset{a \in A}{\text{min}} \rVert b - a \rVert \}
\end{array}
where h(A,B) is the maximum distance of a set A to the nearest point in the set B, h(B,A) is the maximum distance

View File

@ -28,13 +28,13 @@ class MeanSurfaceDistance(Metric):
to S(A) is defined as:
.. math::
{\text{dis}}\left (v, S(A)\right ) = \underset{s_{A} \in S(A)}{\text{min }}\rVert v - s_{A} \rVert \
{\text{dis}}\left (v, S(A)\right ) = \underset{s_{A} \in S(A)}{\text{min }}\rVert v - s_{A} \rVert
The Average Surface Distance from set(B) to set(A) is given by:
.. math::
AvgSurDis(B\rightarrow A) = \frac{\sum_{s_{B} \in S(B)}^{} {\text{dis} \
left ( s_{B}, S(A) \right )} } {\left | S(B) \right |}
AvgSurDis(B \rightarrow A) = \frac{\sum_{s_{B} \in S(B)}^{} {\text{dis} \left
( s_{B}, S(A) \right )} } {\left | S(B) \right |}
Where the \|\|\*\|\| denotes a distance measure. \|\*\| denotes the number of elements.
@ -51,7 +51,7 @@ class MeanSurfaceDistance(Metric):
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 from `y_pred` to `y` and from `y` to `y_pred`, i.e.
:math:`MeanSurDis(A \leftrightarrow B)`, will be returned. Default: False.
:math:`MeanSurDis(y_pred \leftrightarrow y)`, will be returned. Default: False.
Supported Platforms:
``Ascend`` ``GPU`` ``CPU``

View File

@ -136,10 +136,11 @@ class OcclusionSensitivity(Metric):
`y_pred`: a batch of images to test, which could be 2D or 3D.
`label`: classification labels to check for changes. `label` is normally the true label, but
doesn't have to be.
`model` is the neural network.
Raises:
ValueError: If the number of inputs is not 3.
RuntimeError: If the batch size is not 1.
RuntimeError: If y_pred.shape[0] is not 1.
RuntimeError: If the number of labels is different from the number of batches.
"""
if len(inputs) != 3:

View File

@ -50,7 +50,7 @@ class RootMeanSquareDistance(Metric):
symmetric (bool): Whether to calculate the symmetric average root mean square distance between
y_pred and y. If False, only calculates :math:`RmsSurDis(y_pred, y)` surface distance,
otherwise, the mean of distance from `y_pred` to `y` and from `y` to `y_pred`, i.e.
:math:`RmsSurDis(A \leftrightarrow B)` will be returned. Default: False.
:math:`RmsSurDis(y_pred \leftrightarrow y)` will be returned. Default: False.
Supported Platforms:
``Ascend`` ``GPU`` ``CPU``

View File

@ -45,18 +45,27 @@ class Adagrad(Optimizer):
<https://proceedings.neurips.cc/paper/2009/file/621bf66ddb7c962aa0d22ac97d69b793-Paper.pdf>`_.
Adagrad can adaptively assign different learning rates to each parameter in response to the uneven number of
samples for different parameters.
The updating formulas are as follows,
The updating Pseudo codes are as follows,
.. math::
\begin{array}{ll} \\
h_{t+1} = h_{t} + g*g\\
w_{t+1} = w_{t} - lr*\frac{1}{\sqrt{h_{t+1}}}*g
\end{array}
:math:`h` represents the cumulative sum of gradient squared,
:math:`g` represents `grads`,
:math:`lr` represents `learning_rate`,
:math:`w` represents `params`.
\begin{aligned}
&\rule{110mm}{0.4pt} \\
&\textbf{Input} : lr \text{ (learning rate)}, \: w_0 \text{ (params)}, \: f(w)
\text{ (objective)}, \: \lambda \text{ (weight decay)}, \\
&\hspace{12mm} accum \text{ (initial accumulator value)} \\
&\textbf{Initialize} : state\_sum_0 \leftarrow 0.1 \\[-1.ex]
&\rule{110mm}{0.4pt} \\
&\textbf{for} \: t=1 \: \textbf{to} \: \ldots \: \textbf{do} \\
&\hspace{5mm}g_t \leftarrow \nabla_{w} f_t (w_{t-1}) \\
&\hspace{5mm} \textbf{if} \: \lambda \neq 0 \\
&\hspace{10mm} g_t \leftarrow g_t + \lambda w_{t-1} \\
&\hspace{5mm}state\_sum_t \leftarrow state\_sum_{t-1} + g^2_t \\
&\hspace{5mm}w_t \leftarrow
w_{t-1}- lr \frac{g_t}{\sqrt{state\_sum_t}} \\
&\rule{110mm}{0.4pt} \\[-1.ex]
&\bf{return} \: w_t \\[-1.ex]
&\rule{110mm}{0.4pt} \\[-1.ex]
\end{aligned}
Note:
If parameters are not grouped, the `weight_decay` in optimizer will be applied on the network parameters without

View File

@ -370,16 +370,13 @@ class GetNextSingleOp(Cell):
"""
Cell to run for getting the next operation.
For detailed information, refer to `ops.operations.GetNext`.
For detailed information, refer to `mindspore.ops.GetNext`.
Args:
dataset_types (list[:class:`mindspore.dtype`]): The types of dataset.
dataset_shapes (list[tuple[int]]): The shapes of dataset.
queue_name (str): Queue name to fetch the data.
Inputs:
No inputs.
Outputs:
tuple[Tensor], the data get from Dataset.