Add ipynb tutorial for text summaries (#4718)

docs/text_summaries.ipynb

@@ -0,0 +1,334 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "djUvWu41mtXa"
+      },
+      "source": [
+        "##### Copyright 2021 The TensorFlow Authors."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 1,
+      "metadata": {
+        "cellView": "form",
+        "id": "su2RaORHpReL"
+      },
+      "outputs": [],
+      "source": [
+        "#@title Licensed under the Apache License, Version 2.0 (the \"License\");\n",
+        "# you may not use this file except in compliance with the License.\n",
+        "# You may obtain a copy of the License at\n",
+        "#\n",
+        "# https://www.apache.org/licenses/LICENSE-2.0\n",
+        "#\n",
+        "# Unless required by applicable law or agreed to in writing, software\n",
+        "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
+        "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
+        "# See the License for the specific language governing permissions and\n",
+        "# limitations under the License."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "NztQK2uFpXT-"
+      },
+      "source": [
+        "# Displaying text data in TensorBoard\n",
+        "\n",
+        "<table class=\"tfo-notebook-buttons\" align=\"left\">\n",
+        "  <td>\n",
+        "    <a target=\"_blank\" href=\"https://www.tensorflow.org/tensorboard/text_summaries\"><img src=\"https://www.tensorflow.org/images/tf_logo_32px.png\" />View on TensorFlow.org</a>\n",
+        "  </td>\n",
+        "  <td>\n",
+        "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/tensorflow/tensorboard/blob/master/docs/text_summaries.ipynb\"><img src=\"https://www.tensorflow.org/images/colab_logo_32px.png\" />Run in Google Colab</a>\n",
+        "  </td>\n",
+        "  <td>\n",
+        "    <a target=\"_blank\" href=\"https://github.com/tensorflow/tensorboard/blob/master/docs/text_summaries.ipynb\"><img src=\"https://www.tensorflow.org/images/GitHub-Mark-32px.png\" />View source on GitHub</a>\n",
+        "  </td>\n",
+        "</table>"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "eDXRFe_qp5C3"
+      },
+      "source": [
+        "## Overview\n",
+        "\n",
+        "Using the **TensorFlow Text Summary API,** you can easily log arbitrary text and view it in TensorBoard. This can be extremely helpful to sample and examine your input data, or to record execution metadata or generated text.  You can also log diagnostic data as text that can be helpful in the course of your model development.\n",
+        "\n",
+        "In this tutorial, you will try out some basic use cases of the Text Summary API."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "dG-nnZK9qW9z"
+      },
+      "source": [
+        "## Setup"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 2,
+      "metadata": {
+        "id": "3U5gdCw_nSG3"
+      },
+      "outputs": [],
+      "source": [
+        "try:\n",
+        "  # %tensorflow_version only exists in Colab.\n",
+        "  %tensorflow_version 2.x\n",
+        "except Exception:\n",
+        "  pass\n",
+        "\n",
+        "# Load the TensorBoard notebook extension.\n",
+        "%load_ext tensorboard"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 3,
+      "metadata": {
+        "id": "1qIKtOBrqc9Y"
+      },
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "TensorFlow version:  2.5.0-dev20210219\n"
+          ]
+        }
+      ],
+      "source": [
+        "import tensorflow as tf\n",
+        "\n",
+        "from datetime import datetime\n",
+        "import json\n",
+        "from packaging import version\n",
+        "import tempfile\n",
+        "\n",
+        "print(\"TensorFlow version: \", tf.__version__)\n",
+        "assert version.parse(tf.__version__).release[0] >= 2, \\\n",
+        "    \"This notebook requires TensorFlow 2.0 or above.\""
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "qNsjMY0364j4"
+      },
+      "source": [
+        "## Logging a single piece of text\n",
+        "\n",
+        "To understand how the Text Summary API works, you're going to simply log a bit of text and see how it is presented in TensorBoard.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 4,
+      "metadata": {
+        "id": "FxMPcdmvBn9t"
+      },
+      "outputs": [],
+      "source": [
+        "my_text = \"Hello world! 😃\""
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 5,
+      "metadata": {
+        "id": "IJNpyVyxbVtT"
+      },
+      "outputs": [],
+      "source": [
+        "# Clear out any prior log data.\n",
+        "!rm -rf logs\n",
+        "\n",
+        "# Sets up a timestamped log directory.\n",
+        "logdir = \"logs/text_basics/\" + datetime.now().strftime(\"%Y%m%d-%H%M%S\")\n",
+        "# Creates a file writer for the log directory.\n",
+        "file_writer = tf.summary.create_file_writer(logdir)\n",
+        "\n",
+        "# Using the file writer, log the text.\n",
+        "with file_writer.as_default():\n",
+        "  tf.summary.text(\"first_text\", my_text, step=0)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "rngALbRogXe6"
+      },
+      "source": [
+        "Now, use TensorBoard to examine the text. Wait a few seconds for the UI to spin up."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 6,
+      "metadata": {
+        "id": "T_X-wIy-lD9f"
+      },
+      "outputs": [],
+      "source": [
+        "%tensorboard --logdir logs"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "c8n8YqGlT3-c"
+      },
+      "source": [
+        "<!-- <img class=\"tfo-display-only-on-site\" src=\"https://github.com/tensorflow/tensorboard/blob/master/docs/images/images_single.png?raw=1\"/> -->"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "34enxJjjgWi7"
+      },
+      "source": [
+        "## Organizing multiple text streams\n",
+        "\n",
+        "If you have multiple streams of text, you can keep them in separate namespaces to help organize them, just like scalars or other data.\n",
+        "\n",
+        "Note that if you log text at many steps, TensorBoard will subsample the steps to display so as to make the presentation manageable.  You can control the sampling rate using the `--samples_per_plugin` flag."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 7,
+      "metadata": {
+        "id": "dda6960f0119"
+      },
+      "outputs": [],
+      "source": [
+        "# Sets up a second directory to not overwrite the first one.\n",
+        "logdir = \"logs/multiple_texts/\" + datetime.now().strftime(\"%Y%m%d-%H%M%S\")\n",
+        "# Creates a file writer for the log directory.\n",
+        "file_writer = tf.summary.create_file_writer(logdir)\n",
+        "\n",
+        "# Using the file writer, log the text.\n",
+        "with file_writer.as_default():\n",
+        "  with tf.name_scope(\"name_scope_1\"):\n",
+        "    for step in range(20):\n",
+        "      tf.summary.text(\"a_stream_of_text\", f\"Hello from step {step}\", step=step)\n",
+        "      tf.summary.text(\"another_stream_of_text\", f\"This can be kept separate {step}\", step=step)\n",
+        "  with tf.name_scope(\"name_scope_2\"):\n",
+        "    tf.summary.text(\"just_from_step_0\", \"This is an important announcement from step 0\", step=0)\n",
+        "    "
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 14,
+      "metadata": {
+        "id": "515199f4b547"
+      },
+      "outputs": [],
+      "source": [
+        "%tensorboard --logdir logs/multiple_texts --samples_per_plugin 'text=5'"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "bjACE1lAsqUd"
+      },
+      "source": [
+        "## Markdown interpretation\n",
+        "\n",
+        "TensorBoard interprets text summaries as Markdown, since rich formatting can make the data you log easier to read and understand, as shown below. (If you don't want Markdown interpretation, see [this issue](https://github.com/tensorflow/tensorboard/issues/830) for workarounds to suppress interpretation.)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 9,
+      "metadata": {
+        "id": "iHUjCXbetIpb"
+      },
+      "outputs": [],
+      "source": [
+        "# Sets up a third timestamped log directory under \"logs\"\n",
+        "logdir = \"logs/markdown/\" + datetime.now().strftime(\"%Y%m%d-%H%M%S\")\n",
+        "# Creates a file writer for the log directory.\n",
+        "file_writer = tf.summary.create_file_writer(logdir)\n",
+        "\n",
+        "some_obj_worth_noting = {\n",
+        "  \"tfds_training_data\": {\n",
+        "      \"name\": \"mnist\",\n",
+        "      \"split\": \"train\",\n",
+        "      \"shuffle_files\": \"True\",\n",
+        "  },\n",
+        "  \"keras_optimizer\": {\n",
+        "      \"name\": \"Adagrad\",\n",
+        "      \"learning_rate\": \"0.001\",\n",
+        "      \"epsilon\": 1e-07,\n",
+        "  },\n",
+        "  \"hardware\": \"Cloud TPU\",\n",
+        "}\n",
+        "\n",
+        "\n",
+        "# TODO: Update this example when TensorBoard is released with\n",
+        "# https://github.com/tensorflow/tensorboard/pull/4585\n",
+        "# which supports fenced codeblocks in Markdown.\n",
+        "def pretty_json(hp):\n",
+        "  json_hp = json.dumps(hp, indent=2)\n",
+        "  return \"\".join(\"\\t\" + line for line in json_hp.splitlines(True))\n",
+        "\n",
+        "markdown_text = \"\"\"\n",
+        "### Markdown Text\n",
+        "\n",
+        "TensorBoard supports basic markdown syntax, including:\n",
+        "\n",
+        "    preformatted code\n",
+        "\n",
+        "**bold text**\n",
+        "\n",
+        "| and | tables |\n",
+        "| ---- | ---------- |\n",
+        "| among | others |\n",
+        "\"\"\"\n",
+        "\n",
+        "with file_writer.as_default():\n",
+        "  tf.summary.text(\"run_params\", pretty_json(some_obj_worth_noting), step=0)\n",
+        "  tf.summary.text(\"markdown_jubiliee\", markdown_text, step=0)\n",
+        "    "
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 10,
+      "metadata": {
+        "id": "57082d8d6839"
+      },
+      "outputs": [],
+      "source": [
+        "%tensorboard --logdir logs/markdown"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "collapsed_sections": [],
+      "name": "text_summaries.ipynb",
+      "toc_visible": true
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "name": "python3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}