Merge pull request #63 from leVirve-arxiv/readme

Polish the readme doc

README.md

@@ -1,32 +1,40 @@
+# tensorboardX
+
 [![Build Status](https://travis-ci.org/lanpa/tensorboard-pytorch.svg?branch=master)](https://travis-ci.org/lanpa/tensorboard-pytorch)
 [![PyPI version](https://badge.fury.io/py/tensorboardX.svg)](https://badge.fury.io/py/tensorboardX)
 [![Downloads](https://img.shields.io/badge/pip--downloads-5K+-brightgreen.svg)](https://bigquery.cloud.google.com/savedquery/966219917372:edb59a0d70c54eb687ab2a9417a778ee)
-# tensorboard-pytorch
 
-Write tensorboard events with simple function call.
+Write TensorBoard events with simple function call.
+
+* Support `scalar`, `image`, `histogram`, `audio`, `text`, `graph`, `onnx_graph`, `embedding` and `pr_curve` summaries.
+
 
-Supports scalar, image, histogram, audio, text, graph, embedding and pr_curve.
+## Demo
 
-see [demo](http:35.197.26.245:6006) (result of `demo.py` and some images generated by BEGAN)
+[demo site](http://35.197.26.245:6006) (TensorBoard for `demo.py` and some images generated by BEGAN)
+
+*If the demo code `onnx_graph.py` is not working, you have to build pytorch and onnx from source.*
 
-If the demo code `onnx_graph.py` is not working, you have to build pytorch and onnx from source.
 
 ## Install
 
-`#tested on anaconda2/anaconda3, pytorch 0.3, torchvision 0.2`
+Tested on anaconda2 / anaconda3, with PyTorch 0.3 / torchvision 0.2 / tensorflow-tensorboard 0.4
 
 `pip install tensorboardX`
 
-`pip install tensorflow` (for tensorboard web server)
-
 or build from source:
+
 `pip install git+https://github.com/lanpa/tensorboard-pytorch`
 
-## API
-http://tensorboard-pytorch.readthedocs.io/en/latest/tensorboard.html
 
-## Usage
+## Example
+
+* Run the demo script: `python demo.py`
+* Use TensorBoard with `tensorboard --logdir runs`  (needs to install TensorFlow)
+
 ```python
+# demo.py
+
 import torch
 import torchvision.utils as vutils
 import numpy as np
@@ -40,55 +48,59 @@ sample_rate = 44100
 freqs = [262, 294, 330, 349, 392, 440, 440, 440, 440, 440, 440]
 
 for n_iter in range(100):
-    s1 = torch.rand(1) # value to keep
-    s2 = torch.rand(1)
-    writer.add_scalar('data/scalar1', s1[0], n_iter) #data grouping by `slash`
-    writer.add_scalar('data/scalar2', s2[0], n_iter)
-    writer.add_scalars('data/scalar_group', {"xsinx":n_iter*np.sin(n_iter),
-                                             "xcosx":n_iter*np.cos(n_iter),
-                                             "arctanx": np.arctan(n_iter)}, n_iter)
-    x = torch.rand(32, 3, 64, 64) # output from network
-    if n_iter%10==0:
-        x = vutils.make_grid(x, normalize=True, scale_each=True)
+
+    dummy_s1 = torch.rand(1)
+    dummy_s2 = torch.rand(1)
+    # data grouping by `slash`
+    writer.add_scalar('data/scalar1', dummy_s1[0], n_iter)
+    writer.add_scalar('data/scalar2', dummy_s2[0], n_iter)
+
+    writer.add_scalars('data/scalar_group', {'xsinx': n_iter * np.sin(n_iter),
+                                             'xcosx': n_iter * np.cos(n_iter),
+                                             'arctanx': np.arctan(n_iter)}, n_iter)
+
+    dummy_img = torch.rand(32, 3, 64, 64)  # output from network
+    if n_iter % 10 == 0:
+        x = vutils.make_grid(dummy_img, normalize=True, scale_each=True)
         writer.add_image('Image', x, n_iter)
-        x = torch.zeros(sample_rate*2)
+
+        dummy_audio = torch.zeros(sample_rate * 2)
         for i in range(x.size(0)):
-            x[i] = np.cos(freqs[n_iter//10]*np.pi*float(i)/float(sample_rate)) # sound amplitude should in [-1, 1]
-        writer.add_audio('myAudio', x, n_iter, sample_rate=sample_rate)
-        writer.add_text('Text', 'text logged at step:'+str(n_iter), n_iter)
+            # amplitude of sound should in [-1, 1]
+            dummy_audio[i] = np.cos(freqs[n_iter // 10] * np.pi * float(i) / float(sample_rate))
+        writer.add_audio('myAudio', dummy_audio, n_iter, sample_rate=sample_rate)
+
+        writer.add_text('Text', 'text logged at step:' + str(n_iter), n_iter)
+
         for name, param in resnet18.named_parameters():
             writer.add_histogram(name, param.clone().cpu().data.numpy(), n_iter)
-        writer.add_pr_curve('xoxo', np.random.randint(2, size=100), np.random.rand(100), n_iter) #needs tensorboard 0.4RC or later
+
+        # needs tensorboard 0.4RC or later
+        writer.add_pr_curve('xoxo', np.random.randint(2, size=100), np.random.rand(100), n_iter)
+
 dataset = datasets.MNIST('mnist', train=False, download=True)
 images = dataset.test_data[:100].float()
 label = dataset.test_labels[:100]
+
 features = images.view(100, 784)
 writer.add_embedding(features, metadata=label, label_img=images.unsqueeze(1))
 
 # export scalar data to JSON for external processing
 writer.export_scalars_to_json("./all_scalars.json")
-
 writer.close()
 ```
 
-`python demo.py`
-
-`tensorboard --logdir runs`
-
 ## Screenshots
-<img src="screenshots/Demo.gif">
 
+<img src="screenshots/Demo.gif">
 
 ## Tweaks
-To show more images in tensorboard's image tab, just
-modify the hardcoded `event_accumulator` in
-`~/anaconda3/lib/python3.6/site-packages/tensorflow/tensorboard/backend/application.py`
-as you wish.
 
-For tensorflow-tensorboard>0.17 see https://github.com/lanpa/tensorboard-pytorch/issues/44
+To add more ticks for the slider (show more image history), you can modify the hardcoded `event_accumulator` in `~/anaconda3/lib/python3.6/site-packages/tensorflow/tensorboard/backend/application.py` as you wish.
 
-## Reference:
+For `tensorflow-tensorboard` > 0.17 see https://github.com/lanpa/tensorboard-pytorch/issues/44
 
-https://github.com/TeamHG-Memex/tensorboard_logger
+## Reference
 
-https://github.com/dmlc/tensorboard
+* [TeamHG-Memex/tensorboard_logger](https://github.com/TeamHG-Memex/tensorboard_logger)
+* [dmlc/tensorboard](https://github.com/dmlc/tensorboard)