diff --git a/mindspore/nn/cell.py b/mindspore/nn/cell.py index 49d008f75c7..b0e10f45976 100755 --- a/mindspore/nn/cell.py +++ b/mindspore/nn/cell.py @@ -1193,7 +1193,7 @@ class Cell(Cell_): Returns an iterator over immediate cells. Returns: - Iteration, all the child cells in the cell. + Iteration, the immediate child cells in the cell. """ return self.name_cells().values() @@ -1234,7 +1234,7 @@ class Cell(Cell_): def name_cells(self): """ - Returns an iterator over all cells in the network. + Returns an iterator over all immediate cells in the network. Include name of the cell and cell itself. @@ -1588,7 +1588,7 @@ class Cell(Cell_): the parameter should use add_pipeline_stage to add it's pipeline_stage information. - If a parameter P has been used by two operators in different stages "stageA" and "stageB", the parameter P should use P.add_pipeline_stage(stageA) and P.add_pipeline_stage(stageB) - to add it's stage information before use infer_param_pipeline_stage. + to add it's stage information before using infer_param_pipeline_stage. Returns: The params belong to current stage in pipeline parallel. diff --git a/mindspore/nn/metrics/bleu_score.py b/mindspore/nn/metrics/bleu_score.py index b65489c7ce1..9b31f1b83cc 100644 --- a/mindspore/nn/metrics/bleu_score.py +++ b/mindspore/nn/metrics/bleu_score.py @@ -21,7 +21,8 @@ from .metric import Metric, rearrange_inputs class BleuScore(Metric): """ - Calculates BLEU score of machine translated text with one or more references. + Calculates the BLEU score. BLEU (bilingual evaluation understudy) is a metric for evaluating + the quality of text translated by machine. Args: n_gram (int): The n_gram value ranges from 1 to 4. Default: 4. @@ -92,12 +93,13 @@ class BleuScore(Metric): Updates the internal evaluation result with `candidate_corpus` and `reference_corpus`. Args: - inputs: Input `candidate_corpus` and `reference_corpus`. `candidate_corpus` and `reference_corpus` are a - list. The `candidate_corpus` is an iterable of machine translated corpus. The `reference_corpus` is - an iterable of iterables of reference corpus. + inputs: Input `candidate_corpus` and `reference_corpus`. `candidate_corpus` and `reference_corpus` are + both a list. The `candidate_corpus` is an iterable of machine translated corpus. The + `reference_corpus` is an iterable object of iterables of reference corpus. Raises: ValueError: If the number of inputs is not 2. + ValueError: If the lengths of `candidate_corpus` and `reference_corpus` are not equal. """ if len(inputs) != 2: raise ValueError("For 'BleuScore.update', it needs 2 inputs (candidate_corpus, reference_corpus), " @@ -137,7 +139,7 @@ class BleuScore(Metric): Computes the bleu score. Returns: - A numpy with bleu score. + numpy.float64, the bleu score. Raises: RuntimeError: If the update method is not called first, an error will be reported. diff --git a/mindspore/nn/metrics/confusion_matrix.py b/mindspore/nn/metrics/confusion_matrix.py index be631d267e6..17398e82254 100644 --- a/mindspore/nn/metrics/confusion_matrix.py +++ b/mindspore/nn/metrics/confusion_matrix.py @@ -20,24 +20,24 @@ from .metric import Metric, rearrange_inputs class ConfusionMatrix(Metric): r""" - Computes the confusion matrix. The performance matrix of measurement classification model is the model whose output - is binary or multi class. The confusion matrix is calculated. An array of shape [BC4] is returned. - The third dimension represents each channel of each sample in the input batch.Where B is the batch size and C is - the number of classes to be calculated. + Computes the confusion matrix, which is commonly used to evaluate the performance of classification models, + including binary classification and multiple classification. It returns an array of shape [BC4], where B is the + batch size and C is the number of classes to be calculated, the third dimension represents each channel of + each sample in the input batch, . - If you only want to find confusion matrix, use this class. If you want to find 'PPV', 'TPR', 'TNR', etc., use class - 'mindspore.metrics.ConfusionMatrixMetric'. + If you only need confusion matrix, use this class. If you want to calculate other metrics, such as 'PPV', + 'TPR', 'TNR', etc., use class 'mindspore.metrics.ConfusionMatrixMetric'. Args: num_classes (int): Number of classes in the dataset. - normalize (str): The parameter of calculating ConfusionMatrix supports four Normalization modes, Choose from: + normalize (str): Normalization mode for confusion matrix. Choose from: - **'no_norm'** (None) - No Normalization is used. Default: None. - **'target'** (str) - Normalization based on target value. - **'prediction'** (str) - Normalization based on predicted value. - **'all'** (str) - Normalization over the whole matrix. - threshold (float): A threshold, which is used to compare with the input tensor. Default: 0.5. + threshold (float): The threshold used to compare with the input tensor. Default: 0.5. Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` @@ -85,13 +85,14 @@ class ConfusionMatrix(Metric): Update state with y_pred and y. Args: - inputs: Input `y_pred` and `y`. `y_pred` and `y` are a `Tensor`, a list or an array. + inputs: Input `y_pred` and `y`. `y_pred` and `y` are a `Tensor`, list or numpy.ndarray. `y_pred` is the predicted value, `y` is the true value. The shape of `y_pred` is :math:`(N, C, ...)` or :math:`(N, ...)`. The shape of `y` is :math:`(N, ...)`. Raises: - ValueError: If the number of the inputs is not 2. + ValueError: If the number of inputs is not 2. + ValueError: If the lengths of `candidate_corpus` and `reference_corpus` are not equal. """ if len(inputs) != 2: raise ValueError("For 'ConfusionMatrix.update', it needs 2 inputs (predicted value, true value), " @@ -150,28 +151,26 @@ class ConfusionMatrix(Metric): class ConfusionMatrixMetric(Metric): r""" - The performance matrix of measurement classification model is the model whose output is binary or multi class. - The correlation measure of confusion matrix was calculated from the full-scale tensor, and the average values of - batch, class channel and iteration were collected. This function supports the calculation of all measures described - below: the metric name in parameter metric_name. + Computes metrics related to confusion matrix. The calculation based on full-scale tensor, average values of + batch, class channel and iteration are collected. All metrics supported by the interface are listed in comments + of `metric_name`. - If you want to use confusion matrix to calculate, such as 'PPV', 'TPR', 'TNR', use this class. + If you want to calculate metrics related to confusion matrix, such as 'PPV', 'TPR', 'TNR', use this class. If you only want to calculate confusion matrix, please use 'mindspore.metrics.ConfusionMatrix'. Args: skip_channel (bool): Whether to skip the measurement calculation on the first channel of the predicted output. Default: True. - metric_name (str): The names of indicators are in the following range. Of course, you can also set the industry - common aliases for these indicators. Choose from: - ["sensitivity", "specificity", "precision", "negative predictive value", "miss rate", + metric_name (str): Names of supported metrics , users can also set the industry common aliases for them. Choose + from: ["sensitivity", "specificity", "precision", "negative predictive value", "miss rate", "fall out", "false discovery rate", "false omission rate", "prevalence threshold", "threat score", "accuracy", "balanced accuracy", "f1 score", "matthews correlation coefficient", "fowlkes mallows index", "informedness", "markedness"]. calculation_method (bool): If true, the measurement for each sample will be calculated first. If not, the confusion matrix of all samples will be accumulated first. As for classification task, 'calculation_method' should be False. Default: False. - decrease (str): Define the mode to reduce the calculation result of one batch of data. Decrease is used only if - calculation_method is True. Default: "mean". Choose from: + decrease (str): The reduction method on data batch. `decrease` takes effect only when calculation_method + is True. Default: "mean". Choose from: ["none", "mean", "sum", "mean_batch", "sum_batch", "mean_channel", "sum_channel"]. Supported Platforms: @@ -220,23 +219,11 @@ class ConfusionMatrixMetric(Metric): Update state with predictions and targets. Args: - inputs: Input `y_pred` and `y`. `y_pred` and `y` are ndarray. - y_pred: Input data to compute. It must be one-hot format and the first dim represents batch. - The shape of `y_pred` is :math:`(N, C, ...)` or :math:`(N, ...)`. - As for classification tasks, `y_pred` should have the shape [BN] where N is larger than 1. - As for segmentation tasks, the shape should be [BNHW] or [BNHWD]. - y: Compute the true value of the measure. It must be one-hot format and first dim is batch. - The shape of `y` is :math:`(N, C, ...)`. - - inputs: - Input `y_pred` and `y`. `y_pred` and `y` are a `Tensor`, a list or an array. - - - **y_pred** (ndarray) - Input data to compute. It must be one-hot format and first dim is batch. - The shape of `y_pred` is :math:`(N, C, ...)` or :math:`(N, ...)`. - As for classification tasks, `y_pred` should have the shape [BN] where N is larger than 1. - As for segmentation tasks, the shape should be [BNHW] or [BNHWD]. - - **y** (ndarray) - Compute the true value of the measure. It must be one-hot format and first dim is batch. - The shape of `y` is :math:`(N, C, ...)`. + inputs: Input `y_pred` and `y`. `y_pred` and `y` are a `Tensor`, list or numpy.ndarray. + `y_pred`: The batch data shape is :math:`(N, C, ...)` or :math:`(N, ...)`, representing onehot format + or category index format respectively. As for classification tasks, y_pred should have the shape [BN] + where N is larger than 1. As for segmentation tasks, the shape should be [BNHW] or [BNHWD]. + `y`: It must be one-hot format. The batch data shape is :math:`(N, C, ...)`. Raises: ValueError: If the number of the inputs is not 2. diff --git a/mindspore/nn/metrics/cosine_similarity.py b/mindspore/nn/metrics/cosine_similarity.py index fb57bb3adab..09c7d5b900f 100644 --- a/mindspore/nn/metrics/cosine_similarity.py +++ b/mindspore/nn/metrics/cosine_similarity.py @@ -20,16 +20,16 @@ from .metric import Metric, rearrange_inputs class CosineSimilarity(Metric): """ - Computes representation similarity + Computes representation similarity. Args: - similarity (str): 'dot' or 'cosine'. Default: 'cosine' - reduction (str): 'none', 'sum', 'mean' (all along dim -1). Default: 'none' - zero_diagonal (bool): If true, the diagonals are set to zero. Default: True + similarity (str): 'dot' or 'cosine'. Default: 'cosine'. + reduction (str): 'none', 'sum', 'mean' (all along dim -1). Default: 'none'. + zero_diagonal (bool): If True, diagonals of results will be set to zero. Default: True. Return: - A square matrix (input1, input1) with the similarity scores between all elements. - If sum or mean is used, then returns (b, 1) with the reduced value for each row. + numpy.ndarray. A square matrix with element-wise similarity scores. If `reduction` is set to + "sum" or "mean", values of the matrix will be reduced by row. Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` @@ -67,10 +67,10 @@ class CosineSimilarity(Metric): @rearrange_inputs def update(self, inputs): """ - Updates the internal evaluation result with 'input1'. + Updates the internal evaluation result with 'inputs'. Args: - inputs: input_data `input1`. The input_data is a `Tensor` or an array. + inputs (Union[Tensor, list, numpy.ndarray]): The input matrix. """ input_data = self._convert_data(inputs) @@ -83,14 +83,13 @@ class CosineSimilarity(Metric): def eval(self): """ - Computes the Cosine_Similarity square matrix. + Computes the similarity matrix. Returns: - A square matrix. + numpy.ndarray. The similarity matrix. Raises: RuntimeError: If the update method is not called first, an error will be reported. - """ if not self._is_update: raise RuntimeError('Please call the update method before calling eval method.') diff --git a/mindspore/nn/metrics/error.py b/mindspore/nn/metrics/error.py index d185637e44b..1a672a0753f 100644 --- a/mindspore/nn/metrics/error.py +++ b/mindspore/nn/metrics/error.py @@ -27,7 +27,7 @@ class MAE(Metric): .. math:: \text{MAE} = \frac{\sum_{i=1}^n \|y_i - x_i\|}{n} - Here :math:`y_i` is the prediction and :math:`x_i` is the true value. + where :math:`n` is batch size. Note: The method `update` must be called with the form `update(y_pred, y)`. @@ -61,7 +61,7 @@ class MAE(Metric): Args: inputs: Input `y_pred` and `y` for calculating MAE where the shape of - `y_pred` and `y` are both N-D and the shape are the same. + `y_pred` and `y` are both N-D and the shape should be the same. Raises: ValueError: If the number of the input is not 2. @@ -80,7 +80,7 @@ class MAE(Metric): Computes the mean absolute error(MAE). Returns: - Float, the computed result. + numpy.float64. The computed result. Raises: RuntimeError: If the total number of samples is 0. @@ -96,7 +96,7 @@ class MSE(Metric): Measures the mean squared error(MSE). Creates a criterion that measures the MSE (squared L2 norm) between - each element in the input: :math:`x` and the target: :math:`y`. + each element in the predition and the ground truth: :math:`x` and: :math:`y`. .. math:: \text{MSE}(x,\ y) = \frac{\sum_{i=1}^n(y_i - x_i)^2}{n} @@ -130,7 +130,7 @@ class MSE(Metric): Args: inputs: Input `y_pred` and `y` for calculating the MSE where the shape of - `y_pred` and `y` are both N-D and the shape are the same. + `y_pred` and `y` are both N-D and the shape should be the same. Raises: ValueError: If the number of inputs is not 2. @@ -150,7 +150,7 @@ class MSE(Metric): Computes the mean squared error(MSE). Returns: - Float, the computed result. + numpy.float64. The computed result. Raises: RuntimeError: If the number of samples is 0. diff --git a/mindspore/nn/metrics/fbeta.py b/mindspore/nn/metrics/fbeta.py index 64625042647..0d5141cdcfa 100755 --- a/mindspore/nn/metrics/fbeta.py +++ b/mindspore/nn/metrics/fbeta.py @@ -30,7 +30,7 @@ class Fbeta(Metric): {(1+\beta^2) \cdot true\_positive +\beta^2 \cdot false\_negative + false\_positive} Args: - beta (Union[float, int]): The weight of precision. + beta (Union[float, int]): Beta coefficient in the F measure. Examples: >>> import numpy as np @@ -109,10 +109,10 @@ class Fbeta(Metric): Computes the fbeta. Args: - average (bool): Whether to calculate the average fbeta. Default value is False. + average (bool): Whether to calculate the average fbeta. Default: False. Returns: - Float, computed result. + numpy.ndarray or numpy.float64, the computed result. """ validator.check_value_type("average", average, [bool], self.__class__.__name__) if self._class_num == 0: diff --git a/mindspore/nn/metrics/hausdorff_distance.py b/mindspore/nn/metrics/hausdorff_distance.py index 468dfda0593..a06f3eda85a 100644 --- a/mindspore/nn/metrics/hausdorff_distance.py +++ b/mindspore/nn/metrics/hausdorff_distance.py @@ -70,18 +70,23 @@ class HausdorffDistance(Metric): Given two feature sets A and B, the Hausdorff distance between two point sets A and B is defined as follows: .. 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(A, B) = \underset{b \in B}{\text{max}}\{\underset{a \in A}{\text{min}} \rVert b - a \rVert \} + \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 \} + \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 + of a set B to the nearest point in the set A. The distance calculation is oriented, which means that most of times + :math: `h(A, B)` is not equal to :math: `h(B, A)`. Args: - distance_metric (string): The parameter of calculating Hausdorff distance supports three measurement methods, - "euclidean", "chessboard" or "taxicab". Default: "euclidean". + distance_metric (string): Three distance measurement methods are supported: "euclidean", "chessboard" or + "taxicab". Default: "euclidean". percentile (float): Floating point numbers between 0 and 100. Specify the percentile parameter to get the percentile of the Hausdorff distance. Default: None. - directed (bool): It can be divided into directional and non-directional Hausdorff distance, - and the default is non-directional Hausdorff distance, specify the percentile parameter to get - the percentile of the Hausdorff distance. Default: False. + directed (bool): If True, it only calculates h(y_pred, y) distance, otherwise, max(h(y_pred, y), h(y, y_pred)) + will be returned. Default: False. crop (bool): Crop input images and only keep the foregrounds. In order to maintain two inputs' shapes, here the bounding box is achieved by (y_pred | y) which represents the union set of two images. Default: True. @@ -255,15 +260,18 @@ class HausdorffDistance(Metric): @rearrange_inputs def update(self, *inputs): """ - Updates the internal evaluation result 'y_pred', 'y' and 'label_idx'. + Updates the internal evaluation result with the inputs: 'y_pred', 'y' and 'label_idx'. Args: - inputs: Input 'y_pred', 'y' and 'label_idx'. 'y_pred' and 'y' are Tensor or numpy.ndarray. 'y_pred' is the - predicted binary image. 'y' is the actual binary image. 'label_idx', the data type of `label_idx` - is int. + inputs: Input 'y_pred', 'y' and 'label_idx'. 'y_pred' and 'y' are a `Tensor`, list or + numpy.ndarray. 'y_pred' is the predicted binary image. 'y' is the actual + binary image. Data type of 'label_idx' is int or float. Raises: ValueError: If the number of the inputs is not 3. + TypeError: If the data type of label_idx is not int or float. + ValueError: If the value of label_idx is not in y_pred or y. + ValueError: If y_pred and y have different shapes. """ self._is_update = True @@ -293,7 +301,7 @@ class HausdorffDistance(Metric): Calculate the no-directed or directed Hausdorff distance. Returns: - A float with hausdorff_distance. + numpy.float64, the hausdorff distance. Raises: RuntimeError: If the update method is not called first, an error will be reported. diff --git a/mindspore/nn/metrics/loss.py b/mindspore/nn/metrics/loss.py index fad6c9c1bcc..3559509cdb0 100644 --- a/mindspore/nn/metrics/loss.py +++ b/mindspore/nn/metrics/loss.py @@ -54,7 +54,7 @@ class Loss(Metric): Raises: ValueError: If the length of inputs is not 1. - ValueError: If the dimension of loss is not 1. + ValueError: If the dimension of loss is not 1 or 0. """ if len(inputs) != 1: raise ValueError('The length of inputs must be 1, but got {}'.format(len(inputs))) @@ -76,7 +76,7 @@ class Loss(Metric): Calculates the average of the loss. Returns: - Float, the average of the loss. + numpy.float64. The average of the loss. Raises: RuntimeError: If the total number is 0. diff --git a/mindspore/nn/metrics/mean_surface_distance.py b/mindspore/nn/metrics/mean_surface_distance.py index 3faaebd5729..d8470b72c15 100644 --- a/mindspore/nn/metrics/mean_surface_distance.py +++ b/mindspore/nn/metrics/mean_surface_distance.py @@ -20,24 +20,46 @@ from .metric import Metric, rearrange_inputs class MeanSurfaceDistance(Metric): - """ - This function is used to compute the Average Surface Distance from `y_pred` to `y` under the default setting. - Mean Surface Distance(MSD), the mean of the vector is taken. This tell us how much, on average, the surface varies - between the segmentation and the GT. + r""" + Computes the Average Surface Distance from `y_pred` to `y` under the default setting. It measures how much, + on average, the surface varies between the segmentation and the GT (ground truth). + + Given two sets A and B, S(A) denotes the set of surface voxels of A. The shortest distance of an arbitrary voxel v + 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 \ + + The Average Surface Distance form 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 |} + + Where the ||*|| denotes a distance measure. |*| denotes the number of elements. + + The mean of surface distance form set(B) to set(A) and from set(A) to set(B) is: + + .. 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 |} Args: - distance_metric (string): The parameter of calculating Hausdorff distance supports three measurement methods, - "euclidean", "chessboard" or "taxicab". Default: "euclidean". - symmetric (bool): if calculate the symmetric average surface distance between `y_pred` and `y`. In addition, - if sets ``symmetric = True``, the average symmetric surface distance between these two inputs - will be returned. Default: False. + distance_metric (string): Three measurement methods are supported: "euclidean", "chessboard" or "taxicab". + 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. Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` Examples: >>> import numpy as np - >>> from mindspore import nn, Tensor + + >>> from mindspore imporst 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]])) @@ -93,9 +115,9 @@ class MeanSurfaceDistance(Metric): Updates the internal evaluation result 'y_pred', 'y' and 'label_idx'. Args: - inputs: Input 'y_pred', 'y' and 'label_idx'. 'y_pred' and 'y' are Tensor or numpy.ndarray. 'y_pred' is the - predicted binary image. 'y' is the actual binary image. 'label_idx', the data type of `label_idx` - is int. + inputs: Input 'y_pred', 'y' and 'label_idx'. 'y_pred' and 'y' are a Tensor, list or numpy.ndarray. + 'y_pred' is the predicted binary image. 'y' is the actual binary image. 'label_idx', the data + type of `label_idx` is int. Raises: ValueError: If the number of the inputs is not 3. @@ -132,7 +154,7 @@ class MeanSurfaceDistance(Metric): Calculate mean surface distance. Returns: - A float with mean surface distance. + numpy.float64. The mean surface distance value. Raises: RuntimeError: If the update method is not called first, an error will be reported. diff --git a/mindspore/nn/metrics/occlusion_sensitivity.py b/mindspore/nn/metrics/occlusion_sensitivity.py index 9ac06d01dfa..17326398565 100644 --- a/mindspore/nn/metrics/occlusion_sensitivity.py +++ b/mindspore/nn/metrics/occlusion_sensitivity.py @@ -29,19 +29,17 @@ finally: class OcclusionSensitivity(Metric): """ - This function is used to calculate the occlusion sensitivity of the model for a given image. - Occlusion sensitivity refers to how the probability of a given prediction changes with the change of the occluded - part of the image. + Calculates the occlusion sensitivity of the model for a given image. It illustrates which parts of an image are + most important for a network's classification. - For a given result, the output probability is the probability of a region. - - The higher the value in the output image is, the greater the decline of certainty, indicating that - the occluded area is more important in the decision-making process. + Occlusion sensitivity refers to how the predicted probability changes with the change of the occluded + part of an image. The higher the value in the output image is, the greater the decline of certainty, indicating + that the occluded area is more important in the decision-making process. Args: - pad_val (float): What values need to be entered in the image when a part of the image is occluded. Default: 0.0. + pad_val (float): The padding value of the occluded part in an image. Default: 0.0. margin (Union[int, Sequence]): Create a cuboid / cube around the voxel you want to occlude. Default: 2. - n_batch (int): number of images in a batch before inference. Default: 128. + n_batch (int): number of images in a batch. Default: 128. b_box (Sequence): Bounding box on which to perform the analysis. The output image will also match in size. There should be a minimum and maximum for all dimensions except batch: ``[min1, max1, min2, max2,...]``. If no bounding box is supplied, this will be the same size @@ -130,16 +128,10 @@ class OcclusionSensitivity(Metric): Updates input, including `model`, `y_pred` and `label`. Args: - inputs: Input `y_pred` and `label`. `y_pred` and `label` are Tensor, list or numpy.ndarray. - y_pred: image to test. It should be a tensor consisting of 1 batch, which could be 2D or 3D. - label: classification label to check for changes (normally the true label, but doesn't have to be. - - Inputs: - - **model** (nn.Cell) - classification model to use for inference. - - **y_pred** (Union[Tensor, list, np.ndarray]) - image to test. Should be a tensor consisting of 1 batch, - can be 2- or 3D. - - **label** (Union[int, Tensor]) - classification label to check for changes (normally the true label, - but doesn't have to be + inputs: `y_pred` and `label` are a Tensor, list or numpy.ndarray. + `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. Raises: ValueError: If the number of inputs is not 3. diff --git a/mindspore/nn/metrics/perplexity.py b/mindspore/nn/metrics/perplexity.py index c7fc3a6f1f7..dbd6795f6b8 100644 --- a/mindspore/nn/metrics/perplexity.py +++ b/mindspore/nn/metrics/perplexity.py @@ -29,7 +29,7 @@ class Perplexity(Metric): Args: ignore_label (int): Index of an invalid label to be ignored when counting. If set to `None`, it will include all - entries. Default: -1. + entries. Default: None. Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` @@ -71,8 +71,8 @@ class Perplexity(Metric): Updates the internal evaluation result: math:preds and :math:labels. Args: - inputs: Input `preds` and `labels`. `preds` and `labels` are Tensor, list or numpy.ndarray. - `preds` is the predicted values, `labels` is the label of the data. + inputs: Input `preds` and `labels`. `preds` and `labels` are a `Tensor`, list or numpy.ndarray. + `preds` is the predicted values, `labels` is the labels of the data. The shape of `preds` and `labels` are both :math:`(N, C)`. Raises: @@ -115,7 +115,7 @@ class Perplexity(Metric): Returns the current evaluation result. Returns: - float, the computed result. + numpy.float64. The computed result. Raises: RuntimeError: If the sample size is 0. diff --git a/mindspore/nn/metrics/precision.py b/mindspore/nn/metrics/precision.py index fa4378f737d..6a7c66900b3 100644 --- a/mindspore/nn/metrics/precision.py +++ b/mindspore/nn/metrics/precision.py @@ -37,8 +37,7 @@ class Precision(EvaluationBase): In the multi-label cases, the elements of :math:`y` and :math:`y_{pred}` must be 0 or 1. Args: - eval_type (str): Metric to calculate accuracy over a dataset, for classification or - multilabel. Default: 'classification'. + eval_type (str): 'classification' or 'multilabel' are supported. Default: 'classification'. Examples: >>> import numpy as np @@ -135,10 +134,10 @@ class Precision(EvaluationBase): Computes the precision. Args: - average (bool): Specify whether calculate the average precision. Default value is False. + average (bool): Specify whether calculate the average precision. Default: False. Returns: - Float, the computed result. + numpy.float64, the computed result. """ if self._class_num == 0: raise RuntimeError('The input number of samples can not be 0.') diff --git a/mindspore/nn/metrics/recall.py b/mindspore/nn/metrics/recall.py index 01eda16b222..dc41567a03b 100644 --- a/mindspore/nn/metrics/recall.py +++ b/mindspore/nn/metrics/recall.py @@ -37,8 +37,8 @@ class Recall(EvaluationBase): In the multi-label cases, the elements of :math:`y` and :math:`y_{pred}` must be 0 or 1. Args: - eval_type (str): The metric to calculate the recall over a dataset, for classification or - multilabel. Default: 'classification'. + eval_type (str): 'classification' or 'multilabel' are supported. Default: 'classification'. + Default: 'classification'. Examples: >>> import numpy as np @@ -134,10 +134,10 @@ class Recall(EvaluationBase): Computes the recall. Args: - average (bool): Specify whether calculate the average recall. Default value is False. + average (bool): Specify whether calculate the average recall. Default: False. Returns: - Float, the computed result. + numpy.float64, the computed result. """ if self._class_num == 0: raise RuntimeError('The input number of samples can not be 0.') diff --git a/mindspore/nn/metrics/roc.py b/mindspore/nn/metrics/roc.py index d255b5f103c..4bac463e299 100644 --- a/mindspore/nn/metrics/roc.py +++ b/mindspore/nn/metrics/roc.py @@ -24,11 +24,11 @@ class ROC(Metric): In the case of multiclass, the values will be calculated based on a one-vs-the-rest approach. Args: - class_num (int): Integer with the number of classes. For the problem of binary classification, it is not - necessary to provide this argument. Default: None. - pos_label (int): Determine the integer of positive class. Default: None. For binary problems, it is translated - to 1. For multiclass problems, this argument should not be set, as it is iteratively changed in the - range [0,num_classes-1]. Default: None. + class_num (int): The number of classes. It is not necessary to provide this argument under the binary + classification scenario. Default: None. + pos_label (int): Determine the integer of positive class. For binary problems, it is translated to 1 by default. + For multiclass problems, this argument should not be set, as it will + iteratively changed in the range [0,num_classes-1]. Default: None. Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` @@ -117,10 +117,11 @@ class ROC(Metric): Update state with predictions and targets. Args: - inputs: Input `y_pred` and `y`. `y_pred` and `y` are Tensor, list or numpy.ndarray. + inputs: Input `y_pred` and `y`. `y_pred` and `y` are `Tensor`, list or numpy.ndarray. In most cases (not strictly), y_pred is a list of floating numbers in range :math:`[0, 1]` and the shape is :math:`(N, C)`, where :math:`N` is the number of cases and :math:`C` - is the number of categories. y contains values of integers. + is the number of categories. y contains values of integers. The shape is :math:`(N,C)` if one-hot + encoding is used. Shape can also be :math:`(N,)` if category index is used. """ if len(inputs) != 2: raise ValueError('ROC need 2 inputs (y_pred, y), but got {}'.format(len(inputs))) @@ -192,11 +193,13 @@ class ROC(Metric): Returns: A tuple, composed of `fpr`, `tpr`, and `thresholds`. - - **fpr** (np.array) - np.array with false positive rates. If multiclass, this is a list of such np.array, - one for each class. - - **tps** (np.array) - np.array with true positive rates. If multiclass, this is a list of such np.array, - one for each class. - - **thresholds** (np.array) - thresholds used for computing false- and true positive rates. + - **fpr** (np.array) - False positive rate. In binary classification case, a fpr numpy array under different + thresholds will be returned, otherwise in multiclass case, a list of + fpr numpy arrays will be returned and each element represents one category. + - **tpr** (np.array) - True positive rates. n binary classification case, a tps numpy array under different + thresholds will be returned, otherwise in multiclass case, a list of tps numpy arrays + will be returned and each element represents one category. + - **thresholds** (np.array) - Thresholds used for computing fpr and tpr. Raises: RuntimeError: If the update method is not called first, an error will be reported. diff --git a/mindspore/nn/metrics/root_mean_square_surface_distance.py b/mindspore/nn/metrics/root_mean_square_surface_distance.py index 72210709083..bb571ed091d 100644 --- a/mindspore/nn/metrics/root_mean_square_surface_distance.py +++ b/mindspore/nn/metrics/root_mean_square_surface_distance.py @@ -20,18 +20,37 @@ from .metric import Metric, rearrange_inputs class RootMeanSquareDistance(Metric): - """ - This function is used to compute the Residual Mean Square Distance from `y_pred` to `y` under the default - setting. Residual Mean Square Distance(RMS), the mean is taken from each of the points in the vector, these - residuals are squared (to remove negative signs), summed, weighted by the mean and then the square-root is taken. - Measured in mm. + r""" + Computes the Root Mean Square Surface Distance from `y_pred` to `y` under the default setting. + + Given two sets A and B, S(A) denotes the set of surface voxels of A. The shortest distance of an + arbitrary voxel v 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 + + The Root Mean Square Surface Distance form set(B) to set(A) is: + + .. 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 |}} + + 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: + + .. 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 |}} Args: - distance_metric (string): The parameter of calculating Hausdorff distance supports three measurement methods, - "euclidean", "chessboard" or "taxicab". Default: "euclidean". - symmetric (bool): if calculate the symmetric average surface distance between `y_pred` and `y`. In addition, - if sets ``symmetric = True``, the average symmetric surface distance between these two inputs - will be returned. Default: False. + distance_metric (string): Three measurement methods are supported: + "euclidean", "chessboard" or "taxicab". Default: "euclidean". + 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 form `y_pred` to `y` and from `y` to `y_pred`, i.e. + :math:`RmsSurDis(A \leftrightarrow B)` will be returned. Default: False. Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` @@ -95,9 +114,9 @@ class RootMeanSquareDistance(Metric): Updates the internal evaluation result 'y_pred', 'y' and 'label_idx'. Args: - inputs: Input 'y_pred', 'y' and 'label_idx'. 'y_pred' and 'y' are Tensor or numpy.ndarray. 'y_pred' is the - predicted binary image. 'y' is the actual binary image. 'label_idx', the data type of `label_idx` - is int. + inputs: Input 'y_pred', 'y' and 'label_idx'. 'y_pred' and 'y' are `Tensor`, list or numpy.ndarray. + 'y_pred' is the predicted binary image. 'y' is the actual binary image. 'label_idx', the data + type of `label_idx` is int. Raises: ValueError: If the number of the inputs is not 3. @@ -131,10 +150,10 @@ class RootMeanSquareDistance(Metric): def eval(self): """ - Calculate residual mean square surface distance. + Calculate Root Mean Square Distance. Returns: - A float with residual mean square surface distance. + numpy.float64, root mean square surface distance. Raises: RuntimeError: If the update method is not called first, an error will be reported. diff --git a/mindspore/nn/metrics/topk.py b/mindspore/nn/metrics/topk.py index af52a7091d6..7c647780923 100644 --- a/mindspore/nn/metrics/topk.py +++ b/mindspore/nn/metrics/topk.py @@ -63,13 +63,13 @@ class TopKCategoricalAccuracy(Metric): @rearrange_inputs def update(self, *inputs): """ - Updates the internal evaluation result y_pred and y. + Updates the internal evaluation result `y_pred` and `y`. Args: - inputs: Input y_pred and y. y_pred and y are Tensor, list or numpy.ndarray. - y_pred is in most cases (not strictly) a list of floating numbers in range :math:`[0, 1]` + inputs: Input `y_pred` and `y`. ` y_pred` and `y` are Tensor, list or numpy.ndarray. + `y_pred` is in most cases (not strictly) a list of floating numbers in range :math:`[0, 1]` and the shape is :math:`(N, C)`, where :math:`N` is the number of cases and :math:`C` - is the number of categories. y contains values of integers. The shape is :math:`(N, C)` + is the number of categories. `y` contains values of integers. The shape is :math:`(N, C)` if one-hot encoding is used. Shape can also be :math:`(N,)` if category index is used. """ if len(inputs) != 2: @@ -90,7 +90,7 @@ class TopKCategoricalAccuracy(Metric): Computes the top-k categorical accuracy. Returns: - Float, computed result. + numpy.float64, computed result. """ if self._samples_num == 0: raise RuntimeError('The total number of samples must not be 0.')