API comment rectification of 'utils/' and 'privacy/evaluationAPI/'

mindarmour/__init__.py

@@ -1,3 +1,16 @@
+# Copyright 2020 Huawei Technologies Co., Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 """
 MindArmour, a tool box of MindSpore to enhance model trustworthiness and achieve
 privacy-preserving machine learning.

mindarmour/privacy/evaluation/inversion_attack.py

@@ -198,8 +198,11 @@ class ImageInversionAttack:
                 checkpoint file. Default: None.
 
         Returns:
-            tuple, average l2 distance, average ssim value and average confidence (if labels or new_network is None,
-            then average confidence would be None).
+            - float, l2 distance.
+
+            - float, average ssim value.
+
+            - Union[float, None], average confidence. It would be None if labels or new_network is None.
 
         Examples:
             >>> net = LeNet5()
@@ -210,7 +213,6 @@ class ImageInversionAttack:
             >>> ori_images = np.random.random((2, 1, 32, 32))
             >>> result = inversion_attack.evaluate(ori_images, inver_images)
             >>> print(len(result))
-            3
         """
         check_numpy_param('original_images', original_images)
         check_numpy_param('inversion_images', inversion_images)

mindarmour/privacy/evaluation/membership_inference.py

@@ -237,6 +237,7 @@ class MembershipInference:
         Returns:
             - numpy.ndarray, loss_logits features for each sample. Shape is (N, C).
                 N is the number of sample. C = 1 + dim(logits).
+
             - numpy.ndarray, labels for each sample, Shape is (N,).
         """
         loss_logits = np.array([])

mindarmour/utils/_check_param.py

@@ -49,7 +49,7 @@ def check_param_type(arg_name, arg_value, valid_type):
 
 
 def check_param_multi_types(arg_name, arg_value, valid_types):
-    """Check parameter type."""
+    """Check parameter multi types."""
     if not isinstance(arg_value, tuple(valid_types)):
         msg = 'type of {} must be in {}, but got {}' \
             .format(arg_name, valid_types, type(arg_value).__name__)
@@ -196,7 +196,7 @@ def check_pair_numpy_param(inputs_name, inputs, labels_name, labels):
 
 
 def check_equal_length(para_name1, value1, para_name2, value2):
-    """check weather the two parameters have equal length."""
+    """Check weather the two parameters have equal length."""
     if len(value1) != len(value2):
         msg = 'The dimension of {0} must equal to the ' \
               '{1}, but got {0} is {2}, ' \
@@ -208,7 +208,7 @@ def check_equal_length(para_name1, value1, para_name2, value2):
 
 
 def check_equal_shape(para_name1, value1, para_name2, value2):
-    """check weather the two parameters have equal shape."""
+    """Check weather the two parameters have equal shape."""
     if value1.shape != value2.shape:
         msg = 'The shape of {0} must equal to the ' \
               '{1}, but got {0} is {2}, ' \
@@ -220,9 +220,7 @@ def check_equal_shape(para_name1, value1, para_name2, value2):
 
 
 def check_norm_level(norm_level):
-    """
-    check norm_level of regularization.
-    """
+    """Check norm_level of regularization."""
     if not isinstance(norm_level, (int, str)):
         msg = 'Type of norm_level must be in [int, str], but got {}'.format(type(norm_level))
     accept_norm = [1, 2, '1', '2', 'l1', 'l2', 'inf', 'linf', np.inf]
@@ -240,7 +238,7 @@ def normalize_value(value, norm_level):
 
     Args:
         value (numpy.ndarray): Inputs.
-        norm_level (Union[int, str]): Normalized level.
+        norm_level (Union[int, str]): Normalized level. Option: [1, 2, np.inf, '1', '2', 'inf', 'l1', 'l2']
 
     Returns:
         numpy.ndarray, normalized value.
@@ -335,7 +333,7 @@ def check_detection_inputs(inputs, labels):
 
 
 def check_inputs_labels(inputs, labels):
-    """check inputs and labels is valid for white box method."""
+    """Check inputs and labels is valid for white box method."""
     _ = check_param_multi_types('inputs', inputs, (tuple, np.ndarray))
     _ = check_param_multi_types('labels', labels, (tuple, np.ndarray))
     inputs_image = inputs[0] if isinstance(inputs, tuple) else inputs

mindarmour/utils/util.py

@@ -264,7 +264,11 @@ def calculate_lp_distance(original_image, compared_image):
         compared_image (np.ndarray): Another image for comparison.
 
     Returns:
-        tuple, (l0, l2 and linf) distances between two images.
+        - float, l0 distances between two images.
+
+        - float, l2 distances between two images.
+
+        - float, linf distances between two images.
 
     Raises:
         TypeError: If type of original_image or type of compared_image is not numpy.ndarray.
@@ -319,7 +323,6 @@ def compute_ssim(image1, image2):
     Args:
         image1 (numpy.ndarray): The first image to be compared.
         image2 (numpy.ndarray): The second image to be compared.
-            channels).
 
     Returns:
         float, structural similarity.