Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/tensorboard/plugins/scalar/summary_v2.py: 35%

1# Copyright 2018 The TensorFlow Authors. All Rights Reserved. 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"); 

4# you may not use this file except in compliance with the License. 

5# You may obtain a copy of the License at 

6# 

7# http://www.apache.org/licenses/LICENSE-2.0 

8# 

9# Unless required by applicable law or agreed to in writing, software 

10# distributed under the License is distributed on an "AS IS" BASIS, 

11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14# ============================================================================== 

15"""Scalar summaries and TensorFlow operations to create them, V2 versions. 

16 

17A scalar summary stores a single floating-point value, as a rank-0 

18tensor. 

19""" 

20 

21 

22import numpy as np 

23 

24from tensorboard.compat import tf2 as tf 

25from tensorboard.compat.proto import summary_pb2 

26from tensorboard.plugins.scalar import metadata 

27from tensorboard.util import tensor_util 

28 

29 

30def scalar(name, data, step=None, description=None): 

31 """Write a scalar summary. 

32 

33 See also `tf.summary.image`, `tf.summary.histogram`, `tf.summary.SummaryWriter`. 

34 

35 Writes simple numeric values for later analysis in TensorBoard. Writes go to 

36 the current default summary writer. Each summary point is associated with an 

37 integral `step` value. This enables the incremental logging of time series 

38 data. A common usage of this API is to log loss during training to produce 

39 a loss curve. 

40 

41 For example: 

42 

43 ```python 

44 test_summary_writer = tf.summary.create_file_writer('test/logdir') 

45 with test_summary_writer.as_default(): 

46 tf.summary.scalar('loss', 0.345, step=1) 

47 tf.summary.scalar('loss', 0.234, step=2) 

48 tf.summary.scalar('loss', 0.123, step=3) 

49 ``` 

50 

51 Multiple independent time series may be logged by giving each series a unique 

52 `name` value. 

53 

54 See [Get started with TensorBoard](https://www.tensorflow.org/tensorboard/get_started) 

55 for more examples of effective usage of `tf.summary.scalar`. 

56 

57 In general, this API expects that data points are logged iwth a monotonically 

58 increasing step value. Duplicate points for a single step or points logged out 

59 of order by step are not guaranteed to display as desired in TensorBoard. 

60 

61 Arguments: 

62 name: A name for this summary. The summary tag used for TensorBoard will 

63 be this name prefixed by any active name scopes. 

64 data: A real numeric scalar value, convertible to a `float32` Tensor. 

65 step: Explicit `int64`-castable monotonic step value for this summary. If 

66 omitted, this defaults to `tf.summary.experimental.get_step()`, which must 

67 not be None. 

68 description: Optional long-form description for this summary, as a 

69 constant `str`. Markdown is supported. Defaults to empty. 

70 

71 Returns: 

72 True on success, or false if no summary was written because no default 

73 summary writer was available. 

74 

75 Raises: 

76 ValueError: if a default writer exists, but no step was provided and 

77 `tf.summary.experimental.get_step()` is None. 

78 """ 

79 summary_metadata = metadata.create_summary_metadata( 

80 display_name=None, description=description 

81 ) 

82 # TODO(https://github.com/tensorflow/tensorboard/issues/2109): remove fallback 

83 summary_scope = ( 

84 getattr(tf.summary.experimental, "summary_scope", None) 

85 or tf.summary.summary_scope 

86 ) 

87 with summary_scope(name, "scalar_summary", values=[data, step]) as (tag, _): 

88 tf.debugging.assert_scalar(data) 

89 return tf.summary.write( 

90 tag=tag, 

91 tensor=tf.cast(data, tf.float32), 

92 step=step, 

93 metadata=summary_metadata, 

94 ) 

95 

96 

97def scalar_pb(tag, data, description=None): 

98 """Create a scalar summary_pb2.Summary protobuf. 

99 

100 Arguments: 

101 tag: String tag for the summary. 

102 data: A 0-dimensional `np.array` or a compatible python number type. 

103 description: Optional long-form description for this summary, as a 

104 `str`. Markdown is supported. Defaults to empty. 

105 

106 Raises: 

107 ValueError: If the type or shape of the data is unsupported. 

108 

109 Returns: 

110 A `summary_pb2.Summary` protobuf object. 

111 """ 

112 arr = np.array(data) 

113 if arr.shape != (): 

114 raise ValueError( 

115 "Expected scalar shape for tensor, got shape: %s." % arr.shape 

116 ) 

117 if arr.dtype.kind not in ("b", "i", "u", "f"): # bool, int, uint, float 

118 raise ValueError("Cast %s to float is not supported" % arr.dtype.name) 

119 tensor_proto = tensor_util.make_tensor_proto(arr.astype(np.float32)) 

120 summary_metadata = metadata.create_summary_metadata( 

121 display_name=None, description=description 

122 ) 

123 summary = summary_pb2.Summary() 

124 summary.value.add(tag=tag, metadata=summary_metadata, tensor=tensor_proto) 

125 return summary