iplotx 0.7.0__tar.gz → 0.9.0__tar.gz

{iplotx-0.7.0 → iplotx-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 0.7.0
+Version: 0.9.0
 Summary: Plot networkx from igraph and networkx.
 Project-URL: Homepage, https://github.com/fabilab/iplotx
 Project-URL: Documentation, https://readthedocs.org/iplotx

{iplotx-0.7.0 → iplotx-0.9.0}/iplotx/__init__.py

@@ -9,19 +9,19 @@ library was used to construct the network.
 from .version import __version__
 from .plotting import (
     network,
+    graph,
     tree,
+    plot,
 )
 import iplotx.artists as artists
 import iplotx.style as style
 
 
-# Shortcut to iplotx.plotting.network
-plot = network
-
 __all__ = [
     "network",
     "tree",
     "plot",
+    "graph",
     "artists",
     "style",
     "__version__",

{iplotx-0.7.0 → iplotx-0.9.0}/iplotx/network.py

@@ -162,6 +162,8 @@ class NetworkArtist(mpl.artist.Artist):
         """Get VertexCollection artist."""
         return self._vertices
 
+    get_nodes = get_vertices
+
     def get_edges(self):
         """Get EdgeCollection artist."""
         return self._edges
@@ -170,6 +172,8 @@ class NetworkArtist(mpl.artist.Artist):
         """Get list of vertex label artists."""
         return self._vertices.get_labels()
 
+    get_node_labels = get_vertex_labels
+
     def get_edge_labels(self):
         """Get list of edge label artists."""
         return self._edges.get_labels()
@@ -211,6 +215,10 @@ class NetworkArtist(mpl.artist.Artist):
         return vertex_layout_df
 
     def _get_label_series(self, kind):
+        # Equivalence vertex/node
+        if kind == "node":
+            kind = "vertex"
+
         if "label" in self._ipx_internal_data[f"{kind}_df"].columns:
             return self._ipx_internal_data[f"{kind}_df"]["label"]
         else:

{iplotx-0.7.0 → iplotx-0.9.0}/iplotx/plotting.py

@@ -22,6 +22,7 @@ def network(
     layout: Optional[LayoutType] = None,
     grouping: Optional[GroupingType] = None,
     vertex_labels: Optional[list | dict | pd.Series | bool] = None,
+    node_labels: Optional[list | dict | pd.Series | bool] = None,
     edge_labels: Optional[Sequence] = None,
     ax: Optional[mpl.axes.Axes] = None,
     style: str | dict | Sequence[str | dict] = (),
@@ -42,6 +43,9 @@ def network(
             will be drawn. If a list, the labels are taken from the list. If a dict, the keys
             should be the vertex IDs and the values should be the labels. If True (a single
             bool value), the vertex IDs will be used as labels.
+        node_labels: Same meaning as vertex_labels. This is an alias to help users who prefer
+            the word "node" over "vertex". If both vertex_labels and node_labels are specified,
+            "node_labels" overrides "vertex_labels".
         edge_labels: The labels for the edges. If None, no edge labels will be drawn. Defaults
             to None.
         ax: The axis to plot on. If None, a new figure and axis will be created. Defaults to
@@ -68,6 +72,11 @@ def network(
         The list can have one or two elements, depending on whether you are requesting to
         plot a network, a grouping, or both.
     """
+    # Equivalence of node_labels and vertex_labels
+    if node_labels is not None:
+        vertex_labels = node_labels
+    del node_labels
+
     stylecontext = context(style, **kwargs) if style or kwargs else nullcontext()
 
     with stylecontext:
@@ -126,11 +135,17 @@ def network(
         return artists
 
 
+# Aliases
+plot = network
+graph = network
+
+
 def tree(
     tree: Optional[TreeType] = None,
     layout: str | LayoutType = "horizontal",
     directed: bool | str = False,
     vertex_labels: Optional[list | dict | pd.Series | bool] = None,
+    node_labels: Optional[list | dict | pd.Series | bool] = None,
     leaf_labels: Optional[list | dict | pd.Series | bool] = None,
     show_support: bool = False,
     ax: Optional[mpl.axes.Axes] = None,
@@ -150,6 +165,9 @@ def tree(
         directed: If False, do not draw arrows.
         vertex_labels: The labels for the vertices. If None or False, no vertex labels. Also
             read leaf_labels for leaf nodes.
+        node_labels: Same meaning as vertex_labels. This is an alias to help users who prefer
+            the word "node" over "vertex". If both vertex_labels and node_labels are specified,
+            "node_labels" overrides "vertex_labels".
         leaf_labels: The labels for the leaf nodes. If None or False, no leaf labels are used
             except if vertex_labels are specified for leaf nodes. This argument and the
             previous vertex_labels provide somewhat redundant functionality but have quite
@@ -183,6 +201,11 @@ def tree(
     Returns:
         A TreeArtist object, set as a direct child of the matplotlib Axes.
     """
+    # Equivalence of node_labels and vertex_labels
+    if node_labels is not None:
+        vertex_labels = node_labels
+    del node_labels
+
     stylecontext = context(style, **kwargs) if style or kwargs else nullcontext()
 
     with stylecontext:

{iplotx-0.7.0 → iplotx-0.9.0}/iplotx/style/__init__.py

@@ -1,16 +1,24 @@
+"""
+Main style module for iplotx.
+"""
+
 from typing import (
     Any,
     Iterable,
     Optional,
     Sequence,
 )
-from collections import defaultdict
 from collections.abc import Hashable
 from contextlib import contextmanager
 import numpy as np
 import pandas as pd
 
-from ..utils.style import copy_with_deep_values
+from ..utils.style import (
+    copy_with_deep_values,
+    sanitize_leaves,
+    update_style,
+    sanitize_ambiguous,
+)
 from .library import style_library
 from .leaf_info import (
     style_leaves,
@@ -83,94 +91,16 @@ def merge_styles(
     Returns:
         The composite style as a dict.
     """
-    try:
-        import networkx as nx
-    except ImportError:
-        nx = None
-
-    def _sanitize_leaves(style: dict):
-        for key, value in style.items():
-            if key in style_leaves:
-                # Networkx has a few lazy data structures
-                # TODO: move this code to provider
-                if nx is not None:
-                    if isinstance(value, nx.classes.reportviews.NodeView):
-                        style[key] = dict(value)
-                    elif isinstance(value, nx.classes.reportviews.EdgeViewABC):
-                        style[key] = [v for *e, v in value]
-
-            elif isinstance(value, dict):
-                _sanitize_leaves(value)
-
-    def _update(style: dict, current: dict):
-        for key, value in style.items():
-            if key not in current:
-                current[key] = value
-                continue
-
-            # Style non-leaves are either recurred into or deleted
-            if key not in style_leaves:
-                if isinstance(value, dict):
-                    _update(value, current[key])
-                elif value is None:
-                    del current[key]
-                else:
-                    raise ValueError(
-                        f"Setting non-leaf style value to a non-dict: {key}, {value}",
-                    )
-            else:
-                # Style leaves could be incomplete, ensure a sensible default
-                if value is None:
-                    del current[key]
-                    continue
-
-                if not isinstance(value, dict):
-                    current[key] = value
-                    continue
-
-                if hasattr(value, "default_factory"):
-                    current[key] = value
-                    continue
-
-                if hasattr(current[key], "default_factory"):
-                    default_value = current[key].default_factory()
-                else:
-                    default_value = current[key]
-                current[key] = defaultdict(
-                    lambda: default_value,
-                    value,
-                )
-
-    def _sanitize_ambiguous(style: dict):
-        """Fix a few ambiguous cases in the style dict."""
-
-        # Accept "node" style as "vertex" style for user flexibility
-        if "node" in style:
-            style_node = style.pop("node")
-            if "vertex" not in style:
-                style["vertex"] = style_node
-            else:
-                # "node" style applies on TOP of "vertex" style
-                _update(style_node, style["vertex"])
-
-        # NOTE: Deprecate edge_padding for edge_shrink
-        for edgekey in ["edge", "leafedge"]:
-            if "padding" in style.get(edgekey, {}):
-                # shrink takes over
-                if "shrink" in style[edgekey]:
-                    del style[edgekey]["padding"]
-                else:
-                    style[edgekey]["shrink"] = style[edgekey].pop("padding")
 
     merged = {}
     for style in styles:
         if isinstance(style, str):
             style = get_style(style)
         else:
-            _sanitize_leaves(style)
+            sanitize_leaves(style)
             unflatten_style(style)
-            _sanitize_ambiguous(style)
-        _update(style, merged)
+            sanitize_ambiguous(style)
+        update_style(style, merged)
 
     return merged
 

{iplotx-0.7.0 → iplotx-0.9.0}/iplotx/tree.py

@@ -193,6 +193,10 @@ class TreeArtist(mpl.artist.Artist):
         """Get vertex or edge layout."""
         layout_columns = [f"_ipx_layout_{i}" for i in range(self._ipx_internal_data["ndim"])]
 
+        # Equivalence vertex <-> node
+        if kind == "node":
+            kind = "vertex"
+
         if kind == "vertex":
             layout = self._ipx_internal_data["vertex_df"][layout_columns]
             return layout
@@ -245,6 +249,10 @@ class TreeArtist(mpl.artist.Artist):
         return bbox
 
     def _get_label_series(self, kind: str) -> Optional[pd.Series]:
+        # Equivalence vertex <-> node
+        if kind == "node":
+            kind = "vertex"
+
         if "label" in self._ipx_internal_data[f"{kind}_df"].columns:
             return self._ipx_internal_data[f"{kind}_df"]["label"]
         else:
@@ -254,6 +262,8 @@ class TreeArtist(mpl.artist.Artist):
         """Get VertexCollection artist."""
         return self._vertices
 
+    get_nodes = get_vertices
+
     def get_edges(self) -> EdgeCollection:
         """Get EdgeCollection artist."""
         return self._edges
@@ -262,6 +272,8 @@ class TreeArtist(mpl.artist.Artist):
         """Get leaf VertexCollection artist."""
         return self._leaf_vertices
 
+    get_leaf_nodes = get_leaf_vertices
+
     def get_leaf_edges(self) -> Optional[LeafEdgeCollection]:
         """Get LeafEdgeCollection artist if present."""
         if hasattr(self, "_leaf_edges"):
@@ -272,6 +284,8 @@ class TreeArtist(mpl.artist.Artist):
         """Get list of vertex label artists."""
         return self._vertices.get_labels()
 
+    get_node_labels = get_vertex_labels
+
     def get_edge_labels(self) -> LabelCollection:
         """Get list of edge label artists."""
         return self._edges.get_labels()

iplotx-0.9.0/iplotx/utils/style.py

@@ -0,0 +1,128 @@
+import copy
+from collections import defaultdict
+
+from ..style.leaf_info import (
+    style_leaves,
+)
+
+try:
+    import networkx as nx
+except ImportError:
+    nx = None
+
+
+def copy_with_deep_values(style):
+    """Make a deep copy of the style dict but do not create copies of the keys."""
+    # Defaultdict should be respected
+    if hasattr(style, "default_factory"):
+        newdict = defaultdict(lambda: style.default_factory())
+    else:
+        newdict = {}
+    for key, value in style.items():
+        if isinstance(value, dict):
+            newdict[key] = copy_with_deep_values(value)
+        else:
+            newdict[key] = copy.copy(value)
+    return newdict
+
+
+def sanitize_leaves(style: dict):
+    """Sanitize the leaves of a style dictionary.
+
+    Parameters:
+        style (dict): A style dictionary.
+    Returns:
+        None: The style dictionary is modified in place.
+    """
+    for key, value in style.items():
+        if key in style_leaves:
+            # Networkx has a few lazy data structures
+            # TODO: move this code to provider
+            if nx is not None:
+                if isinstance(value, nx.classes.reportviews.NodeView):
+                    style[key] = dict(value)
+                elif isinstance(value, nx.classes.reportviews.EdgeViewABC):
+                    style[key] = [v for *e, v in value]
+
+        elif isinstance(value, dict):
+            sanitize_leaves(value)
+
+
+def update_style(new_style: dict, current_style: dict):
+    """Update the current style with a new style.
+
+    Parameters:
+        new_style (dict): A new style dictionary.
+        current_style (dict): The current style dictionary.
+    Returns:
+        None: The current style dictionary is modified in place.
+    """
+    for key, value in new_style.items():
+        if key not in current_style:
+            current_style[key] = value
+            continue
+
+        # Style non-leaves are either recurred into or deleted
+        if key not in style_leaves:
+            if isinstance(value, dict):
+                update_style(value, current_style[key])
+            elif value is None:
+                del current_style[key]
+            else:
+                raise ValueError(
+                    f"Setting non-leaf style value to a non-dict: {key}, {value}",
+                )
+        else:
+            # Style leaves could be incomplete, ensure a sensible default
+            if value is None:
+                del current_style[key]
+                continue
+
+            if not isinstance(value, dict):
+                current_style[key] = value
+                continue
+
+            if hasattr(value, "default_factory"):
+                current_style[key] = value
+                continue
+
+            if hasattr(current_style[key], "default_factory"):
+                default_value = current_style[key].default_factory()
+            else:
+                default_value = current_style[key]
+            current_style[key] = defaultdict(
+                lambda: default_value,
+                value,
+            )
+
+
+def sanitize_ambiguous(style: dict):
+    """Fix a few ambiguous cases in the style dict.
+
+    Parameters:
+        style (dict): A style dictionary. This must be unflattened beforehand.
+    Returns:
+        None: The style dictionary is modified in place.
+
+    NOTE: This function exists by design, not accident. It is useful for purposeful
+    (e.g. node vs vertex) or historical (e.g. edge_padding vs edge_shrink) reasons.
+    Either way, it softens the user experience without complicating the API.
+    """
+
+    # Accept "node" style as "vertex" style for user flexibility
+    if "node" in style:
+        style_node = style.pop("node")
+        if "vertex" not in style:
+            style["vertex"] = style_node
+        else:
+            # "node" style applies on TOP of "vertex" style
+            update_style(style_node, style["vertex"])
+
+    # NOTE: Deprecate edge_padding for edge_shrink
+    for edgekey in ["edge", "leafedge"]:
+        if "padding" in style.get(edgekey, {}):
+            # shrink takes over
+            if "shrink" in style[edgekey]:
+                del style[edgekey]["padding"]
+            else:
+                style[edgekey]["shrink"] = style[edgekey].pop("padding")

{iplotx-0.7.0 → iplotx-0.9.0}/iplotx/version.py

@@ -2,4 +2,4 @@
 iplotx version information module.
 """
 
-__version__ = "0.7.0"
+__version__ = "0.9.0"

{iplotx-0.7.0 → iplotx-0.9.0}/tests/test_igraph.py

@@ -31,19 +31,19 @@ class GraphTestRunner(unittest.TestCase):
     def test_basic(self):
         g = ig.Graph.Ring(5)
         fig, ax = plt.subplots(figsize=(3, 3))
-        ipx.plot(g, ax=ax, layout=self.layout_small_ring)
+        ipx.graph(g, ax=ax, layout=self.layout_small_ring)
 
     @image_comparison(baseline_images=["graph_directed"], remove_text=True)
     def test_directed(self):
         g = ig.Graph.Ring(5, directed=True)
         fig, ax = plt.subplots(figsize=(3, 3))
-        ipx.plot(g, ax=ax, layout=self.layout_small_ring)
+        ipx.graph(g, ax=ax, layout=self.layout_small_ring)
 
     @image_comparison(baseline_images=["graph_vertexsize"], remove_text=True)
     def test_vertexsize(self):
         g = ig.Graph.Ring(5)
         fig, ax = plt.subplots(figsize=(3, 3))
-        ipx.plot(
+        ipx.graph(
             g,
             ax=ax,
             layout=self.layout_small_ring,
@@ -55,7 +55,7 @@ class GraphTestRunner(unittest.TestCase):
     def test_labels(self):
         g = ig.Graph.Ring(5)
         fig, ax = plt.subplots(figsize=(3, 3))
-        ipx.plot(
+        ipx.graph(
             network=g,
             ax=ax,
             layout=self.layout_small_ring,
@@ -76,14 +76,14 @@ class GraphTestRunner(unittest.TestCase):
         g = ig.Graph.Ring(5)
         layout = g.layout("circle")
         fig, ax = plt.subplots(figsize=(3, 3))
-        ipx.plot(g, layout=layout, ax=ax)
+        ipx.graph(g, layout=layout, ax=ax)
 
     @image_comparison(baseline_images=["graph_layout_attribute"], remove_text=True)
     def test_layout_attribute_alt(self):
         g = ig.Graph.Ring(5)
         g["layout"] = ig.Layout([(x, x) for x in range(g.vcount())])
         fig, ax = plt.subplots(figsize=(3, 3))
-        ipx.plot(g, layout="layout", ax=ax)
+        ipx.graph(g, layout="layout", ax=ax)
 
     @image_comparison(baseline_images=["graph_directed_curved_loops"], remove_text=True)
     def test_directed_curved_loops(self):
@@ -94,7 +94,7 @@ class GraphTestRunner(unittest.TestCase):
         fig, ax = plt.subplots(figsize=(4, 4))
         # ax.set_xlim(-1.2, 1.2)
         # ax.set_ylim(-1.2, 1.2)
-        ipx.plot(
+        ipx.graph(
             g,
             ax=ax,
             layout=self.layout_small_ring,
@@ -112,7 +112,7 @@ class GraphTestRunner(unittest.TestCase):
     def test_mark_groups_squares(self):
         g = ig.Graph.Ring(5, directed=True)
         fig, ax = plt.subplots(figsize=(3, 3))
-        ipx.plot(
+        ipx.graph(
             g,
             ax=ax,
             layout=self.layout_small_ring,
@@ -125,7 +125,7 @@ class GraphTestRunner(unittest.TestCase):
     def test_edit_children(self):
         g = ig.Graph.Ring(5)
         fig, ax = plt.subplots(figsize=(4, 4))
-        ipx.plot(
+        ipx.graph(
             g,
             ax=ax,
             style={"vertex": {"marker": "o"}},
@@ -148,7 +148,7 @@ class GraphTestRunner(unittest.TestCase):
         fig, ax = plt.subplots()
         lo = g.layout("circle")
         lo.scale(3)
-        ipx.plot(
+        ipx.graph(
             g,
             ax=ax,
             layout=lo,
@@ -176,7 +176,7 @@ class GraphTestRunner(unittest.TestCase):
         fig, ax = plt.subplots()
         lo = g.layout("circle")
         lo.scale(3)
-        ipx.plot(
+        ipx.graph(
             g,
             ax=ax,
             layout=lo,
@@ -201,7 +201,7 @@ class GraphTestRunner(unittest.TestCase):
     def test_null_graph(self):
         g = ig.Graph()
         fig, ax = plt.subplots()
-        ipx.plot(g, ax=ax)
+        ipx.graph(g, ax=ax)
         ax.set_aspect(1.0)
 
 
@@ -278,14 +278,14 @@ class ClusteringTestRunner(unittest.TestCase):
         g = ig.Graph.Ring(5, directed=True)
         clu = ig.VertexClustering(g, [0] * 5)
         fig, ax = plt.subplots()
-        ipx.plot(g, grouping=clu, ax=ax, layout=self.layout_small_ring)
+        ipx.graph(g, grouping=clu, ax=ax, layout=self.layout_small_ring)
 
     @image_comparison(baseline_images=["clustering_directed_large"], remove_text=True)
     def test_clustering_directed_large(self):
         g = ig.Graph.Ring(50, directed=True)
         clu = ig.VertexClustering(g, [0] * 3 + [1] * 17 + [2] * 30)
         fig, ax = plt.subplots()
-        ipx.plot(
+        ipx.graph(
             g,
             grouping=clu,
             style={

{iplotx-0.7.0 → iplotx-0.9.0}/tests/test_networkx.py

@@ -26,14 +26,14 @@ class GraphTestRunner(unittest.TestCase):
             ]
         )
         pos = {1: (0, 0), 2: (-1, 0.3), 3: (2, 0.17), 4: (4, 0.255), 5: (5, 0.03)}
-        ipx.plot(
+        ipx.network(
             G,
             layout=pos,
-            vertex_labels=False,
-            vertex_size=5,
-            vertex_facecolor="white",
-            vertex_edgecolor="black",
-            vertex_linewidth=3,
+            node_labels=False,
+            node_size=5,
+            node_facecolor="white",
+            node_edgecolor="black",
+            node_linewidth=3,
             edge_linewidth=3,
             edge_color=["grey", "black"],
             margins=0.1,
@@ -52,10 +52,10 @@ class GraphTestRunner(unittest.TestCase):
         # explicitly set positions
         pos = {1: (0, 0), 2: (-1, 0.3), 3: (2, 0.17), 4: (4, 0.255), 5: (5, 0.03)}
 
-        ipx.plot(
+        ipx.network(
             G,
             layout=pos,
-            vertex_labels=True,
+            node_labels=True,
             style={
                 "vertex": {
                     "size": "label",
@@ -224,11 +224,11 @@ class GraphTestRunner(unittest.TestCase):
         )
 
         fig, ax = plt.subplots()
-        ipx.plot(
+        ipx.network(
             G,
             ax=ax,
             layout="pos",
-            vertex_labels=True,
+            node_labels=True,
             edge_labels=True,
         )
 
@@ -298,11 +298,11 @@ class GraphTestRunner(unittest.TestCase):
         )
 
         fig, ax = plt.subplots(figsize=(5, 4))
-        ipx.plot(
+        ipx.network(
             G,
             ax=ax,
             layout="pos",
-            vertex_labels=True,
+            node_labels=True,
             style={
                 "vertex": {
                     "facecolor": G.nodes.data("color"),

iplotx-0.7.0/iplotx/utils/style.py

@@ -1,17 +0,0 @@
-import copy
-from collections import defaultdict
-
-
-def copy_with_deep_values(style):
-    """Make a deep copy of the style dict but do not create copies of the keys."""
-    # Defaultdict should be respected
-    if hasattr(style, "default_factory"):
-        newdict = defaultdict(lambda: style.default_factory())
-    else:
-        newdict = {}
-    for key, value in style.items():
-        if isinstance(value, dict):
-            newdict[key] = copy_with_deep_values(value)
-        else:
-            newdict[key] = copy.copy(value)
-    return newdict