Update documentation (mostly VISUALIZATION and COOKBOOK)

docs/about.rst

@@ -1,12 +1,11 @@
 About this project
 ==================
 
-Netwulf is an interactive visualization engine for networkx_ Graph-objects.
-Unlike other visualization methods, it is neither slow, nor does it rely
-to install any crude dependencies. On top, fine-tuning visualizations 
-is made simple due to the interactive visualization nature and reproducing visualizations
-is made possible thanks to seamless communication between Python and the
-visualization tool.
+Netwulf is an interactive visualization tool for networkx_ Graph-objects,
+that allows you to produce beautiful looking network visualizations. Simply
+input a `networkx.Graph` object, style the network in the interactive console
+and either download the result as a PNG or pipe the layout back to Python for
+further processing. Netwulf is fast and relies on no crude dependencies.
 
 Quick example
 -------------
@@ -20,7 +19,7 @@ Quick example
 
     visualize(G)
 
-.. figure:: img/BA.png
+.. figure:: img/simple_example.gif
 
     started visualization
 
@@ -30,18 +29,18 @@ Why should I use netwulf
 Pros
 ~~~~
 
-- interactive styling of network visualizations in the browser, started from Python
-- no compiling needed
-- no external program needed 
-- cross-platform
-- seamlessly use the inferred style back in Python
-- redraw the visualization in Python using matplotlib
+- Interactive styling of network visualizations in the browser, started from Python
+- No compiling needed
+- No external program needed 
+- Cross-platform
+- Seamlessly use the inferred style back in Python
+- Redraw the visualization in Python using matplotlib
 
 Cons
 ~~~~
 
-- no multiedges yet
-- no rendering of directed edges
+- No multiedges yet
+- No rendering of directed edges
 
 
 Install

docs/cookbook/groups.rst

@@ -1,21 +1,86 @@
-Visualize Groups
-----------------
+Simplest use case
+-----------------
 
-Cluster a network and visualize it with groups.
+Given a *networkx.Graph* object, you can launch netwulf like so:
 
 .. code:: python
 
+	import networkx as nx
+	import netwulf as wulf
+
+	G = nx.barabasi_albert_graph(100, 2)
+
+	wulf.visualize(G)  # <-- THIS IS IT
+
+Alternatively, *netwulf.visualize* can accept a node-link dictionary object `formatted like this <https://gist.githubusercontent.com/ulfaslak/6be66de1ac3288d5c1d9452570cbba5a/raw/4cab5036464800e51ce59fc088688e9821795efb/miserables.json>`_.
+
+
+Node and link attributes
+------------------------
+
+Netwulf recognizes node attributes 'group' and 'size', and link attribute 'weight'.
+Users can create a *networkx.Graph* object with node and link data:
+
+.. code:: python
+
+    list(G.nodes(data=True))[:3]
+    # [(0, {'group': 0, 'size': 0.20982489558943607}),
+    #  (1, {'group': 0, 'size': 0.7118952904573288}),
+    #  (2, {'group': 0, 'size': 0.8785902846905586})]
+
+    list(G.edges(data=True))[:3]
+    # [(0, 5, {'weight': 0.8917083938103719}),
+    #  (0, 9, {'weight': 0.29583879684946757}),
+    #  (0, 12, {'weight': 0.36847140599448236})]
+
+Example:
+
+.. code:: python
+
+    import numpy as np
     import networkx as nx
-    import community
     import netwulf as wulf
 
-    G = nx.random_partition_graph([10,10,10],.25,.01)
-    bb = community.best_partition(G)  # dict of node-community pairs
-    nx.set_node_attributes(G, bb, 'group')
+    # Create a network
+    G = nx.random_partition_graph([10, 10, 10], .25, .01)
+
+    # Change 'block' node attribute to 'group'
+    for k, v in G.nodes(data=True):
+        v['group'] = v['block']; del v['block']
+
+    # Or detect communities and encode them in 'group' attribute
+    # import community
+    # bb = community.best_partition(G)
+    # nx.set_node_attributes(G, bb, 'group')
+
+    # Set node 'size' attributes
+    for n, data in G.nodes(data=True):
+        n['size'] = np.random.random()
+
+    # Set link 'weight' attributes
+    for n1, n2, data in G.edges(data=True):
+        data['weight'] = np.random.random()
 
     wulf.visualize(G)
 
 
 .. figure:: img/random_partition_graph.png
 
-    colored partition
+Note: If 'group' is not a color (like "red" or "#4fba21") the group colors are assigned randomly.
+
+
+Save as PDF
+-----------
+
+.. code:: python
+
+	import networkx as nx
+	import netwulf as wulf
+
+	G = nx.barabasi_albert_graph(100, 2)
+
+	network, config = wulf.visualize(G, plot_in_cell_below=False)
+
+	fig, ax = plt.subplots(figsize=(10, 10))
+	wulf.draw_netwulf(network, fig, ax)
+	plt.savefig("myfigure.pdf")

docs/python_api/drawing.rst

@@ -14,9 +14,9 @@ the function :mod:`netwulf.tools.draw_netwulf`.
 
     stylized_network, config = wulf.visualize(G)
 
-    import matplotlib.pyplot as pl
-    fig, ax = wulf.draw_netwulf(G)
-    pl.show()
+    import matplotlib.pyplot as plt
+    fig, ax = wulf.draw_netwulf(stylized_network)
+    plt.show()
 
 
 A visualization window is opened and the network can be stylized.
@@ -34,7 +34,7 @@ for the first node this might look like
 .. code:: python
 
     ax.text(
-            network_properties['nodes'][0]['pos'][0],
-            network_properties['nodes'][0]['pos'][1],
+            network_properties['nodes'][0]['x']
+            network_properties['nodes'][0]['y']
             network_properties['nodes'][0]['id']
            )

docs/python_api/post_back.rst

@@ -26,10 +26,9 @@ Once you're done, press the button `Post to Python`.
 
     Post to Python
 
-Pressing this button will lead the data to be posted back to Python. 
-Subsequently the browser window will be closed. The Python kernel will
-not be responding until either the `Post to Python`-button is pressed
-or the ``KeyboardInterrupt`` signal is send (manually or using the `Stop`-Button 
+Pressing this button will pipe the data back to Python and close the browser
+The Python kernel is busy until either `Post to Python` is clicked or a
+``KeyboardInterrupt`` signal is send (manually or using the `Stop`-Button 
 in a Jupyter notebook).
 
 The returned stylized network dictionary will contain all the necessary information
@@ -38,72 +37,87 @@ to reproduce the figure. It will look something like this.
 .. code:: python
 
     stylized_network = {
-         'xlim': [0, 833],
-         'ylim': [0, 833],
-         'linkColor': '#7c7c7c',
-         'linkAlpha': 0.5,
-         'nodeStrokeColor': '#000000',
-         'nodeStrokeWidth': 0.75,
-         'links': [{'link': [0, 2], 'width': 3},
-          {'link': [0, 3], 'width': 3},
-          {'link': [0, 4], 'width': 3},
-          {'link': [1, 2], 'width': 3},
-          {'link': [1, 3], 'width': 3},
-          {'link': [1, 4], 'width': 3}],
-         'nodes': [{'id': 0,
-           'pos': [436.0933431058901, 431.72418500564186],
-           'radius': 20,
-           'color': '#16a085'},
-          {'id': 1,
-           'pos': [404.62184898400426, 394.8158724310507],
-           'radius': 20,
-           'color': '#16a085'},
-          {'id': 2,
-           'pos': [409.15148692745356, 438.08415417584683],
-           'radius': 20,
-           'color': '#16a085'},
-          {'id': 3,
-           'pos': [439.27989436871223, 397.14932001193233],
-           'radius': 20,
-           'color': '#16a085'},
-          {'id': 4,
-           'pos': [393.4680683212157, 420.63184247673917],
-           'radius': 20,
-           'color': '#16a085'}]
-          }
-
-
-Furthermore, the configuration
+        'xlim': [0, 833],
+        'ylim': [0, 833],
+        'linkColor': '#7c7c7c',
+        'linkAlpha': 0.5,
+        'nodeStrokeColor': '#000000',
+        'nodeStrokeWidth': 0.75,
+        'links': [
+            {'source': 0, 'target': 2, 'width': 3},
+            {'source': 0, 'target': 3, 'width': 3},
+            {'source': 0, 'target': 4, 'width': 3},
+            {'source': 1, 'target': 2, 'width': 3},
+            {'source': 1, 'target': 3, 'width': 3},
+            {'source': 1, 'target': 4, 'width': 3}
+        ],
+        'nodes': [
+            {'id': 0,
+             'x': 436.0933431058901,
+             'y': 431.72418500564186,
+             'radius': 20,
+             'color': '#16a085'},
+            {'id': 1,
+             'x': 404.62184898400426,
+             'y': 394.8158724310507,
+             'radius': 20,
+             'color': '#16a085'},
+            {'id': 2,
+             'x': 409.15148692745356,
+             'y': 438.08415417584683,
+             'radius': 20,
+             'color': '#16a085'},
+            {'id': 3,
+             'x': 439.27989436871223,
+             'y': 397.14932001193233,
+             'radius': 20,
+             'color': '#16a085'},
+            {'id': 4,
+             'x': 393.4680683212157,
+             'y': 420.63184247673917,
+             'radius': 20,
+             'color': '#16a085'}
+        ]
+    }
+
+
+Furthermore, the configuration dictionary 
 which was used to generate this figure will resemble
 
 .. code:: python
 
-    config = {
-         'Apply heat (wiggle)': False,
-         'Charge strength': -30,
-         'Center gravity': 0.1,
-         'Link distance': 10,
-         'Link width': 2,
-         'Link alpha': 0.5,
-         'Node size': 10,
-         'Node stroke size': 0.5,
-         'Node size exponent': 0.5,
-         'Link width exponent': 0.5,
-         'Collision': False,
-         'Node fill': '#16a085',
-         'Node stroke': '#000000',
-         'Link stroke': '#7c7c7c',
-         'Label stroke': '#000000',
-         'Show labels': False,
-         'Show singleton nodes': False,
-         'Node size by strength': False,
-         'Zoom': 1.5,
-         'Min. link weight %': 0,
-         'Max. link weight %': 100
-         }
+    default_config = {
+        # Input/output
+        'zoom': 1.5,
+        # Physics
+        'node_charge': -30,
+        'node_gravity': 0.1,
+        'link_distance': 10,
+        'node_collision': False,
+        'wiggle_nodes': False,
+        'freeze_nodes': False,
+        # Nodes
+        'node_fill_color': '#16a085',
+        'node_stroke_color': '#000000',
+        'node_label_color': '#000000',
+        'display_node_labels': False,
+        'scale_node_size_by_strength': False,
+        'node_size': 10,
+        'node_stroke_width': 0.5,
+        'node_size_unevenness': 0.5,
+        # Links
+        'link_color': '#7c7c7c',
+        'link_width': 5,
+        'link_alpha': 0.5,
+        'link_width_unevenness': 0.5,
+        # Thresholding
+        'display_singleton_nodes': False,
+        'min_link_weight_percentage': 0,
+        'max_link_weight_percentage': 100
+    }
 
 If the visualization was started from a Jupyter notebook, a picture of the stylized
-network will appear additionally
+network will appear in the cell below.
 
 .. figure:: img/figure_in_jupyter.png