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

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"""Text summaries and TensorFlow operations to create them, V2 versions.""" 

16 

17 

18import numpy as np 

19 

20from tensorboard.compat import tf2 as tf 

21from tensorboard.compat.proto import summary_pb2 

22from tensorboard.plugins.text import metadata 

23from tensorboard.util import tensor_util 

24 

25 

26def text(name, data, step=None, description=None): 

27 r"""Write a text summary. 

28 

29 See also `tf.summary.scalar`, `tf.summary.SummaryWriter`, `tf.summary.image`. 

30 

31 Writes text Tensor values for later visualization and analysis in TensorBoard. 

32 Writes go to the current default summary writer. Like `tf.summary.scalar` 

33 points, text points are each associated with a `step` and a `name`. 

34 All the points with the same `name` constitute a time series of text values. 

35 

36 For Example: 

37 ```python 

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

39 with test_summary_writer.as_default(): 

40 tf.summary.text('first_text', 'hello world!', step=0) 

41 tf.summary.text('first_text', 'nice to meet you!', step=1) 

42 ``` 

43 

44 The text summary can also contain Markdown, and TensorBoard will render the text 

45 as such. 

46 

47 ```python 

48 with test_summary_writer.as_default(): 

49 text_data = ''' 

50 | *hello* | *there* | 

51 |---------|---------| 

52 | this | is | 

53 | a | table | 

54 ''' 

55 text_data = '\n'.join(l.strip() for l in text_data.splitlines()) 

56 tf.summary.text('markdown_text', text_data, step=0) 

57 ``` 

58 

59 Since text is Tensor valued, each text point may be a Tensor of string values. 

60 rank-1 and rank-2 Tensors are rendered as tables in TensorBoard. For higher ranked 

61 Tensors, you'll see just a 2D slice of the data. To avoid this, reshape the Tensor 

62 to at most rank-2 prior to passing it to this function. 

63 

64 Demo notebook at 

65 ["Displaying text data in TensorBoard"](https://www.tensorflow.org/tensorboard/text_summaries). 

66 

67 Arguments: 

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

69 be this name prefixed by any active name scopes. 

70 data: A UTF-8 string Tensor value. 

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

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

73 not be None. 

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

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

76 

77 Returns: 

78 True on success, or false if no summary was emitted because no default 

79 summary writer was available. 

80 

81 Raises: 

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

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

84 """ 

85 summary_metadata = metadata.create_summary_metadata( 

86 display_name=None, description=description 

87 ) 

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

89 summary_scope = ( 

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

91 or tf.summary.summary_scope 

92 ) 

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

94 tf.debugging.assert_type(data, tf.string) 

95 return tf.summary.write( 

96 tag=tag, tensor=data, step=step, metadata=summary_metadata 

97 ) 

98 

99 

100def text_pb(tag, data, description=None): 

101 """Create a text tf.Summary protobuf. 

102 

103 Arguments: 

104 tag: String tag for the summary. 

105 data: A Python bytestring (of type bytes), a Unicode string, or a numpy data 

106 array of those types. 

107 description: Optional long-form description for this summary, as a `str`. 

108 Markdown is supported. Defaults to empty. 

109 

110 Raises: 

111 TypeError: If the type of the data is unsupported. 

112 

113 Returns: 

114 A `tf.Summary` protobuf object. 

115 """ 

116 try: 

117 tensor = tensor_util.make_tensor_proto(data, dtype=np.object_) 

118 except TypeError as e: 

119 raise TypeError("tensor must be of type string", e) 

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) 

125 return summary