iplotx 0.0.1__py3-none-any.whl

iplotx/styles.py

@@ -0,0 +1,186 @@
+from typing import Union, Sequence, Hashable
+from copy import deepcopy
+from contextlib import contextmanager
+import numpy as np
+import pandas as pd
+
+
+style_leaves = (
+    "edgecolor",
+    "facecolor",
+    "linewidth",
+    "linestyle",
+    "alpha",
+    "zorder",
+)
+
+
+default = {
+    "vertex": {
+        "size": 20,
+        "facecolor": "black",
+        "marker": "o",
+        "label": {
+            "horizontalalignment": "center",
+            "verticalalignment": "center",
+            "hpadding": 18,
+            "vpadding": 12,
+        },
+    },
+    "edge": {
+        "linewidth": 1.5,
+        "linestyle": "-",
+        "color": "black",
+        "curved": False,
+        "offset": 3,
+        "tension": 1,
+        "label": {
+            "horizontalalignment": "center",
+            "verticalalignment": "center",
+        },
+    },
+    "arrow": {
+        "marker": "|>",
+        "width": 8,
+        "color": "black",
+    },
+    "grouping": {
+        "facecolor": ["grey", "steelblue", "tomato"],
+        "edgecolor": "black",
+        "linewidth": 1.5,
+        "alpha": 0.5,
+        "vertexpadding": 25,
+    },
+}
+
+hollow = deepcopy(default)
+hollow["vertex"]["color"] = None
+hollow["vertex"]["facecolor"] = "none"
+hollow["vertex"]["edgecolor"] = "black"
+hollow["vertex"]["linewidth"] = 1.5
+hollow["vertex"]["marker"] = "r"
+hollow["vertex"]["size"] = "label"
+
+
+styles = {
+    "default": default,
+    "hollow": hollow,
+}
+
+
+stylename = "default"
+
+
+current = deepcopy(styles["default"])
+
+
+def get_stylename():
+    """Return the name of the current iplotx style."""
+    return str(stylename)
+
+
+def get_style(name: str = ""):
+    namelist = name.split(".")
+    style = styles
+    for i, namei in enumerate(namelist):
+        if (i == 0) and (namei == ""):
+            style = current
+        else:
+            try:
+                style = style[namei]
+            except KeyError:
+                raise KeyError(f"Style not found: {name}")
+
+    style = deepcopy(style)
+    return style
+
+
+# The following is inspired by matplotlib's style library
+# https://github.com/matplotlib/matplotlib/blob/v3.10.3/lib/matplotlib/style/core.py#L45
+def use(style: Union[str, dict, Sequence]):
+    """Use iplotx style setting for a style specification.
+
+    The style name of 'default' is reserved for reverting back to
+    the default style settings.
+
+    Parameters:
+        style: A style specification, currently either a name of an existing style
+            or a dict with specific parts of the style to override. The string
+            "default" resets the style to the default one. If this is a sequence,
+            each style is applied in order.
+    """
+    global current
+
+    def _update(style: dict, current: dict):
+        for key, value in style.items():
+            if key not in current:
+                current[key] = value
+                continue
+
+            # Style leaves are by definition not to be recurred into
+            if isinstance(value, dict) and (key not in style_leaves):
+                _update(value, current[key])
+            elif value is None:
+                del current[key]
+            else:
+                current[key] = value
+
+    if isinstance(style, (dict, str)):
+        styles = [style]
+    else:
+        styles = style
+
+    for style in styles:
+        if style == "default":
+            reset()
+        else:
+            if isinstance(style, str):
+                current = get_style(style)
+            else:
+                _update(style, current)
+
+
+def reset():
+    """Reset to default style."""
+    global current
+    current = deepcopy(styles["default"])
+
+
+@contextmanager
+def stylecontext(style: Union[str, dict, Sequence]):
+    current = get_style()
+    try:
+        use(style)
+        yield
+    finally:
+        use(current)
+
+
+def rotate_style(
+    style,
+    index: Union[int, None] = None,
+    id: Union[Hashable, None] = None,
+    props=style_leaves,
+):
+    if (index is None) and (id is None):
+        raise ValueError(
+            "At least one of 'index' or 'id' must be provided to rotate_style."
+        )
+
+    style = deepcopy(style)
+
+    for prop in props:
+        val = style.get(prop, None)
+        if val is None:
+            continue
+        # NOTE: this assumes that these properties are leaves of the style tree
+        # Btw: dict includes defaultdict, Couter, etc.
+        if (id is not None) and isinstance(val, (dict, pd.Series)):
+            # This works on both dict-like and Series
+            style[prop] = val[id]
+        elif (index is not None) and isinstance(
+            val, (tuple, list, np.ndarray, pd.Index, pd.Series)
+        ):
+            style[prop] = np.asarray(val)[index % len(val)]
+
+    return style

iplotx/typing.py

@@ -0,0 +1,41 @@
+from typing import Union, Sequence
+from numpy import ndarray
+from pandas import DataFrame
+
+from .importing import igraph, networkx
+
+
+igraphGraph = igraph.Graph if igraph is None else None
+if networkx is not None:
+    from networkx import Graph as networkxGraph
+    from networkx import DiGraph as networkxDiGraph
+    from networkx import MultiGraph as networkxMultiGraph
+    from networkx import MultiDiGraph as networkxMultiDiGraph
+
+    networkxOmniGraph = Union[
+        networkxGraph, networkxDiGraph, networkxMultiGraph, networkxMultiDiGraph
+    ]
+else:
+    networkxOmniGraph = None
+
+if igraphGraph is not None and networkxOmniGraph is not None:
+    GraphType = Union[igraphGraph, networkxOmniGraph]
+elif igraphGraph is not None:
+    GraphType = igraphGraph
+else:
+    GraphType = networkxOmniGraph
+
+LayoutType = Union[str, Sequence[Sequence[float]], ndarray, DataFrame]
+
+if (igraph is not None) and (networkx is not None):
+    # networkx returns generators of sets, igraph has its own classes
+    # additionally, one can put list of memberships
+    GroupingType = Union[
+        Sequence[set],
+        igraph.clustering.Clustering,
+        igraph.clustering.VertexClustering,
+        igraph.clustering.Cover,
+        igraph.clustering.VertexCover,
+        Sequence[int],
+        Sequence[str],
+    ]

iplotx/utils/geometry.py

@@ -0,0 +1,227 @@
+from math import tan, atan2
+import numpy as np
+
+
+# See also this link for the general answer (using scipy to compute coefficients):
+# https://stackoverflow.com/questions/12643079/b%C3%A9zier-curve-fitting-with-scipy
+def _evaluate_squared_bezier(points, t):
+    """Evaluate a squared Bezier curve at t."""
+    p0, p1, p2 = points
+    return (1 - t) ** 2 * p0 + 2 * (1 - t) * t * p1 + t**2 * p2
+
+
+def _evaluate_cubic_bezier(points, t):
+    """Evaluate a cubic Bezier curve at t."""
+    p0, p1, p2, p3 = points
+    return (
+        (1 - t) ** 3 * p0
+        + 3 * (1 - t) ** 2 * t * p1
+        + 3 * (1 - t) * t**2 * p2
+        + t**3 * p3
+    )
+
+
+def convex_hull(points):
+    """Compute the convex hull of a set of 2D points."""
+    from ..importing import igraph
+
+    points = np.asarray(points)
+
+    # igraph's should be faster in 2D
+    if igraph is not None:
+        hull_idx = igraph.convex_hull(list(points))
+    else:
+        try:
+            from scipy.spatial import ConvexHull
+
+            hull_idx = ConvexHull(points).vertices
+        except ImportError:
+            hull_idx = _convex_hull_Graham_scan(points)
+
+    return hull_idx
+
+
+# see also: https://github.com/igraph/igraph/blob/075be76c92b99ca4c95ad9207bcc1af6d471c85e/src/misc/other.c#L116
+# Compared to that C implementation, this is a bit more vectorised and messes less with memory as usual when
+# optimising Python/numpy code
+def _convex_hull_Graham_scan(points):
+    """Compute the indices for the convex hull of a set of 2D points using Graham's scan algorithm."""
+    if len(points) < 4:
+        # NOTE: for an exact triangle, this does not guarantee chirality. Should be ok anyway
+        return np.arange(len(points))
+
+    points = np.asarray(points)
+
+    # Find pivot (bottom left corner)
+    miny_idx = np.flatnonzero(points[:, 1] == points[:, 1].min())
+    pivot_idx = miny_idx[points[miny_idx, 0].argmin()]
+
+    # Compute angles against that pivot, ensuring the pivot itself last
+    angles = np.arctan2(
+        points[:, 1] - points[pivot_idx, 1], points[:, 0] - points[pivot_idx, 0]
+    )
+    angles[pivot_idx] = np.inf
+
+    # Sort points by angle
+    order = np.argsort(angles)
+
+    # Whenever two points have the same angle, keep the furthest one from the pivot
+    # whenever an index is discarded from "order", set it to -1
+    j = 0
+    last_idx = order[0]
+    pivot_idx = order[-1]
+    for i in range(1, len(order)):
+        next_idx = order[i]
+        if angles[last_idx] == angles[next_idx]:
+            dlast = np.linalg.norm(points[last_idx] - points[pivot_idx])
+            dnext = np.linalg.norm(points[next_idx] - points[pivot_idx])
+            # Ignore the new point, it's inside
+            if dlast > dnext:
+                order[i] = -1
+            # Ignore the old point, it's inside
+            # The new one has a chance (depending on who comes next)
+            else:
+                order[j] = -1
+                last_idx = next_idx
+                j = i
+        # New angle found: this point automatically gets a chance
+        # (depending on who comes next). This also means that the
+        # last point (last_idx before reassignment) will make it into
+        # the hull
+        else:
+            last_idx = next_idx
+            j += 1
+
+    # Construct the hull from all indices that are not -1
+    order = order[order != -1]
+    jorder = len(order) - 1
+    stack = []
+    j = 0
+    last_idx = -1
+    before_last_idx = -1
+    while jorder > -1:
+        next_idx = order[jorder]
+
+        # If doing a correct turn (right), add the point to the hull
+        # if doing a wrong turn (left), backtrack and skip
+
+        # At the beginning, assume it's a good turn to start collecting points
+        if j < 2:
+            cp = -1
+        else:
+            cp = (points[last_idx, 0] - points[before_last_idx, 0]) * (
+                points[next_idx, 1] - points[before_last_idx, 1]
+            ) - (points[next_idx, 0] - points[before_last_idx, 0]) * (
+                points[last_idx, 1] - points[before_last_idx, 1]
+            )
+
+        # turning correctly or accumulating: add to the stack
+        if cp < 0:
+            jorder -= 1
+            stack.append(next_idx)
+            j += 1
+            before_last_idx = last_idx
+            last_idx = next_idx
+
+            # wrong turn: backtrack, excise wrong point and move to next vertex
+        else:
+            del stack[-1]
+            j -= 1
+            last_idx = before_last_idx
+            before_last_idx = stack[j - 2] if j >= 2 else -1
+
+    stack = np.asarray(stack)
+
+    return stack
+
+
+def _compute_group_path_with_vertex_padding(
+    points,
+    transform,
+    vertexpadding=10,
+):
+    """Offset path for a group based on vertex padding.
+
+    At the input, the structure is [v1, v1, v1, ..., vn, vn, vn, v1]
+
+    # NOTE: this would look better as a cubic Bezier, but ok for now.
+    """
+
+    # Transform into figure coordinates
+    trans = transform.transform
+    trans_inv = transform.inverted().transform
+    points = trans(points)
+
+    # Find the vertex centers, to recompute the offsets from scratch
+    # Independent whether this is a first call or a later draw,
+    # finding the vertex center can be done at once
+    # 0.         .->.vcenter
+    #  |         |  ^
+    #  |         |  |
+    # 1.--.2     .--.
+    # singleton group
+    s2 = 0.96
+    if len(points) == 9:
+        points[:] = 0.5 * (points[0] + points[4])
+        points[0] += np.array([0, -1]) * vertexpadding
+        points[1] += np.array([-s2, -s2]) * vertexpadding
+        points[2] += np.array([-1, 0]) * vertexpadding
+        points[3] += np.array([-s2, s2]) * vertexpadding
+        points[4] += np.array([0, 1]) * vertexpadding
+        points[5] += np.array([s2, s2]) * vertexpadding
+        points[6] += np.array([1, 0]) * vertexpadding
+        points[7] += np.array([s2, -s2]) * vertexpadding
+        points[8] += np.array([0, -1]) * vertexpadding
+    else:
+        # doublet group are a bit different from triangles+
+        if len(points) == 11:
+            # points per vertex
+            ppv = 5
+            points[:-1:ppv] = 0.5 * (points[:-1:ppv] + points[ppv - 1 : -1 : ppv])
+        else:
+            ppv = 3
+            points[:-1:ppv] = (
+                points[:-1:ppv] + points[ppv - 1 : -1 : ppv] - points[1:-1:ppv]
+            )
+        for j in range(1, ppv):
+            points[j:-1:ppv] = points[:-1:ppv]
+        points[-1] = points[0]
+
+        # Compute all shift vectors by diff, arctan2, then add 90 degrees, tan, norm
+        # This maintains chirality
+        # NOTE: the last point is just going back to the beginning, this
+        # is a quirk or how mpl's closed paths work
+
+        # Normalised diff
+        vpoints = points[:-1:ppv].copy()
+        vpoints[0] -= points[-2]
+        vpoints[1:] -= points[:-1:ppv][:-1]
+        vpoints = (vpoints.T / np.sqrt((vpoints**2).sum(axis=1))).T
+
+        # Rotate by 90 degrees
+        vpads = vpoints @ np.array([[0, 1], [-1, 0]])
+
+        # Permute diff for the end
+        vpads_perm = np.zeros_like(vpads)
+        vpads_perm[:-1] = vpads[1:]
+        vpads_perm[-1] = vpads[0]
+
+        # Shift the points
+        if ppv == 3:
+            points[:-1:ppv] += vpads * vertexpadding
+            points[1:-1:ppv] += (vpads + vpads_perm) * vertexpadding
+            points[2:-1:ppv] += vpads_perm * vertexpadding
+        else:
+            points[:-1:ppv] += vpads * vertexpadding
+            points[1:-1:ppv] += (vpads + vpoints) * vertexpadding
+            points[2:-1:ppv] += vpoints * vertexpadding
+            points[3:-1:ppv] += (vpads_perm + vpoints) * vertexpadding
+            points[4:-1:ppv] += vpads_perm * vertexpadding
+
+    # mpl's quirky closed-path thing
+    points[-1] = points[0]
+
+    # Transform back to data coordinates
+    points = trans_inv(points)
+
+    return points

iplotx/utils/matplotlib.py

@@ -0,0 +1,136 @@
+from functools import wraps, partial
+from math import atan2
+import matplotlib as mpl
+
+from .geometry import (
+    _evaluate_squared_bezier,
+    _evaluate_cubic_bezier,
+)
+
+
+# NOTE: https://github.com/networkx/grave/blob/main/grave/grave.py
+def _stale_wrapper(func):
+    """Decorator to manage artist state."""
+
+    @wraps(func)
+    def inner(self, *args, **kwargs):
+        try:
+            func(self, *args, **kwargs)
+        finally:
+            self.stale = False
+
+    return inner
+
+
+def _forwarder(forwards, cls=None):
+    """Decorator to forward specific methods to Artist children."""
+    if cls is None:
+        return partial(_forwarder, forwards)
+
+    def make_forward(name):
+        def method(self, *args, **kwargs):
+            ret = getattr(cls.mro()[1], name)(self, *args, **kwargs)
+            for c in self.get_children():
+                getattr(c, name)(*args, **kwargs)
+            return ret
+
+        return method
+
+    for f in forwards:
+        method = make_forward(f)
+        method.__name__ = f
+        method.__doc__ = "broadcasts {} to children".format(f)
+        setattr(cls, f, method)
+
+    return cls
+
+
+def _additional_set_methods(attributes, cls=None):
+    """Decorator to add specific set methods for children properties."""
+    if cls is None:
+        return partial(_additional_set_methods, attributes)
+
+    def make_setter(name):
+        def method(self, value):
+            self.set(**{name: value})
+
+        return method
+
+    for attr in attributes:
+        desc = attr.replace("_", " ")
+        method = make_setter(attr)
+        method.__name__ = f"set_{attr}"
+        method.__doc__ = f"Set {desc}."
+        setattr(cls, f"set_{attr}", method)
+
+    return cls
+
+
+# FIXME: this method appears quite inconsistent, would be better to improve.
+# The issue is that to really know the size of a label on screen, we need to
+# render it first. Therefore, we should render the labels, then render the
+# vertices. Leaving for now, since this can be styled manually which covers
+# 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"]
+    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
+    return (width, height)
+
+
+def _compute_mid_coord(path):
+    """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)
+
+    # Cubic Bezier
+    if path.codes[-1] == mpl.path.Path.CURVE4:
+        return _evaluate_cubic_bezier(path.vertices, 0.5)
+
+    # 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."
+    )
+
+
+def _compute_group_path_with_vertex_padding(
+    points,
+    transform,
+    vertexpadding=10,
+):
+    """Offset path for a group based on vertex padding.
+
+    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)
+
+    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])
+
+        mprev_orth = -1 / mprev
+        points[i * 3] = vcur + vertexpadding * mprev_orth
+
+        vprev = vcur
+        mprev = mnext
+
+    points = trans_inv(points)
+    return points

iplotx/version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

iplotx/vertex.py

@@ -0,0 +1,112 @@
+import numpy as np
+from matplotlib.transforms import IdentityTransform
+from matplotlib.collections import PatchCollection
+from matplotlib.patches import (
+    Ellipse,
+    Circle,
+    RegularPolygon,
+    Rectangle,
+)
+
+
+class VertexCollection(PatchCollection):
+    """Collection of vertex patches for plotting.
+
+    This class takes additional keyword arguments compared to PatchCollection:
+
+    @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, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def get_sizes(self):
+        """Same as get_size."""
+        return self.get_size()
+
+    def get_size(self):
+        """Get vertex sizes.
+
+        If width and height are unequal, get the largest of the two.
+
+        @return: An array of vertex sizes.
+        """
+        import numpy as np
+
+        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_size(self, sizes):
+        """Set vertex sizes.
+
+        This rescales the current vertex symbol/path linearly, using this
+        value as the largest of width and height.
+
+        @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
+
+        self.stale = True
+
+    def set_sizes(self, sizes):
+        """Same as set_size."""
+        self.set_size(sizes)
+
+    @property
+    def stale(self):
+        return super().stale
+
+    @stale.setter
+    def stale(self, val):
+        PatchCollection.stale.fset(self, val)
+        if val and hasattr(self, "stale_callback_post"):
+            self.stale_callback_post(self)
+
+
+def make_patch(marker: str, size, **kwargs):
+    """Make a patch of the given marker shape and size."""
+    forbidden_props = ["label"]
+    for prop in forbidden_props:
+        if prop in kwargs:
+            kwargs.pop(prop)
+
+    if isinstance(size, (int, float)):
+        size = (size, size)
+
+    if marker in ("o", "circle"):
+        return 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)
+    elif marker in ("^", "triangle"):
+        return RegularPolygon((0, 0), numVertices=3, radius=size[0] / 2, **kwargs)
+    elif marker in ("d", "diamond"):
+        return make_patch("s", size[0], angle=45, **kwargs)
+    elif marker in ("v", "triangle_down"):
+        return 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}")