Merge branch 'master' of github.com:benmaier/netwulf

CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+
+## [v0.1.4] - 2019-09-09
+### Fixed
+- having graph properties with numpy types raised an error when dumping to JSON,
+  so these types are now converted to Python types prior to dumping
+
+### Changed
+- nodes with strength 0 are now rescaled to strength 1 if node size is scaled by strength
+- when changing node and link properties in a frozen simulation, the simulation is not restarted anymore
+- The server is stopped as soon as the Browser window is closed
+
+## [v0.1.3] - 2019-06-18
+### Added
+- module `netwulf.io`, which contains functions to save and load stylized networks
+- appropriate tests for this module's functionality
+- sections in the docs
+- a label and link drawing cookbook example
+
+### Changed
+- `zorder`-behavior in matplotlib drawing (`netwulf.draw_netwulf`)
+
+## [v0.1.2] - 2019-06-17
+### Added
+- function `netwulf.tools.node_pos` to get a node's position on the matplotlib axis
+- function `netwulf.tools.add_node_label` to add a node label to the matplotlib axis
+- function `netwulf.tools.add_edge_label` to add an edge label to the matplotlib axis
+
+### Changed
+- The corresponding docs for node labels was changed to use the new functions.
+- The matplotlib test now contains additional tests for the edge label and node label positioning
+
+## [v0.1.1] - 2019-05-24
+### Changed
+- some default settings
+- set constant `dpi = 72` for unit conversions in matplotlib redrawing because apparently matplotlib only uses this value for conversions, see https://stackoverflow.com/a/35501485/4177832.
+
+## [v0.1.0] - 2019-05-23
+### Changed
+- `netwulf.tools.bind_positions_to_network` is now called `netwulf.bind_properties_to_network` and it now does exactly that -- write properties instead of just positions
+- several visualization config options were renamed
+- `netwulf.tools.draw_netwulf` now draws the canvas positions instead of the actual node positions (differences arise by zooming).
+
 ## [v0.0.18] - 2019-05-15
 ### Added
 - added automated test functionality in ``/tests/`` and ``Makefile``
@@ -18,6 +60,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - switched from usage of `os.path` to `pathlib` at the appropriate places
 
-[Unreleased]: https://github.com/benmaier/netwulf/compare/v0.0.18...HEAD
+[Unreleased]: https://github.com/benmaier/netwulf/compare/v0.1.4...HEAD
+[v0.1.4]: https://github.com/benmaier/netwulf/compare/v0.1.3...v0.1.4
+[v0.1.3]: https://github.com/benmaier/netwulf/compare/v0.1.2...v0.1.3
+[v0.1.2]: https://github.com/benmaier/netwulf/compare/v0.1.1...v0.1.2
+[v0.1.1]: https://github.com/benmaier/netwulf/compare/v0.1.0...v0.1.1
+[v0.1.0]: https://github.com/benmaier/netwulf/compare/v0.0.18...v0.1.0
 [v0.0.18]: https://github.com/benmaier/netwulf/compare/v0.0.17...v0.0.18
 [v0.0.17]: https://github.com/benmaier/netwulf/releases/tag/v0.0.17

OUTLOOK.md

@@ -0,0 +1,15 @@
+# Outlook
+
+This is a place to collect ideas on how to further improve the network visualization process.
+
+## Directed and curved edges
+
+This is a crucial functionality for a lot of network scientists. We plan to [incorporate this functionality soon](ulfaslak/network_styling_with_d3#3), in fact we already [started working on it](benmaier/curved-edges).
+
+## Tree styling
+
+d3 provides a great [API for tree styling](https://github.com/d3/d3-hierarchy/blob/master/README.md). We should build an addition tree styling function.
+
+## Hierarchically clustered networks
+
+Networks are often inferred to be hierarchically clustered. Different visualizations could be used to visually cluster these networks in a way that does not rely on a force-layout, e.g. with something like a [Pack](https://github.com/d3/d3-hierarchy/blob/master/README.md#pack), see [also here](https://observablehq.com/@d3/zoomable-circle-packing) or with [hierarchical edge bundling](https://observablehq.com/@d3/hierarchical-edge-bundling).

README.md

@@ -9,6 +9,11 @@ The package is build around the philosophy that network manipulation and preproc
 
 ![example](https://github.com/benmaier/netwulf/raw/master/img/simple_example.gif)
 
+## Paper
+
+[![status](http://joss.theoj.org/papers/3a22c963a45dbddc8501a4b5ef4b2bf6/status.svg)](http://joss.theoj.org/papers/3a22c963a45dbddc8501a4b5ef4b2bf6)
+
+If you use `netwulf` for your scientific work, consider citing us! We're currently [under review in JOSS](https://github.com/openjournals/joss-reviews/issues/1425).
 
 ## Install
 
@@ -61,7 +66,7 @@ This project is licensed under the [MIT License](https://github.com/benmaier/net
 
 ## Contributing
 
-If you want to contribute to this project, please make sure to read the [code of conduct](https://github.com/benmaier/netwulf/blob/master/CODE_OF_CONDUCT.md) and the [contributing guidelines](https://github.com/benmaier/netwulf/blob/master/CONTRIBUTING.md).
+If you want to contribute to this project, please make sure to read the [code of conduct](https://github.com/benmaier/netwulf/blob/master/CODE_OF_CONDUCT.md) and the [contributing guidelines](https://github.com/benmaier/netwulf/blob/master/CONTRIBUTING.md). In case you're wondering about what to contribute, we're always collecting ideas of what we want to implement next in the [outlook notes](https://github.com/benmaier/netwulf/blob/master/OUTLOOK.md).
 
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg)](code-of-conduct.md)
 

README.rst

@@ -18,6 +18,15 @@ without code.
 
 |example|
 
+Paper
+-----
+
+|status|
+
+If you use ``netwulf`` for your scientific work, consider citing us!
+We're currently `under review in
+JOSS <https://github.com/openjournals/joss-reviews/issues/1425>`__.
+
 Install
 -------
 
@@ -88,6 +97,9 @@ If you want to contribute to this project, please make sure to read the
 conduct <https://github.com/benmaier/netwulf/blob/master/CODE_OF_CONDUCT.md>`__
 and the `contributing
 guidelines <https://github.com/benmaier/netwulf/blob/master/CONTRIBUTING.md>`__.
+In case you're wondering about what to contribute, we're always
+collecting ideas of what we want to implement next in the `outlook
+notes <https://github.com/benmaier/netwulf/blob/master/OUTLOOK.md>`__.
 
 |Contributor Covenant|
 
@@ -139,6 +151,8 @@ until the warnings disappear. Then do
 
 .. |logo| image:: https://github.com/benmaier/netwulf/raw/master/img/logo_small.png
 .. |example| image:: https://github.com/benmaier/netwulf/raw/master/img/simple_example.gif
+.. |status| image:: http://joss.theoj.org/papers/3a22c963a45dbddc8501a4b5ef4b2bf6/status.svg
+   :target: http://joss.theoj.org/papers/3a22c963a45dbddc8501a4b5ef4b2bf6
 .. |Documentation Status| image:: https://readthedocs.org/projects/netwulf/badge/?version=latest
    :target: https://netwulf.readthedocs.io/en/latest/?badge=latest
 .. |visualization example0| image:: https://github.com/benmaier/netwulf/raw/master/img/BA_1.png

docs/cookbook/cookbook.rst

@@ -101,6 +101,38 @@ Save as PDF
     
     network, config = wulf.visualize(G, plot_in_cell_below=False)
     
-    fig, ax = plt.subplots(figsize=(10, 10))
-    wulf.draw_netwulf(network, fig, ax)
+    fig, ax = wulf.draw_netwulf(network, figsize=(10,10))
     plt.savefig("myfigure.pdf")
+
+
+Labels and node positions
+-------------------------
+
+.. code:: python
+
+    import networkx as nx
+    import netwulf as wulf
+    import matplotlib.pyplot as plt
+
+    G = nx.Graph()
+    G.add_nodes_from([0,1,2,'a','b','c'])
+    G.add_edges_from([(0,1),('a','b')])
+
+    network, config = wulf.visualize(G,config={'zoom':3})
+
+    # draw links only at first
+    fig, ax = wulf.draw_netwulf(network,draw_nodes=False)
+
+    # get positions of two unconnected nodes to draw a link anyway
+    v0 = wulf.node_pos(network, 'c')
+    v1 = wulf.node_pos(network, 2)
+    ax.plot([v0[0],v1[0]],[v0[1],v1[1]],c='#d95f02')
+
+    # draw nodes now
+    wulf.draw_netwulf(network,fig,ax,draw_links=False)
+
+    # add labels to a node and an edge
+    wulf.add_node_label(ax,network,'c')
+    wulf.add_edge_label(ax,network,('a','b'))
+    
+.. figure:: img/labeled_graph.png

docs/dev_notes/testing.rst

@@ -18,7 +18,19 @@ with an output looking like this
 
 .. code:: bash
 
-    PLACEHOLDER
+	---------- coverage: platform darwin, python 3.7.3-final-0 -----------
+	Name                        Stmts   Miss  Cover
+	-----------------------------------------------
+	netwulf/__init__.py             4      0   100%
+	netwulf/interactive.py        154     24    84%
+	netwulf/metadata.py             9      0   100%
+	netwulf/tests/__init__.py       1      0   100%
+	netwulf/tests/test_all.py      70      2    97%
+	netwulf/tools.py               92      1    99%
+	-----------------------------------------------
+	TOTAL                         330     27    92%
+	
+	================ 5 passed, 4 warnings in 58.81 seconds ================
 
 If you open a pull request, make sure you ran the tests and copy the test report
 as a comment with your pull request like so
@@ -61,6 +73,23 @@ A browser window will be opened with a visualization looking like this.
 
 It will close automatically.
 
+Config
+~~~~~~~
+
+The config test starts a visualization with a configuration where each entry differs from its default value.
+
+.. code:: python
+
+    T.test_config_adaption()
+
+A browser window will be opened with a visualization looking like this.
+
+.. figure:: img/test_config.png
+
+    Posting test
+
+It will close automatically. The test checks wether the returned configuration is equal to the posted configuration.
+
 Reproducibility
 ~~~~~~~~~~~~~~~
 
@@ -132,3 +161,13 @@ The resulting figure should look like this:
 
     matplotlib test 1
 
+Data I/O
+~~~~~~~~
+
+A stylized network is supposed to be saved and loaded by the functions in the module :mod:`netwulf.io`. Start the test like this
+
+.. code:: python
+
+    T.test_io()
+
+The test network will be styled in netwulf, saved, loaded and then redrawn in matplotlib. Hence the figure should look like the netwulf visualization.

docs/index.rst

@@ -19,6 +19,7 @@ Netwulf - Interactive Network Visualization
    python_api/post_back
    python_api/drawing
    python_api/network_manipulation
+   python_api/data_io
 
 .. toctree::
    :maxdepth: 2
@@ -45,4 +46,5 @@ Netwulf - Interactive Network Visualization
 
    reference/interactive
    reference/tools
+   reference/io
 

docs/python_api/data_io.rst

@@ -0,0 +1,34 @@
+Data I/O
+--------
+
+It's not too hard to dump the returned visualization session to a json-file 
+to restore it easily, but we wrote a wrapper for that nevertheless.
+
+Start a visualization like this
+
+.. code:: python
+
+    import networkx as nx
+    import netwulf as wulf
+
+    G = nx.barabasi_albert_graph(100,2)
+
+    stylized_network, config = wulf.visualize(G)
+
+You can either save/load the stylized network only
+
+.. code:: python
+
+    wulf.save("BA.json", stylized_network, config)
+    stylized_network, config, _ = wulf.load("BA.json")
+    wulf.draw_netwulf(stylized_network, config)
+
+
+Or you can save/load with the respective ``networkx.Graph``-object
+in order to replicate some other features.
+
+.. code:: python
+
+    wulf.save("BA.json", stylized_network, config, G)
+    stylized_network, config, G = wulf.load("BA.json")
+

docs/python_api/drawing.rst

@@ -27,14 +27,24 @@ the figure will be redrawn in matplotlib and opened.
 
     Reproduced figure
 
-In order to add labels, use ``matplotlib``'s text function.
-Node positions and labels are saved in the stylized network, so
-for the first node this might look like
+In order to add labels, use netwulf's functions 
+:mod:`netwulf.tools.add_edge_label` 
+or
+:mod:`netwulf.tools.add_node_label`.
 
 .. code:: python
 
-    ax.text(
-            network_properties['nodes'][0]['x'],
-            network_properties['nodes'][0]['y'],
-            network_properties['nodes'][0]['id']
-           )
+    add_edge_label(ax, stylized_network, (0,1))
+    add_node_label(ax, stylized_network, 9)
+
+This will add the node id and edge tuple to the figure. You can add an optional label string as 
+
+.. code:: python
+
+    add_edge_label(ax, stylized_network, (0,1), label='this edge')
+    add_node_label(ax, stylized_network, 9, label='this node')
+
+For additional styling options check out the respective functions docstrings at
+:mod:`netwulf.tools.add_edge_label` 
+or
+:mod:`netwulf.tools.add_node_label`.

docs/python_api/post_back.rst

@@ -87,32 +87,33 @@ which was used to generate this figure will resemble
 
     default_config = {
         # Input/output
-        'zoom': 1.5,
+        'zoom': 1,
         # Physics
-        'node_charge': -30,
+        'node_charge': -45,
         'node_gravity': 0.1,
-        'link_distance': 10,
-        'node_collision': False,
+        'link_distance': 15,
+        'link_distance_variation': 0,
+        'node_collision': True,
         'wiggle_nodes': False,
         'freeze_nodes': False,
         # Nodes
-        'node_fill_color': '#16a085',
-        'node_stroke_color': '#000000',
+        'node_fill_color': '#79aaa0',
+        'node_stroke_color': '#555555',
         '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,
+        'node_size': 5,
+        'node_stroke_width': 1,
+        'node_size_variation': 0.5,
         # Links
         'link_color': '#7c7c7c',
-        'link_width': 5,
+        'link_width': 2,
         'link_alpha': 0.5,
-        'link_width_unevenness': 0.5,
+        'link_width_variation': 0.5,
         # Thresholding
-        'display_singleton_nodes': False,
-        'min_link_weight_percentage': 0,
-        'max_link_weight_percentage': 100
+        'display_singleton_nodes': True,
+        'min_link_weight_percentile': 0,
+        'max_link_weight_percentile': 1
     }
 
 If the visualization was started from a Jupyter notebook, a picture of the stylized

docs/reference/io.rst

@@ -0,0 +1,8 @@
+Data I/O module
+---------------
+
+.. automodule:: netwulf.io
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

netwulf/__init__.py

@@ -7,3 +7,4 @@
 from .metadata import __version__
 from .interactive import *
 from .tools import *
+from .io import *