fhieber commented on a change in pull request #10139: [REQUEST FOR REVIEW] [MXNET-109] Logging APIs for Visualizing MXNet Data in TensorBoard URL: https://github.com/apache/incubator-mxnet/pull/10139#discussion_r175684744
########## File path: docs/api/python/contrib/summary.md ########## @@ -0,0 +1,258 @@ +# Logging MXNet Data for Visualization in TensorBoard + +## Overview + +The module `mxnet.contrib.summary` enables MXNet users to visualize data in +[TensorBoard](https://www.tensorflow.org/programmers_guide/summaries_and_tensorboard). +Please note that this module only provides the APIs for data logging. For visualization, +users still need to install TensorBoard. + +### How to install TensorBoard +To launch TensorBoard for visualization, make sure you have the +[official release of TensorBoard](https://pypi.python.org/pypi/tensorboard) installed. +You can type `pip install tensorboard` on you machine to install TensorBoard. + +### How to launch TensorBoard +After you installed the TensorBoar Python package, type the following command in the terminal +to launch TensorBoard: +``` +tensorborad --logdir=/path/to/your/log/dir --host=your_host_ip --port=your_port_number +``` +As an example of visualizing data using the browser on your machine, you can type +``` +tensorborad --logdir=/path/to/your/log/dir --host=127.0.0.1 --port=8888 +``` +Then in the browser, type address `127.0.0.1:8888`. Note that in some situations, +the port number `8888` may be occupied by other applications and launching TensorBoard +may fail. You may choose a different port number that is available in those situations. + + +### How to use TensorBoard GUI for data visualization +Please find the tutorials on +[TensorFlow website](https://www.tensorflow.org/programmers_guide/summaries_and_tensorboard) for details. + +### What are other required packages for using the MXNet logging APIs +Please make sure the following Python packages have been installed before using +the MXNet logging APIs: +- [protobuf](https://pypi.python.org/pypi/protobuf) +- [six](https://pypi.python.org/pypi/six) +- [PIL](https://pypi.python.org/pypi/PIL) + + +### What data types in TensorBoard GUI are supported by MXNet logging APIs +We currently support the following data types that you can find on the TensorBoard GUI: +- SCALARS +- IMAGES +- HISTOGRAMS +- PROJECTOR ([EMBEDDINGS VISUALIZATION](https://www.tensorflow.org/programmers_guide/embedding)) +- AUDIO +- TEXT +- PR CURVES + +```eval_rst +.. warning:: This package contains experimental APIs and may change in the near future. +``` + +The `summary` module provides the logging APIs through the `SummaryWriter` class. + +```eval_rst +.. autosummary:: + :nosignatures: + + mxnet.contrib.summary.SummaryWriter + mxnet.contrib.summary.SummaryWriter.add_audio + mxnet.contrib.summary.SummaryWriter.add_embedding + mxnet.contrib.summary.SummaryWriter.add_histogram + mxnet.contrib.summary.SummaryWriter.add_image + mxnet.contrib.summary.SummaryWriter.add_pr_curve + mxnet.contrib.summary.SummaryWriter.add_scalar + mxnet.contrib.summary.SummaryWriter.add_text + mxnet.contrib.summary.SummaryWriter.close + mxnet.contrib.summary.SummaryWriter.flush + mxnet.contrib.summary.SummaryWriter.get_logdir + mxnet.contrib.summary.SummaryWriter.reopen +``` + +## Examples +Let's take a look at several simple examples demonstrating how to use the MXNet logging APIs. + +### Scalar +Scalar values are often plotted in terms of curves, such as training accuracy as time evolves. Here +is an example of plotting the curve of `y=sin(x/100)` where `x` is in the range of `[0, 2*pi]`. +```python +import numpy as np +from mxnet.contrib.summary import SummaryWriter + +x_vals = np.arange(start=0, stop=2 * np.pi, step=0.01) +y_vals = np.sin(x_vals) +with SummaryWriter(logdir='./logs') as sw: + for x, y in zip(x_vals, y_vals): + sw.add_scalar(tag='sin_function_curve', value=y, global_step=x * 100) +``` + + + +### Histogram +We can visulize the value distributions of tensors by logging `NDArray`s in terms of histograms. Review comment: typo: visualize ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
