added label functions, close #29

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
@@ -29,7 +39,8 @@ 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.1.1...HEAD
+[Unreleased]: https://github.com/benmaier/netwulf/compare/v0.1.2...HEAD
+[v0.1.1]: 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

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`.

netwulf/metadata.py

@@ -3,7 +3,7 @@
 Contains a bunch of information about this package.
 """
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 
 __author__ = "Ulf Aslak, Benjamin F. Maier"
 __copyright__ = "Copyright 2018-2019, Ulf Aslak, Benjamin F. Maier"

netwulf/tests/test_all.py

@@ -4,7 +4,7 @@
 import matplotlib.pyplot as pl
 import networkx as nx
 
-from netwulf.tools import bind_properties_to_network, get_filtered_network, draw_netwulf
+from netwulf.tools import bind_properties_to_network, get_filtered_network, draw_netwulf, node_pos, add_node_label, add_edge_label
 from netwulf import visualize
 
 def _get_test_network():
@@ -137,7 +137,10 @@ def test_matplotlib(self):
             }
 
 
-        draw_netwulf(stylized_network)
+        fig, ax = draw_netwulf(stylized_network)
+
+        add_node_label(ax, stylized_network, 0)
+        add_edge_label(ax, stylized_network, (0,1))
         pl.show(block=False)
         pl.pause(5)
         pl.close()

netwulf/tools.py

@@ -9,6 +9,142 @@
 import matplotlib.pyplot as pl
 from matplotlib.collections import LineCollection, EllipseCollection
 
+def node_pos(network_properties,node_id):
+    """
+    Get the node's position in matplotlib data coordinates.
+    
+    Parameters
+    ----------
+    network_properties : dict
+        The network properties which are returned from the
+        interactive visualization.
+
+    Returns
+    -------
+    x : float
+        The x-position in matplotlib data coordinates
+    y : float
+        The y-position in matplotlib data coordinates
+
+    Example
+    -------
+        >>> props, _ = visualize(G)
+        >>> node_pos(props, 0)
+    """
+
+    height = network_properties['ylim'][1] - network_properties['ylim'][0]
+    node = network_properties['nodes'][node_id]
+
+    return node['x_canvas'], height - node['y_canvas']
+
+def add_node_label(ax,
+                   network_properties,
+                   node_id,
+                   label=None,
+                   dx=0,
+                   dy=0,
+                   ha='center',
+                   va='center',
+                   **kwargs):
+    """
+    Add a label to a node in the drawn matplotlib axis
+
+    Parameters
+    ----------
+    ax : matplotlib.Axis
+        The Axis object which has been used to draw the network
+    network_properties : dict
+        The network properties which are returned from the
+        interactive visualization.
+    node_id : str or int
+        The focal node's id in the `network_properties` dict
+    label : str, default : None
+        The text to write at the node's position
+        If `None`, the value of `node_id` will be put there.
+    dx : float, default : 0.0
+        Label offset in x-direction
+    dy : float, default : 0.0
+        Label offset in y-direction
+    ha : str, default : 'center'
+        Horizontal anchor orientation of the text
+    va : str, default : 'center'
+        Vertical anchor orientation of the text
+    **kwargs : dict
+        Additional styling arguments forwarded to Axis.text
+
+
+    Example
+    -------
+        >>> netw, _ = netwulf.visualize(G)
+        >>> fig, ax = netwulf.draw_netwulf(netw)
+        >>> netwulf.add_node_label(ax,netw,0)
+    """
+
+    pos = node_pos(network_properties, node_id)
+
+    if label is None:
+        label = str(node_id)
+
+    ax.text(pos[0]+dx,pos[1]+dy,label,ha=ha,va=va,**kwargs)
+
+def add_edge_label(ax,
+                   network_properties,
+                   edge,
+                   label=None,
+                   dscale=0.5,
+                   dx=0,
+                   dy=0,
+                   ha='center',
+                   va='center',
+                   **kwargs):
+    """
+    Add a label to an edge in the drawn matplotlib axis
+
+    Parameters
+    ----------
+    ax : matplotlib.Axis
+        The Axis object which has been used to draw the network
+    edge : 2-tuple of str or int
+        The edge's node ids
+    network_properties : dict
+        The network properties which are returned from the
+        interactive visualization.
+    label : str, default : None
+        The text to write at the node's position
+        If `None`, the tuple of node ids in `edge` will be put there.
+    dscale : float, default : 0.5
+        At which position between the two nodes to put the label
+        (``dscale = 0.0`` refers to the position of node ``edge[0]``
+        and ``dscale = 1.0`` refers to the position of node ``edge[1]``,
+        so use any number between 0.0 and 1.0).
+    dx : float, default : 0.0
+        Additional label offset in x-direction
+    dy : float, default : 0.0
+        Additional label offset in y-direction
+    ha : str, default : 'center'
+        Horizontal anchor orientation of the text
+    va : str, default : 'center'
+        Vertical anchor orientation of the text
+    **kwargs : dict
+        Additional styling arguments forwarded to Axis.text
+
+
+    Example
+    -------
+        >>> netw, _ = netwulf.visualize(G)
+        >>> fig, ax = netwulf.draw_netwulf(netw)
+        >>> netwulf.add_node_label(ax,netw,0)
+    """
+
+    v0 = np.array(node_pos(network_properties, edge[0]))
+    v1 = np.array(node_pos(network_properties, edge[1]))
+    e = (v1-v0)
+
+    if label is None:
+        label = str("("+str(edge[0])+", "+str(edge[1])+")")
+
+    pos = v0 + dscale * e 
+    ax.text(pos[0]+dx,pos[1]+dy,label,ha=ha,va=va,**kwargs)
 
 def bind_properties_to_network(network,
                                network_properties,
@@ -41,8 +177,8 @@ def bind_properties_to_network(network,
 
     Example
     -------
-        >>> props, _ = visualize(G)
-        >>> bind_properties_to_network(G, props)
+        >>> props, _ = netwulf.visualize(G)
+        >>> netwulf.bind_properties_to_network(G, props)
     """
     # Add individial node attributes
     if bind_node_positions:
@@ -119,15 +255,10 @@ def draw_netwulf(network_properties, fig=None, ax=None, figsize=None):
     """
     Redraw the visualization using matplotlib. Creates
     figure and axes if None provided.
-    In order to add labels, do for instance
-
-    .. code:: python
-
-        ax.text(
-                network_properties['nodes'][0]['x'],
-                network_properties['nodes'][0]['y'],
-                network_properties['nodes'][0]['id']
-               )
+    In order to add labels, check out 
+    :mod:`netwulf.tools.add_node_label`
+    and
+    :mod:`netwulf.tools.add_edge_label`
 
     Parameters
     ----------