tensorflow--tensorflow/tensorflow/python/summary/tb_summary.py

# Copyright 2023 The TensorFlow Authors. All Rights Reserved.
#
# 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.
# ==============================================================================
"""Re-exports the APIs of TF2 summary that live in TensorBoard."""

from tensorflow.python.util.tf_export import tf_export

try:
  from tensorboard.summary.v2 import scalar as scalar_v2_lib  # pylint: disable=g-import-not-at-top
  TENSORBOARD_AVAILABLE = True
  del scalar_v2_lib
except ImportError:
  TENSORBOARD_AVAILABLE = False

_TENSORBOARD_NOT_INSTALLED_ERROR = (
    "TensorBoard is not installed, missing implementation for {}. "
    "Please install TensorBoard via `pip install tensorboard`."
)


class TBNotInstalledError(ImportError):
  def __init__(self, summary_api):
    self.error_message = _TENSORBOARD_NOT_INSTALLED_ERROR.format(summary_api)
    super().__init__(self.error_message)


@tf_export("summary.audio", v1=[])
def audio(
    name,
    data,
    sample_rate,
    step=None,
    max_outputs=3,
    encoding=None,
    description=None,
):
  """Write an audio summary.

  Arguments:
    name: A name for this summary. The summary tag used for TensorBoard will be
      this name prefixed by any active name scopes.
    data: A `Tensor` representing audio data with shape `[k, t, c]`, where `k`
      is the number of audio clips, `t` is the number of frames, and `c` is the
      number of channels. Elements should be floating-point values in `[-1.0,
      1.0]`. Any of the dimensions may be statically unknown (i.e., `None`).
    sample_rate: An `int` or rank-0 `int32` `Tensor` that represents the sample
      rate, in Hz. Must be positive.
    step: Explicit `int64`-castable monotonic step value for this summary. If
      omitted, this defaults to `tf.summary.experimental.get_step()`, which must
      not be None.
    max_outputs: Optional `int` or rank-0 integer `Tensor`. At most this many
      audio clips will be emitted at each step. When more than `max_outputs`
      many clips are provided, the first `max_outputs` many clips will be used
      and the rest silently discarded.
    encoding: Optional constant `str` for the desired encoding. Only "wav" is
      currently supported, but this is not guaranteed to remain the default, so
      if you want "wav" in particular, set this explicitly.
    description: Optional long-form description for this summary, as a constant
      `str`. Markdown is supported. Defaults to empty.
  Returns:
    True on success, or false if no summary was emitted because no default
    summary writer was available.
  Raises:
    ValueError: if a default writer exists, but no step was provided and
      `tf.summary.experimental.get_step()` is None.
  """
  try:
    from tensorboard.summary.v2 import audio as audio_v2  # pylint: disable=g-import-not-at-top, g-importing-member
  except ImportError as exc:
    raise TBNotInstalledError("tf.summary.audio") from exc
  return audio_v2(
      name=name,
      data=data,
      sample_rate=sample_rate,
      step=step,
      max_outputs=max_outputs,
      encoding=encoding,
      description=description,
  )


@tf_export("summary.histogram", v1=[])
def histogram(name, data, step=None, buckets=None, description=None):
  """Write a histogram summary.

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

  Writes a histogram to the current default summary writer, for later analysis
  in TensorBoard's 'Histograms' and 'Distributions' dashboards (data written
  using this API will appear in both places). Like `tf.summary.scalar` points,
  each histogram is associated with a `step` and a `name`. All the histograms
  with the same `name` constitute a time series of histograms.

  The histogram is calculated over all the elements of the given `Tensor`
  without regard to its shape or rank.

  This example writes 2 histograms:

  ```python
  w = tf.summary.create_file_writer('test/logs')
  with w.as_default():
      tf.summary.histogram("activations", tf.random.uniform([100, 50]), step=0)
      tf.summary.histogram("initial_weights", tf.random.normal([1000]), step=0)
  ```

  A common use case is to examine the changing activation patterns (or lack
  thereof) at specific layers in a neural network, over time.

  ```python
  w = tf.summary.create_file_writer('test/logs')
  with w.as_default():
  for step in range(100):
      # Generate fake "activations".
      activations = [
          tf.random.normal([1000], mean=step, stddev=1),
          tf.random.normal([1000], mean=step, stddev=10),
          tf.random.normal([1000], mean=step, stddev=100),
      ]

      tf.summary.histogram("layer1/activate", activations[0], step=step)
      tf.summary.histogram("layer2/activate", activations[1], step=step)
      tf.summary.histogram("layer3/activate", activations[2], step=step)
  ```

  Arguments:
    name: A name for this summary. The summary tag used for TensorBoard will be
      this name prefixed by any active name scopes.
    data: A `Tensor` of any shape. The histogram is computed over its elements,
      which must be castable to `float64`.
    step: Explicit `int64`-castable monotonic step value for this summary. If
      omitted, this defaults to `tf.summary.experimental.get_step()`, which must
      not be None.
    buckets: Optional positive `int`. The output will have this many buckets,
      except in two edge cases. If there is no data, then there are no buckets.
      If there is data but all points have the same value, then all buckets'
      left and right endpoints are the same and only the last bucket has nonzero
      count. Defaults to 30 if not specified.
    description: Optional long-form description for this summary, as a constant
      `str`. Markdown is supported. Defaults to empty.

  Returns:
    True on success, or false if no summary was emitted because no default
    summary writer was available.

  Raises:
    ValueError: if a default writer exists, but no step was provided and
      `tf.summary.experimental.get_step()` is None.
  """
  try:
    from tensorboard.summary.v2 import histogram as histogram_v2  # pylint: disable=g-import-not-at-top, g-importing-member
  except ImportError as exc:
    raise TBNotInstalledError("tf.summary.histogram") from exc
  return histogram_v2(
      name=name, data=data, step=step, buckets=buckets, description=description
  )


@tf_export("summary.image", v1=[])
def image(name, data, step=None, max_outputs=3, description=None):
  """Write an image summary.

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

  Writes a collection of images to the current default summary writer. Data
  appears in TensorBoard's 'Images' dashboard. Like `tf.summary.scalar` points,
  each collection of images is associated with a `step` and a `name`.  All the
  image collections with the same `name` constitute a time series of image
  collections.

  This example writes 2 random grayscale images:

  ```python
  w = tf.summary.create_file_writer('test/logs')
  with w.as_default():
    image1 = tf.random.uniform(shape=[8, 8, 1])
    image2 = tf.random.uniform(shape=[8, 8, 1])
    tf.summary.image("grayscale_noise", [image1, image2], step=0)
  ```

  To avoid clipping, data should be converted to one of the following:

  - floating point values in the range [0,1], or
  - uint8 values in the range [0,255]

  ```python
  # Convert the original dtype=int32 `Tensor` into `dtype=float64`.
  rgb_image_float = tf.constant([
    [[1000, 0, 0], [0, 500, 1000]],
  ]) / 1000
  tf.summary.image("picture", [rgb_image_float], step=0)

  # Convert original dtype=uint8 `Tensor` into proper range.
  rgb_image_uint8 = tf.constant([
    [[1, 1, 0], [0, 0, 1]],
  ], dtype=tf.uint8) * 255
  tf.summary.image("picture", [rgb_image_uint8], step=1)
  ```

  Arguments:
    name: A name for this summary. The summary tag used for TensorBoard will be
      this name prefixed by any active name scopes.
    data: A `Tensor` representing pixel data with shape `[k, h, w, c]`, where
      `k` is the number of images, `h` and `w` are the height and width of the
      images, and `c` is the number of channels, which should be 1, 2, 3, or 4
      (grayscale, grayscale with alpha, RGB, RGBA). Any of the dimensions may be
      statically unknown (i.e., `None`). Floating point data will be clipped to
      the range [0,1]. Other data types will be clipped into an allowed range
      for safe casting to uint8, using `tf.image.convert_image_dtype`.
    step: Explicit `int64`-castable monotonic step value for this summary. If
      omitted, this defaults to `tf.summary.experimental.get_step()`, which must
      not be None.
    max_outputs: Optional `int` or rank-0 integer `Tensor`. At most this many
      images will be emitted at each step. When more than `max_outputs` many
      images are provided, the first `max_outputs` many images will be used and
      the rest silently discarded.
    description: Optional long-form description for this summary, as a constant
      `str`. Markdown is supported. Defaults to empty.

  Returns:
    True on success, or false if no summary was emitted because no default
    summary writer was available.

  Raises:
    ValueError: if a default writer exists, but no step was provided and
      `tf.summary.experimental.get_step()` is None.
  """
  try:
    from tensorboard.summary.v2 import image as image_v2  # pylint: disable=g-import-not-at-top, g-importing-member
  except ImportError as exc:
    raise TBNotInstalledError("tf.summary.image") from exc
  return image_v2(
      name=name,
      data=data,
      step=step,
      max_outputs=max_outputs,
      description=description,
  )


@tf_export("summary.scalar", v1=[])
def scalar(name, data, step=None, description=None):
  """Write a scalar summary.

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

  Writes simple numeric values for later analysis in TensorBoard.  Writes go to
  the current default summary writer. Each summary point is associated with an
  integral `step` value. This enables the incremental logging of time series
  data.  A common usage of this API is to log loss during training to produce
  a loss curve.

  For example:

  ```python
  test_summary_writer = tf.summary.create_file_writer('test/logdir')
  with test_summary_writer.as_default():
      tf.summary.scalar('loss', 0.345, step=1)
      tf.summary.scalar('loss', 0.234, step=2)
      tf.summary.scalar('loss', 0.123, step=3)
  ```

  Multiple independent time series may be logged by giving each series a unique
  `name` value.

  See [Get started with
  TensorBoard](https://www.tensorflow.org/tensorboard/get_started)
  for more examples of effective usage of `tf.summary.scalar`.

  In general, this API expects that data points are logged with a monotonically
  increasing step value. Duplicate points for a single step or points logged out
  of order by step are not guaranteed to display as desired in TensorBoard.

  Arguments:
    name: A name for this summary. The summary tag used for TensorBoard will be
      this name prefixed by any active name scopes.
    data: A real numeric scalar value, convertible to a `float32` Tensor.
    step: Explicit `int64`-castable monotonic step value for this summary. If
      omitted, this defaults to `tf.summary.experimental.get_step()`, which must
      not be None.
    description: Optional long-form description for this summary, as a constant
      `str`. Markdown is supported. Defaults to empty.

  Returns:
    True on success, or false if no summary was written because no default
    summary writer was available.

  Raises:
    ValueError: if a default writer exists, but no step was provided and
      `tf.summary.experimental.get_step()` is None.
  """
  try:
    from tensorboard.summary.v2 import scalar as scalar_v2  # pylint: disable=g-import-not-at-top, g-importing-member
  except ImportError as exc:
    raise TBNotInstalledError("tf.summary.scalar") from exc
  return scalar_v2(name=name, data=data, step=step, description=description)


@tf_export("summary.text", v1=[])
def text(name, data, step=None, description=None):
  r"""Write a text summary.

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

  Writes text Tensor values for later visualization and analysis in TensorBoard.
  Writes go to the current default summary writer.  Like `tf.summary.scalar`
  points, text points are each associated with a `step` and a `name`.
  All the points with the same `name` constitute a time series of text values.

  For Example:
  ```python
  test_summary_writer = tf.summary.create_file_writer('test/logdir')
  with test_summary_writer.as_default():
      tf.summary.text('first_text', 'hello world!', step=0)
      tf.summary.text('first_text', 'nice to meet you!', step=1)
  ```

  The text summary can also contain Markdown, and TensorBoard will render the
  text
  as such.

  ```python
  with test_summary_writer.as_default():
      text_data = '''
            | *hello* | *there* |
            |---------|---------|
            | this    | is      |
            | a       | table   |
      '''
      text_data = '\n'.join(l.strip() for l in text_data.splitlines())
      tf.summary.text('markdown_text', text_data, step=0)
  ```

  Since text is Tensor valued, each text point may be a Tensor of string values.
  rank-1 and rank-2 Tensors are rendered as tables in TensorBoard.  For higher
  ranked
  Tensors, you'll see just a 2D slice of the data.  To avoid this, reshape the
  Tensor
  to at most rank-2 prior to passing it to this function.

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

  Arguments:
    name: A name for this summary. The summary tag used for TensorBoard will be
      this name prefixed by any active name scopes.
    data: A UTF-8 string Tensor value.
    step: Explicit `int64`-castable monotonic step value for this summary. If
      omitted, this defaults to `tf.summary.experimental.get_step()`, which must
      not be None.
    description: Optional long-form description for this summary, as a constant
      `str`. Markdown is supported. Defaults to empty.

  Returns:
    True on success, or false if no summary was emitted because no default
    summary writer was available.

  Raises:
    ValueError: if a default writer exists, but no step was provided and
      `tf.summary.experimental.get_step()` is None.
  """
  try:
    from tensorboard.summary.v2 import text as text_v2  # pylint: disable=g-import-not-at-top, g-importing-member
  except ImportError as exc:
    raise TBNotInstalledError("tf.summary.text") from exc
  return text_v2(name=name, data=data, step=step, description=description)