iplotx 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

iplotx/utils/matplotlib.py

@@ -1,5 +1,6 @@
 from functools import wraps, partial
 from math import atan2
+import numpy as np
 import matplotlib as mpl
 
 from .geometry import (
@@ -29,6 +30,7 @@ def _forwarder(forwards, cls=None):
 
     def make_forward(name):
         def method(self, *args, **kwargs):
+            """Each decorated method is called on the decorated class and then, nonrecursively, on all children."""
             ret = getattr(cls.mro()[1], name)(self, *args, **kwargs)
             for c in self.get_children():
                 getattr(c, name)(*args, **kwargs)
@@ -46,7 +48,13 @@ def _forwarder(forwards, cls=None):
 
 
 def _additional_set_methods(attributes, cls=None):
-    """Decorator to add specific set methods for children properties."""
+    """Decorator to add specific set methods for children properties.
+
+    This is useful to autogenerate methods a la set_<key>(value), for
+    instance set_alpha(value). It works by delegating to set(alpha=value).
+
+    Overall, this is a minor tweak compared to the previous decorator.
+    """
     if cls is None:
         return partial(_additional_set_methods, attributes)
 
@@ -73,64 +81,76 @@ def _additional_set_methods(attributes, cls=None):
 # many use cases.
 def _get_label_width_height(text, hpadding=18, vpadding=12, **kwargs):
     """Get the bounding box size for a text with certain properties."""
-    forbidden_props = ["horizontalalignment", "verticalalignment", "ha", "va"]
+    forbidden_props = [
+        "horizontalalignment",
+        "verticalalignment",
+        "ha",
+        "va",
+        "color",
+        "edgecolor",
+        "facecolor",
+    ]
     for prop in forbidden_props:
         if prop in kwargs:
             del kwargs[prop]
 
     path = mpl.textpath.TextPath((0, 0), text, **kwargs)
     boundingbox = path.get_extents()
-    width = boundingbox.width + hpadding
-    height = boundingbox.height + vpadding
+    width = boundingbox.width
+    height = boundingbox.height
+
+    # Scaling with font size appears broken... try to patch it up linearly here, even though we know it don't work well
+    width *= kwargs.get("size", 12) / 12.0
+    height *= kwargs.get("size", 12) / 12.0
+
+    width += hpadding
+    height += vpadding
     return (width, height)
 
 
-def _compute_mid_coord(path):
+def _compute_mid_coord_and_rot(path, trans):
     """Compute mid point of an edge, straight or curved."""
     # Distinguish between straight and curved paths
     if path.codes[-1] == mpl.path.Path.LINETO:
-        return path.vertices.mean(axis=0)
+        coord = path.vertices.mean(axis=0)
+        vtr = trans(path.vertices)
+        rot = atan2(
+            vtr[-1, 1] - vtr[0, 1],
+            vtr[-1, 0] - vtr[0, 0],
+        )
 
     # Cubic Bezier
-    if path.codes[-1] == mpl.path.Path.CURVE4:
-        return _evaluate_cubic_bezier(path.vertices, 0.5)
+    elif path.codes[-1] == mpl.path.Path.CURVE4:
+        coord = _evaluate_cubic_bezier(path.vertices, 0.5)
+        # TODO:
+        rot = 0
 
     # Square Bezier
-    if path.codes[-1] == mpl.path.Path.CURVE3:
-        return _evaluate_squared_bezier(path.vertices, 0.5)
-
-    raise ValueError(
-        "Curve type not straight and not squared/cubic Bezier, cannot compute mid point."
-    )
+    elif path.codes[-1] == mpl.path.Path.CURVE3:
+        coord = _evaluate_squared_bezier(path.vertices, 0.5)
+        # TODO:
+        rot = 0
 
+    else:
+        raise ValueError(
+            "Curve type not straight and not squared/cubic Bezier, cannot compute mid point."
+        )
 
-def _compute_group_path_with_vertex_padding(
-    points,
-    transform,
-    vertexpadding=10,
-):
-    """Offset path for a group based on vertex padding.
+    return coord, rot
 
-    At the input, the structure is [v1, v1, v1, v2, v2, v2, ...]
-    """
 
-    # Transform into figure coordinates
-    trans = transform.transform
-    trans_inv = transform.inverted().transform
-    points = trans(points)
+def _build_cmap_fun(values, cmap):
+    """Map colormap on top of numerical values."""
+    cmap = mpl.cm._ensure_cmap(cmap)
 
-    npoints = len(points) // 3
-    vprev = points[-1]
-    mprev = atan2(points[0, 1] - vprev[1], points[0, 0] - vprev[0])
-    for i, vcur in enumerate(points[::3]):
-        vnext = points[(i + 1) * 3]
-        mnext = atan2(vnext[1] - vcur[1], vnext[0] - vcur[0])
+    if np.isscalar(values):
+        values = [values]
 
-        mprev_orth = -1 / mprev
-        points[i * 3] = vcur + vertexpadding * mprev_orth
+    if isinstance(values, dict):
+        values = np.array(list(values.values()))
 
-        vprev = vcur
-        mprev = mnext
+    vmin = np.nanmin(values)
+    vmax = np.nanmax(values)
+    norm = mpl.colors.Normalize(vmin=vmin, vmax=vmax)
 
-    points = trans_inv(points)
-    return points
+    return lambda x: cmap(norm(x))

iplotx/utils/style.py

@@ -0,0 +1 @@
+from copy import copy

iplotx/version.py

@@ -1 +1,5 @@
-__version__ = "0.1.0"
+"""
+iplotx version information module.
+"""
+
+__version__ = "0.2.1"

iplotx/vertex.py

@@ -1,51 +1,129 @@
+"""
+Module containing code to manipulate vertex visualisations, especially the VertexCollection class.
+"""
+
+from typing import (
+    Optional,
+    Sequence,
+    Any,
+)
+import warnings
 import numpy as np
-from matplotlib.transforms import IdentityTransform
+import pandas as pd
+import matplotlib as mpl
 from matplotlib.collections import PatchCollection
 from matplotlib.patches import (
+    Patch,
     Ellipse,
     Circle,
     RegularPolygon,
     Rectangle,
 )
 
+from .style import (
+    get_style,
+    rotate_style,
+    copy_with_deep_values,
+)
+from .utils.matplotlib import (
+    _get_label_width_height,
+    _build_cmap_fun,
+    _forwarder,
+)
+from .label import LabelCollection
+
 
+@_forwarder(
+    (
+        "set_clip_path",
+        "set_clip_box",
+        "set_snap",
+        "set_sketch_params",
+        "set_animated",
+        "set_picker",
+    )
+)
 class VertexCollection(PatchCollection):
-    """Collection of vertex patches for plotting.
+    """Collection of vertex patches for plotting."""
 
-    This class takes additional keyword arguments compared to PatchCollection:
+    _factor = 1.0
 
-    @param vertex_builder: A list of vertex builders to construct the visual
-        vertices. This is updated if the size of the vertices is changed.
-    @param size_callback: A function to be triggered after vertex sizes are
-        changed. Typically this redraws the edges.
-    """
+    def __init__(
+        self,
+        layout: pd.DataFrame,
+        *args,
+        layout_coordinate_system: str = "cartesian",
+        style: Optional[dict[str, Any]] = None,
+        labels: Optional[Sequence[str]] = None,
+        **kwargs,
+    ):
+        """Initialise the VertexCollection.
 
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
+        Parameters:
+            layout: The vertex layout.
+            layout_coordinate_system: The coordinate system for the layout, usually "cartesian").
+            style: The vertex style (subdictionary "vertex") to apply.
+            labels: The vertex labels, if present.
+        """
 
-    def get_sizes(self):
-        """Same as get_size."""
-        return self.get_size()
+        self._index = layout.index
+        self._style = style
+        self._labels = labels
+        self._layout = layout
+        self._layout_coordinate_system = layout_coordinate_system
 
-    def get_size(self):
-        """Get vertex sizes.
+        # Create patches from structured data
+        patches, sizes, kwargs2 = self._init_vertex_patches()
 
-        If width and height are unequal, get the largest of the two.
+        kwargs.update(kwargs2)
+        kwargs["match_original"] = True
 
-        @return: An array of vertex sizes.
+        # Pass to PatchCollection constructor
+        super().__init__(patches, *args, **kwargs)
+
+        # Set offsets in coordinate system
+        self._update_offsets_from_layout()
+
+        # Compute _transforms like in _CollectionWithScales for dpi issues
+        self.set_sizes(sizes)
+
+        if self._labels is not None:
+            self._compute_label_collection()
+
+    def get_children(self) -> tuple[mpl.artist.Artist]:
+        """Get the children artists.
+
+        This can include the labels as a LabelCollection.
         """
-        import numpy as np
+        children = []
+        if hasattr(self, "_label_collection"):
+            children.append(self._label_collection)
+        return tuple(children)
 
-        sizes = []
-        for path in self.get_paths():
-            bbox = path.get_extents()
-            mins, maxs = bbox.min, bbox.max
-            width, height = maxs - mins
-            size = max(width, height)
-            sizes.append(size)
-        return np.array(sizes)
+    def set_figure(self, fig) -> None:
+        """Set the figure for this artist and all children."""
+        super().set_figure(fig)
+        self.set_sizes(self._sizes, self.get_figure(root=True).dpi)
+        for child in self.get_children():
+            child.set_figure(fig)
 
-    def set_size(self, sizes):
+    def get_index(self):
+        """Get the VertexCollection index."""
+        return self._index
+
+    def get_vertex_id(self, index):
+        """Get the id of a single vertex at a positional index."""
+        return self._index[index]
+
+    def get_sizes(self):
+        """Get vertex sizes (max of width and height), not scaled by dpi."""
+        return self._sizes
+
+    def get_sizes_dpi(self):
+        """Get vertex sizes (max of width and height), scaled by dpi."""
+        return self._transforms[:, 0, 0]
+
+    def set_sizes(self, sizes, dpi: float = 72.0) -> None:
         """Set vertex sizes.
 
         This rescales the current vertex symbol/path linearly, using this
@@ -53,26 +131,163 @@ class VertexCollection(PatchCollection):
 
         @param sizes: A sequence of vertex sizes or a single size.
         """
-        paths = self._paths
-        try:
-            iter(sizes)
-        except TypeError:
-            sizes = [sizes] * len(paths)
-
-        sizes = list(sizes)
-        current_sizes = self.get_sizes()
-        for path, cursize in zip(paths, current_sizes):
-            # Circular use of sizes
-            size = sizes.pop(0)
-            sizes.append(size)
-            # Rescale the path for this vertex
-            path.vertices *= size / cursize
+        if sizes is None:
+            self._sizes = np.array([])
+            self._transforms = np.empty((0, 3, 3))
+        else:
+            self._sizes = np.asarray(sizes)
+            self._transforms = np.zeros((len(self._sizes), 3, 3))
+            scale = self._sizes * dpi / 72.0 * self._factor
+            self._transforms[:, 0, 0] = scale
+            self._transforms[:, 1, 1] = scale
+            self._transforms[:, 2, 2] = 1.0
+        self.stale = True
+
+    get_size = get_sizes
+    set_size = set_sizes
+
+    def get_layout(self) -> pd.DataFrame:
+        """Get the vertex layout.
+
+        Returns:
+            The vertex layout as a DataFrame.
+        """
+        return self._layout
+
+    def get_layout_coordinate_system(self) -> str:
+        """Get the layout coordinate system.
+
+        Returns:
+            Name of the layout coordinate system, e.g. "cartesian" or "polar".
+        """
+        return self._layout_coordinate_system
+
+    def get_offsets(self, ignore_layout: bool = True) -> np.ndarray:
+        """Get the vertex offsets.
 
+        Parameters:
+            ignore_layout: If True, return the matplotlib Artist._offsets directly, ignoring the
+                layout coordinate system. If False, it's equivalent to get_layout().values.
+
+        Returns:
+            The vertex offsets as a 2D numpy array.
+
+        Note: It is best for users to *not* ignore the layout coordinate system, as it may lead
+        to inconsistencies. However, some internal matplotlib functions require the default
+        signature of this function to look at the vanilla offsets, hence the default parameters.
+        """
+        if not ignore_layout:
+            return self.get_layout().values
+        else:
+            return self._offsets
+
+    def _update_offsets_from_layout(self) -> None:
+        """Update offsets in matplotlib coordinates from the layout DataFrame."""
+        if self._layout_coordinate_system == "cartesian":
+            self._offsets = self._layout.values
+        elif self._layout_coordinate_system == "polar":
+            # Convert polar coordinates (r, theta) to cartesian (x, y)
+            r = self._layout.iloc[:, 0].values
+            theta = self._layout.iloc[:, 1].values
+            if self._offsets is None:
+                self._offsets = np.zeros((len(r), 2))
+            self._offsets[:, 0] = r * np.cos(theta)
+            self._offsets[:, 1] = r * np.sin(theta)
+        else:
+            raise ValueError(
+                f"Layout coordinate system not supported: {self._layout_coordinate_system}."
+            )
+
+    def set_offsets(self, offsets: np.ndarray) -> None:
+        """Set the vertex positions/offsets in layout coordinates.
+
+        Parameters:
+            offsets: Array of coordinates in the layout coordinate system. For polar layouts,
+                these should be in the form of (r, theta) pairs.
+        """
+        self._layout.values[:] = offsets
+        self._update_offsets_from_layout()
         self.stale = True
 
-    def set_sizes(self, sizes):
-        """Same as set_size."""
-        self.set_size(sizes)
+    def _init_vertex_patches(self):
+        style = self._style or {}
+        if "cmap" in style:
+            cmap_fun = _build_cmap_fun(
+                style["facecolor"],
+                style["cmap"],
+            )
+        else:
+            cmap_fun = None
+
+        if style.get("size", 20) == "label":
+            if self._labels is None:
+                warnings.warn(
+                    "No labels found, cannot resize vertices based on labels."
+                )
+                style["size"] = get_style("default.vertex")["size"]
+
+        if "cmap" in style:
+            colorarray = []
+        patches = []
+        sizes = []
+        for i, (vid, row) in enumerate(self._layout.iterrows()):
+            if style.get("size", 20) == "label":
+                # NOTE: it's ok to overwrite the dict here
+                style["size"] = _get_label_width_height(
+                    str(self._labels[vid]), **style.get("label", {})
+                )
+
+            stylei = rotate_style(style, index=i, key=vid)
+            if cmap_fun is not None:
+                colorarray.append(style["facecolor"])
+                stylei["facecolor"] = cmap_fun(stylei["facecolor"])
+
+            # Shape of the vertex (Patch)
+            art, size = make_patch(**stylei)
+            patches.append(art)
+            sizes.append(size)
+
+        kwargs = {}
+        if "cmap" in style:
+            vmin = np.min(colorarray)
+            vmax = np.max(colorarray)
+            norm = mpl.colors.Normalize(vmin=vmin, vmax=vmax)
+            kwargs["cmap"] = style["cmap"]
+            kwargs["norm"] = norm
+
+        return patches, sizes, kwargs
+
+    def _compute_label_collection(self):
+        transform = self.get_offset_transform()
+
+        style = (
+            copy_with_deep_values(self._style.get("label", None))
+            if self._style is not None
+            else {}
+        )
+        forbidden_props = ["hpadding", "vpadding"]
+        for prop in forbidden_props:
+            if prop in style:
+                del style[prop]
+
+        self._label_collection = LabelCollection(
+            self._labels,
+            style=style,
+            offsets=self._offsets,
+            transform=transform,
+        )
+
+    def get_labels(self):
+        """Get the vertex labels.
+
+        Returns:
+            The artist with the LabelCollection.
+        """
+
+        if hasattr(self, "_label_collection"):
+            return self._label_collection
+        else:
+            return None
 
     @property
     def stale(self):
@@ -84,29 +299,64 @@ class VertexCollection(PatchCollection):
         if val and hasattr(self, "stale_callback_post"):
             self.stale_callback_post(self)
 
+    @mpl.artist.allow_rasterization
+    def draw(self, renderer):
+        if not self.get_visible():
+            return
+
+        # null graph, no need to draw anything
+        # NOTE: I would expect this to be already a clause in the superclass by oh well
+        if len(self.get_paths()) == 0:
+            return
+
+        self.set_sizes(self._sizes, self.get_figure(root=True).dpi)
+
+        # NOTE: This draws the vertices first, then the labels.
+        # The correct order would be vertex1->label1->vertex2->label2, etc.
+        # We might fix if we manage to find a way to do it.
+        super().draw(renderer)
+        for child in self.get_children():
+            child.draw(renderer)
 
-def make_patch(marker: str, size, **kwargs):
+
+def make_patch(
+    marker: str, size: float | Sequence[float], **kwargs
+) -> tuple[Patch, float]:
     """Make a patch of the given marker shape and size."""
-    forbidden_props = ["label"]
+    forbidden_props = ["label", "cmap", "norm"]
     for prop in forbidden_props:
         if prop in kwargs:
             kwargs.pop(prop)
 
-    if isinstance(size, (int, float)):
+    if np.isscalar(size):
+        size = float(size)
         size = (size, size)
 
-    if marker in ("o", "circle"):
-        return Circle((0, 0), size[0] / 2, **kwargs)
+    # Size of vertices is determined in self._transforms, which scales with dpi, rather than here,
+    # so normalise by the average dimension (btw x and y) to keep the ratio of the marker.
+    # If you check in get_sizes, you will see that rescaling also happens with the max of width
+    # and height.
+    size = np.asarray(size, dtype=float)
+    size_max = size.max()
+    if size_max > 0:
+        size /= size_max
+
+    art: Patch
+    if marker in ("o", "c", "circle"):
+        art = Circle((0, 0), size[0] / 2, **kwargs)
     elif marker in ("s", "square", "r", "rectangle"):
-        return Rectangle((-size[0] / 2, -size[1] / 2), size[0], size[1], **kwargs)
+        art = Rectangle((-size[0] / 2, -size[1] / 2), size[0], size[1], **kwargs)
     elif marker in ("^", "triangle"):
-        return RegularPolygon((0, 0), numVertices=3, radius=size[0] / 2, **kwargs)
+        art = RegularPolygon((0, 0), numVertices=3, radius=size[0] / 2, **kwargs)
     elif marker in ("d", "diamond"):
-        return make_patch("s", size[0], angle=45, **kwargs)
+        art, _ = make_patch("s", size[0], angle=45, **kwargs)
     elif marker in ("v", "triangle_down"):
-        return RegularPolygon(
+        art = RegularPolygon(
             (0, 0), numVertices=3, radius=size[0] / 2, orientation=np.pi, **kwargs
         )
     elif marker in ("e", "ellipse"):
-        return Ellipse((0, 0), size[0] / 2, size[1] / 2, **kwargs)
-    raise KeyError(f"Unknown marker: {marker}")
+        art = Ellipse((0, 0), size[0] / 2, size[1] / 2, **kwargs)
+    else:
+        raise KeyError(f"Unknown marker: {marker}")
+
+    return (art, size_max)

iplotx-0.2.1.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: iplotx
+Version: 0.2.1
+Summary: Plot networkx from igraph and networkx.
+Project-URL: Homepage, https://github.com/fabilab/iplotx
+Project-URL: Documentation, https://readthedocs.org/iplotx
+Project-URL: Repository, https://github.com/fabilab/iplotx.git
+Project-URL: Bug Tracker, https://github.com/fabilab/iplotx/issues
+Project-URL: Changelog, https://github.com/fabilab/iplotx/blob/main/CHANGELOG.md
+Author-email: Fabio Zanini <fabio.zanini@unsw.edu.au>
+Maintainer-email: Fabio Zanini <fabio.zanini@unsw.edu.au>
+License: MIT
+Keywords: graph,network,plotting,visualisation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=2.0.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pylint>=3.3.7
+Provides-Extra: igraph
+Requires-Dist: igraph>=0.11.0; extra == 'igraph'
+Provides-Extra: networkx
+Requires-Dist: networkx>=2.0.0; extra == 'networkx'
+Description-Content-Type: text/markdown
+
+![Github Actions](https://github.com/fabilab/iplotx/actions/workflows/test.yml/badge.svg)
+![PyPI - Version](https://img.shields.io/pypi/v/iplotx)
+![RTD](https://readthedocs.org/projects/iplotx/badge/?version=latest)
+![pylint](assets/pylint.svg)
+
+# iplotx
+Plotting networks from igraph and networkx.
+
+**NOTE**: This is currently beta quality software. The API and functionality are settling in and might break occasionally.
+
+## Installation
+```bash
+pip install iplotx
+```
+
+## Quick Start
+```python
+import networkx as nx
+import matplotlib.pyplot as plt
+import iplotx as ipx
+
+g = nx.Graph([(0, 1), (1, 2), (2, 3), (3, 4), (4, 0)])
+layout = nx.layout.circular_layout(g)
+fig, ax = plt.subplots(figsize=(3, 3))
+ipx.plot(g, ax=ax, layout=layout)
+```
+
+![Quick start image](docs/source/_static/graph_basic.png)
+
+## Documentation
+See [readthedocs](https://iplotx.readthedocs.io/en/latest/) for the full documentation.
+
+## Gallery
+See [gallery](https://iplotx.readthedocs.io/en/latest/gallery/index.html).
+
+## Roadmap
+- Plot networks from igraph and networkx interchangeably, using matplotlib as a backend. ✅
+- Support interactive plotting, e.g. zooming and panning after the plot is created. ✅
+- Support storing the plot to disk thanks to the many matplotlib backends (SVG, PNG, PDF, etc.). ✅
+- Support flexible yet easy styling. ✅
+- Efficient plotting of large graphs using matplotlib's collection functionality. ✅
+- Support editing plotting elements after the plot is created, e.g. changing node colors, labels, etc. ✅
+- Support animations, e.g. showing the evolution of a network over time. ✅
+- Support trees from special libraries such as ete3, biopython, etc. This will need a dedicated function and layouting. ✅
+- Support uni- and bi-directional communication between graph object and plot object.🏗️
+
+**NOTE:** The last item can probably be achieved already by using `matplotlib`'s existing callback functionality. It is currently untested, but if you manage to get it to work on your graph let me know and I'll add it to the examples (with credit).
+
+## Authors
+Fabio Zanini (https://fabilab.org)