!63 add comments, optimize histogram log generator to record max and min

Merge pull request !63 from wenkai/wk0422_2

mindinsight/datavisual/data_transform/histogram_container.py

@@ -120,6 +120,13 @@ class HistogramContainer:
 
         It's caller's duty to ensure input is valid.
 
+        Why we need visual range for histograms? Miss aligned buckets between steps might miss-lead users about the
+        trend of a tensor. Because for given tensor, if you have thinner buckets, count of every bucket might get
+        low, however, if you have thicker buckets, count of every bucket might get high.  If there are the above two
+        kinds of histogram in one graph, user might think the histogram with thicker buckets has more values. This is
+        miss-leading. So we need to unify buckets across steps. Visual range for histogram is a technology for unifying
+        buckets.
+
         Args:
             max_val (float): Max value for visual histogram.
             min_val (float): Min value for visual histogram.

mindinsight/datavisual/data_transform/reservoir.py

@@ -172,6 +172,10 @@ class HistogramReservoir(Reservoir):
                 max_count = max(histogram.count, max_count)
                 visual_range.update(histogram.max, histogram.min)
 
+            if visual_range.max == visual_range.min and not max_count:
+                logger.warning("Max equals to min, however, count is zero. Please check mindspore "
+                               "does write max and min values to histogram summary file.")
+
             bins = calc_histogram_bins(max_count)
 
             # update visual range

tests/utils/log_generators/histogram_log_generator.py

@@ -62,6 +62,9 @@ class HistogramLogGenerator(LogGenerator):
             bucket.width = width
             bucket.count = count
 
+        value.histogram.min = values.get("min", -1)
+        value.histogram.max = values.get("max", -1)
+
         return histogram_event
 
     def generate_log(self, file_path, steps_list, tag_name):
@@ -91,6 +94,8 @@ class HistogramLogGenerator(LogGenerator):
             buckets = []
             leftmost = list(np.random.randn(11))
             leftmost.sort()
+            min_val = leftmost[0]
+            max_val = leftmost[-1]
             for i in range(10):
                 left = leftmost[i]
                 width = leftmost[i+1] - left
@@ -98,7 +103,7 @@ class HistogramLogGenerator(LogGenerator):
                 bucket = [left, width, count]
                 buckets.append(bucket)
 
-            histogram.update({'buckets': buckets})
+            histogram.update({'buckets': buckets, "min": min_val, "max": max_val})
             histogram_metadata.append(histogram)
 
             self._write_log_one_step(file_path, histogram)