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

iplotx/edge/arrow.py

@@ -1,6 +1,7 @@
-from typing import (
-    Never,
-)
+"""
+Module for edge arrows in iplotx.
+"""
+
 import numpy as np
 import matplotlib as mpl
 from matplotlib.patches import PathPatch
@@ -19,10 +20,17 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
     def __init__(
         self,
         edge_collection,
-        transform: mpl.transforms.Transform = mpl.transforms.IdentityTransform(),
         *args,
+        transform: mpl.transforms.Transform = mpl.transforms.IdentityTransform(),
         **kwargs,
-    ):
+    ) -> None:
+        """Initialize the edge arrow collection.
+
+        Parameters:
+            edge_collection: The edge collection to which these arrows belong.
+            transform: The transform to apply to the arrows. This related to the arrow size
+                scaling, not the arrow tip position which is controlled by set_offset_transform.
+        """
 
         self._edge_collection = edge_collection
         self._style = get_style(".edge.arrow")
@@ -48,10 +56,11 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
         self.set_sizes(sizes)
 
     def get_sizes(self):
-        """Get vertex sizes (max of width and height), not scaled by dpi."""
+        """Get arrow sizes (max of width and height), not scaled by dpi."""
         return self._sizes
 
     def get_sizes_dpi(self):
+        """Get arrow sizes (max of width and height) scaled by dpi."""
         return self._transforms[:, 0, 0]
 
     def set_sizes(self, sizes, dpi=72.0):
@@ -77,7 +86,7 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
     get_size = get_sizes
     set_size = set_sizes
 
-    def set_figure(self, fig) -> Never:
+    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)
@@ -85,6 +94,7 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
             child.set_figure(fig)
 
     def get_offset_transform(self):
+        """Get offset transform for the edge arrows. This sets the tip of each arrow."""
         return self._edge_collection.get_transform()
 
     get_size = get_sizes
@@ -95,7 +105,7 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
 
         patches = []
         sizes = []
-        for i, (vid1, vid2) in enumerate(self._edge_collection._vertex_ids):
+        for i in range(len(self._edge_collection._vertex_ids)):
             stylei = rotate_style(style, index=i)
             if ("facecolor" not in stylei) and ("color" not in stylei):
                 stylei["facecolor"] = self._edge_collection.get_edgecolors()[i][:3]
@@ -114,7 +124,7 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
 
         return patches, sizes
 
-    def set_array(self, array):
+    def set_array(self, A):
         """Set the array for cmap/norm coloring, but keep the facecolors as set (usually 'none')."""
         raise ValueError("Setting an array for arrows directly is not supported.")
 
@@ -122,20 +132,10 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
         """Set arrow colors (edge and/or face) based on a colormap."""
         # NOTE: facecolors is always an array because we come from patches
         # It can have zero alpha (i.e. if we choose "none", or a hollow marker)
-        self.set_edgecolors(colors)
+        self.set_edgecolor(colors)
         has_facecolor = self._facecolors[:, 3] > 0
         self._facecolors[has_facecolor] = colors[has_facecolor]
 
-    @property
-    def stale(self):
-        return super().stale
-
-    @stale.setter
-    def stale(self, val):
-        mpl.collections.PatchCollection.stale.fset(self, val)
-        if val and hasattr(self, "stale_callback_post"):
-            self.stale_callback_post(self)
-
     @mpl.artist.allow_rasterization
     def draw(self, renderer):
         self.set_sizes(self._sizes, self.get_figure(root=True).dpi)

iplotx/edge/geometry.py

@@ -0,0 +1,392 @@
+"""
+Support module with geometry- and path-related functions for edges.
+"""
+
+from typing import Optional
+from math import atan2, tan, pi
+import numpy as np
+import matplotlib as mpl
+
+from ..typing import (
+    Pair,
+)
+from .ports import _get_port_unit_vector
+
+
+def _compute_loops_per_angle(nloops, angles):
+    if len(angles) == 0:
+        return [(0, 2 * pi, nloops)]
+
+    angles_sorted_closed = list(sorted(angles))
+    angles_sorted_closed.append(angles_sorted_closed[0] + 2 * pi)
+    deltas = np.diff(angles_sorted_closed)
+
+    # Now we have the deltas and the total number of loops
+    # 1. Assign all loops to the largest wedge
+    idx_dmax = deltas.argmax()
+    if nloops == 1:
+        return [
+            (
+                angles_sorted_closed[idx_dmax],
+                angles_sorted_closed[idx_dmax + 1],
+                nloops,
+            )
+        ]
+
+    # 2. Check if any other wedges are larger than this
+    # If not, we are done (this is the algo in igraph)
+    dsplit = deltas[idx_dmax] / nloops
+    if (deltas > dsplit).sum() < 2:
+        return [
+            (
+                angles_sorted_closed[idx_dmax],
+                angles_sorted_closed[idx_dmax + 1],
+                nloops,
+            )
+        ]
+
+        # 3. Check how small the second-largest wedge would become
+    idx_dsort = np.argsort(deltas)
+    return [
+        (
+            angles_sorted_closed[idx_dmax],
+            angles_sorted_closed[idx_dmax + 1],
+            nloops - 1,
+        ),
+        (
+            angles_sorted_closed[idx_dsort[-2]],
+            angles_sorted_closed[idx_dsort[-2] + 1],
+            1,
+        ),
+    ]
+
+
+def _get_shorter_edge_coords(vpath, vsize, theta):
+    # Bound theta from -pi to pi (why is that not guaranteed?)
+    theta = (theta + pi) % (2 * pi) - pi
+
+    # Size zero vertices need no shortening
+    if vsize == 0:
+        return np.array([0, 0])
+
+    for i in range(len(vpath)):
+        v1 = vpath.vertices[i]
+        v2 = vpath.vertices[(i + 1) % len(vpath)]
+        theta1 = atan2(*((v1)[::-1]))
+        theta2 = atan2(*((v2)[::-1]))
+
+        # atan2 ranges ]-3.14, 3.14]
+        # so it can be that theta1 is -3 and theta2 is +3
+        # therefore we need two separate cases, one that cuts at pi and one at 0
+        cond1 = theta1 <= theta <= theta2
+        cond2 = (
+            (theta1 + 2 * pi) % (2 * pi)
+            <= (theta + 2 * pi) % (2 * pi)
+            <= (theta2 + 2 * pi) % (2 * pi)
+        )
+        if cond1 or cond2:
+            break
+    else:
+        raise ValueError("Angle for patch not found")
+
+    # The edge meets the patch of the vertex on the v1-v2 size,
+    # at angle theta from the center
+    mtheta = tan(theta)
+    if v2[0] == v1[0]:
+        xe = v1[0]
+    else:
+        m12 = (v2[1] - v1[1]) / (v2[0] - v1[0])
+        xe = (v1[1] - m12 * v1[0]) / (mtheta - m12)
+    ye = mtheta * xe
+    ve = np.array([xe, ye])
+    return ve * vsize
+
+
+def _fix_parallel_edges_straight(
+    paths,
+    indices,
+    indices_inv,
+    trans,
+    trans_inv,
+    offset=3,
+):
+    """Offset parallel edges along the same path."""
+    ntot = len(indices) + len(indices_inv)
+
+    # This is straight so two vertices anyway
+    # NOTE: all paths will be the same, which is why we need to offset them
+    vs, ve = trans(paths[indices[0]].vertices)
+
+    # Move orthogonal to the line
+    fracs = (vs - ve) / np.sqrt(((vs - ve) ** 2).sum()) @ np.array([[0, 1], [-1, 0]])
+
+    # NOTE: for now treat both direction the same
+    for i, idx in enumerate(indices + indices_inv):
+        # Offset the path
+        paths[idx].vertices = trans_inv(
+            trans(paths[idx].vertices) + fracs * offset * (i - ntot / 2)
+        )
+
+
+def _compute_loop_path(
+    vcoord_fig,
+    vpath,
+    vsize,
+    angle1,
+    angle2,
+    trans_inv,
+    looptension,
+):
+    # Shorten at starting angle
+    start = _get_shorter_edge_coords(vpath, vsize, angle1) + vcoord_fig
+    # Shorten at end angle
+    end = _get_shorter_edge_coords(vpath, vsize, angle2) + vcoord_fig
+
+    aux1 = (start - vcoord_fig) * looptension + vcoord_fig
+    aux2 = (end - vcoord_fig) * looptension + vcoord_fig
+
+    vertices = np.vstack(
+        [
+            start,
+            aux1,
+            aux2,
+            end,
+        ]
+    )
+    codes = ["MOVETO"] + ["CURVE4"] * 3
+
+    # Offset to place and transform to data coordinates
+    vertices = trans_inv(vertices)
+    codes = [getattr(mpl.path.Path, x) for x in codes]
+    path = mpl.path.Path(
+        vertices,
+        codes=codes,
+    )
+    return path
+
+
+def _compute_edge_path_straight(
+    vcoord_data,
+    vpath_fig,
+    vsize_fig,
+    trans,
+    trans_inv,
+    **kwargs,
+):
+
+    # Coordinates in figure (default) coords
+    vcoord_fig = trans(vcoord_data)
+
+    points = []
+
+    # Angle of the straight line
+    theta = atan2(*((vcoord_fig[1] - vcoord_fig[0])[::-1]))
+
+    # Shorten at starting vertex
+    vs = _get_shorter_edge_coords(vpath_fig[0], vsize_fig[0], theta) + vcoord_fig[0]
+    points.append(vs)
+
+    # Shorten at end vertex
+    ve = (
+        _get_shorter_edge_coords(vpath_fig[1], vsize_fig[1], theta + pi) + vcoord_fig[1]
+    )
+    points.append(ve)
+
+    codes = ["MOVETO", "LINETO"]
+    path = mpl.path.Path(
+        points,
+        codes=[getattr(mpl.path.Path, x) for x in codes],
+    )
+    path.vertices = trans_inv(path.vertices)
+    return path, (theta, theta + np.pi)
+
+
+def _compute_edge_path_waypoints(
+    waypoints,
+    vcoord_data,
+    vpath_fig,
+    vsize_fig,
+    trans,
+    trans_inv,
+    layout_coordinate_system: str = "cartesian",
+    points_per_curve: int = 30,
+    **kwargs,
+):
+
+    if waypoints in ("x0y1", "y0x1"):
+        assert layout_coordinate_system == "cartesian"
+
+        # Coordinates in figure (default) coords
+        vcoord_fig = trans(vcoord_data)
+
+        if waypoints == "x0y1":
+            waypoint = np.array([vcoord_fig[0][0], vcoord_fig[1][1]])
+        else:
+            waypoint = np.array([vcoord_fig[1][0], vcoord_fig[0][1]])
+
+        # Angles of the straight lines
+        theta0 = atan2(*((waypoint - vcoord_fig[0])[::-1]))
+        theta1 = atan2(*((waypoint - vcoord_fig[1])[::-1]))
+
+        # Shorten at starting vertex
+        vs = (
+            _get_shorter_edge_coords(vpath_fig[0], vsize_fig[0], theta0) + vcoord_fig[0]
+        )
+
+        # Shorten at end vertex
+        ve = (
+            _get_shorter_edge_coords(vpath_fig[1], vsize_fig[1], theta1) + vcoord_fig[1]
+        )
+
+        points = [vs, waypoint, ve]
+        codes = ["MOVETO", "LINETO", "LINETO"]
+        angles = (theta0, theta1)
+    elif waypoints == "r0a1":
+        assert layout_coordinate_system == "polar"
+
+        r0, alpha0 = vcoord_data[0]
+        r1, alpha1 = vcoord_data[1]
+        idx_inner = np.argmin([r0, r1])
+        idx_outer = 1 - idx_inner
+        alpha_outer = [alpha0, alpha1][idx_outer]
+
+        # FIXME: this is aware of chirality as stored by the layout function
+        betas = np.linspace(alpha0, alpha1, points_per_curve)
+        waypoints = [r0, r1][idx_inner] * np.vstack([np.cos(betas), np.sin(betas)]).T
+        endpoint = [r0, r1][idx_outer] * np.array(
+            [np.cos(alpha_outer), np.sin(alpha_outer)]
+        )
+        points = np.array(list(waypoints) + [endpoint])
+        points = trans(points)
+        codes = ["MOVETO"] + ["LINETO"] * len(waypoints)
+        # FIXME: same as previus comment
+        angles = (alpha0 + pi / 2, alpha1)
+
+    else:
+        raise NotImplementedError(
+            f"Edge shortening with waypoints not implemented yet: {waypoints}.",
+        )
+
+    path = mpl.path.Path(
+        points,
+        codes=[getattr(mpl.path.Path, x) for x in codes],
+    )
+
+    path.vertices = trans_inv(path.vertices)
+    return path, angles
+
+
+def _compute_edge_path_curved(
+    tension,
+    vcoord_data,
+    vpath_fig,
+    vsize_fig,
+    trans,
+    trans_inv,
+    ports=(None, None),
+):
+    """Shorten the edge path along a cubic Bezier between the vertex centres.
+
+    The most important part is that the derivative of the Bezier at the start
+    and end point towards the vertex centres: people notice if they do not.
+    """
+
+    # Coordinates in figure (default) coords
+    vcoord_fig = trans(vcoord_data)
+
+    dv = vcoord_fig[1] - vcoord_fig[0]
+    edge_straight_length = np.sqrt((dv**2).sum())
+
+    auxs = [None, None]
+    for i in range(2):
+        if ports[i] is not None:
+            der = _get_port_unit_vector(ports[i], trans_inv)
+            auxs[i] = der * edge_straight_length * tension + vcoord_fig[i]
+
+    # Both ports defined, just use them and hope for the best
+    # Obviously, if the user specifies ports that make no sense,
+    # this is going to be a (technically valid) mess.
+    if all(aux is not None for aux in auxs):
+        pass
+
+    # If no ports are specified (the most common case), compute
+    # the Bezier and shorten it
+    elif all(aux is None for aux in auxs):
+        # Put auxs along the way
+        auxs = np.array(
+            [
+                vcoord_fig[0] + 0.33 * dv,
+                vcoord_fig[1] - 0.33 * dv,
+            ]
+        )
+        # Right rotation from the straight edge
+        dv_rot = -0.1 * dv @ np.array([[0, 1], [-1, 0]])
+        # Shift the auxs orthogonal to the straight edge
+        auxs += dv_rot * tension
+
+    # First port is defined
+    elif (auxs[0] is not None) and (auxs[1] is None):
+        auxs[1] = auxs[0]
+
+    # Second port is defined
+    else:
+        auxs[0] = auxs[1]
+
+    vs = [None, None]
+    thetas = [None, None]
+    for i in range(2):
+        thetas[i] = atan2(*((auxs[i] - vcoord_fig[i])[::-1]))
+        vs[i] = (
+            _get_shorter_edge_coords(vpath_fig[i], vsize_fig[i], thetas[i])
+            + vcoord_fig[i]
+        )
+
+    path = {
+        "vertices": [
+            vs[0],
+            auxs[0],
+            auxs[1],
+            vs[1],
+        ],
+        "codes": ["MOVETO"] + ["CURVE4"] * 3,
+    }
+
+    path = mpl.path.Path(
+        path["vertices"],
+        codes=[getattr(mpl.path.Path, x) for x in path["codes"]],
+    )
+
+    # Return to data transform
+    path.vertices = trans_inv(path.vertices)
+    return path, tuple(thetas)
+
+
+def _compute_edge_path(
+    *args,
+    tension: float = 0,
+    waypoints: str = "none",
+    ports: Pair[Optional[str]] = (None, None),
+    layout_coordinate_system: str = "cartesian",
+    **kwargs,
+):
+    """Compute the edge path in a few different ways."""
+    if (waypoints != "none") and (tension != 0):
+        raise ValueError("Waypoints not supported for curved edges.")
+
+    if waypoints != "none":
+        return _compute_edge_path_waypoints(
+            waypoints,
+            *args,
+            layout_coordinate_system=layout_coordinate_system,
+            **kwargs,
+        )
+
+    if tension == 0:
+        return _compute_edge_path_straight(*args, **kwargs)
+
+    return _compute_edge_path_curved(
+        tension,
+        *args,
+        ports=ports,
+        **kwargs,
+    )

iplotx/edge/ports.py

@@ -1,3 +1,7 @@
+"""
+Module for handling edge ports in iplotx.
+"""
+
 import numpy as np
 
 sq2 = np.sqrt(2) / 2
@@ -19,8 +23,9 @@ def _get_port_unit_vector(
     trans_inv,
 ):
     """Get the tangent unit vector from a port string."""
-    # The only tricky bit is if the port says e.g. north but the y axis is inverted, in which case the port should go south.
-    # We can figure it out by checking the sign of the monotonic trans_inv from figure to data coordinates.
+    # The only tricky bit is if the port says e.g. north but the y axis is inverted, in which
+    # case the port should go south. We can figure it out by checking the sign of the monotonic
+    # trans_inv from figure to data coordinates.
     v12 = trans_inv(
         np.array(
             [

iplotx/groups.py

@@ -40,7 +40,7 @@ class GroupingArtist(PatchCollection):
         transform: mpl.transforms.Transform = mpl.transforms.IdentityTransform(),
         *args,
         **kwargs,
-    ):
+    ) -> None:
         """Container artist for vertex groupings, e.g. covers or clusterings.
 
         Parameters:
@@ -65,7 +65,10 @@ class GroupingArtist(PatchCollection):
 
         network = kwargs.pop("network", None)
         patches, grouping, coords_hulls = self._create_patches(
-            grouping, layout, network, **kwargs
+            grouping,
+            layout,
+            network,
+            **kwargs,
         )
         if "network" in kwargs:
             del kwargs["network"]
@@ -80,17 +83,17 @@ class GroupingArtist(PatchCollection):
 
         self.set_transform(transform)
 
-    def set_figure(self, figure):
+    def set_figure(self, figure) -> None:
         """Set the figure for the grouping, recomputing the paths depending on the figure's dpi."""
         ret = super().set_figure(figure)
         self._compute_paths(self.get_figure(root=True).dpi)
         return ret
 
-    def get_vertexpadding(self):
+    def get_vertexpadding(self) -> float:
         """Get the vertex padding of each group."""
         return self._vertexpadding
 
-    def get_vertexpadding_dpi(self, dpi=72.0):
+    def get_vertexpadding_dpi(self, dpi: float = 72.0) -> float:
         """Get vertex padding of each group, scaled by dpi of the figure."""
         return self.get_vertexpadding() * dpi / 72.0 * self._factor
 
@@ -126,7 +129,7 @@ class GroupingArtist(PatchCollection):
             patches.append(patch)
         return patches, grouping, coords_hulls
 
-    def _compute_paths(self, dpi=72.0):
+    def _compute_paths(self, dpi: float = 72.0) -> None:
         ppc = self._points_per_curve
         for i, hull in enumerate(self._coords_hulls):
             self._paths[i].vertices = _compute_group_path_with_vertex_padding(
@@ -137,16 +140,23 @@ class GroupingArtist(PatchCollection):
                 points_per_curve=ppc,
             )
 
-    def _process(self):
+    def _process(self) -> None:
         self._compute_paths()
 
-    def draw(self, renderer):
-        # FIXME: this kind of breaks everything since the vertices' magical "_transforms" does not really
-        # scale from 72 pixels but rather from the screen's or something. Conclusion: using this keeps
-        # consistency across dpis but breaks proportionality of vertexpadding and vertex_size (for now).
-        # NOTE: this might be less bad than initially thought in the sense that even perfect scaling
-        # does not seem to align the center of the perimeter of the group with the center of the perimeter
-        # of the vertex when of the same exact size. So we are probably ok winging it as users will adapt.
+    def draw(self, renderer) -> None:
+        """Draw or re-draw the grouping patches.
+
+        Parameters:
+            renderer: The renderer to use for drawing the patches.
+        """
+        # FIXME: this kind of breaks everything since the vertices' magical "_transforms" does
+        # not really scale from 72 pixels but rather from the screen's or something.
+        # Conclusion: using this keeps consistency across dpis but breaks proportionality of
+        # vertexpadding and vertex_size (for now).
+        # NOTE: this might be less bad than initially thought in the sense that even perfect
+        # scaling does not seem to align the center of the perimeter of the group with the
+        # center of the perimeter of the vertex when of the same exact size. So we are
+        # probably ok winging it as users will adapt.
         self._compute_paths(self.get_figure(root=True).dpi)
         super().draw(renderer)