iplotx 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

iplotx/__init__.py

@@ -11,6 +11,9 @@ from .plotting import (
     network,
     tree,
 )
+import iplotx.artists as artists
+import iplotx.style as style
+
 
 # Shortcut to iplotx.plotting.network
 plot = network
@@ -19,5 +22,7 @@ __all__ = [
     "network",
     "tree",
     "plot",
+    "artists",
+    "style",
     "__version__",
 ]

iplotx/artists.py

@@ -0,0 +1,24 @@
+"""
+All artists defined in iplotx.
+"""
+
+from .network import NetworkArtist
+from .tree import TreeArtist
+from .vertex import VertexCollection
+from .edge import EdgeCollection
+from .label import LabelCollection
+from .edge.arrow import EdgeArrowCollection
+from .edge.leaf import LeafEdgeCollection
+from .cascades import CascadeCollection
+
+
+___all__ = (
+    NetworkArtist,
+    TreeArtist,
+    VertexCollection,
+    EdgeCollection,
+    LeafEdgeCollection,
+    LabelCollection,
+    EdgeArrowCollection,
+    CascadeCollection,
+)

iplotx/cascades.py

@@ -208,15 +208,15 @@ class CascadeCollection(mpl.collections.PatchCollection):
         if (layout_name, orientation) == ("horizontal", "right"):
             for path in self.get_paths():
                 path.vertices[[1, 2], 0] = self.get_maxdepth()
-        elif (layout_name, orientation) == ("horizontal", "right"):
+        elif (layout_name, orientation) == ("horizontal", "left"):
             for path in self.get_paths():
                 path.vertices[[0, 3], 0] = self.get_maxdepth()
         elif (layout_name, orientation) == ("vertical", "descending"):
             for path in self.get_paths():
-                path.vertices[[1, 2], 1] = self.get_maxdepth()
+                path.vertices[[0, 1], 1] = self.get_maxdepth()
         elif (layout_name, orientation) == ("vertical", "ascending"):
             for path in self.get_paths():
-                path.vertices[[0, 3], 1] = self.get_maxdepth()
+                path.vertices[[2, 3], 1] = self.get_maxdepth()
         else:
             raise ValueError(
                 f"Layout name and orientation not supported: {layout_name}, {orientation}."

iplotx/edge/__init__.py

@@ -262,11 +262,13 @@ class EdgeCollection(mpl.collections.PatchCollection):
         trans_inv = transform.inverted().transform
 
         # 1. Make a list of vertices with loops, and store them for later
-        loop_vertex_dict = defaultdict(lambda: dict(indices=[], edge_angles=[]))
-        for i, (v1, v2) in enumerate(vids):
-            # Postpone loops (step 3)
-            if v1 == v2:
-                loop_vertex_dict[v1]["indices"].append(i)
+        # NOTE: vinfo["loops"] can be False when we want no loops (e.g. leaf edges)
+        if vinfo.get("loops", True):
+            loop_vertex_dict = defaultdict(lambda: dict(indices=[], edge_angles=[]))
+            for i, (v1, v2) in enumerate(vids):
+                # Postpone loops (step 3)
+                if v1 == v2:
+                    loop_vertex_dict[v1]["indices"].append(i)
 
         # 2. Make paths for non-loop edges
         # NOTE: keep track of parallel edges to offset them
@@ -274,7 +276,7 @@ class EdgeCollection(mpl.collections.PatchCollection):
         paths = []
         for i, (v1, v2) in enumerate(vids):
             # Postpone loops (step 3)
-            if v1 == v2:
+            if vinfo.get("loops", True) and (v1 == v2):
                 paths.append(None)
                 continue
 
@@ -330,10 +332,11 @@ class EdgeCollection(mpl.collections.PatchCollection):
                 path.vertices[:] = trans_inv(trans(path.vertices) + offset)
 
             # Collect angles for this vertex, to be used for loops plotting below
-            if v1 in loop_vertex_dict:
-                loop_vertex_dict[v1]["edge_angles"].append(angles[0])
-            if v2 in loop_vertex_dict:
-                loop_vertex_dict[v2]["edge_angles"].append(angles[1])
+            if vinfo.get("loops", True):
+                if v1 in loop_vertex_dict:
+                    loop_vertex_dict[v1]["edge_angles"].append(angles[0])
+                if v2 in loop_vertex_dict:
+                    loop_vertex_dict[v2]["edge_angles"].append(angles[1])
 
             # Add the path for this non-loop edge
             paths.append(path)
@@ -360,39 +363,40 @@ class EdgeCollection(mpl.collections.PatchCollection):
                     )
 
         # 3. Deal with loops at the end
-        for vid, ldict in loop_vertex_dict.items():
-            vpath = vpaths[ldict["indices"][0]][0]
-            vsize = vsizes[ldict["indices"][0]][0]
-            vcoord_fig = trans(vcenters[ldict["indices"][0]][0])
-            nloops = len(ldict["indices"])
-            edge_angles = ldict["edge_angles"]
-
-            # The space between the existing angles is where we can fit the loops
-            # One loop we can fit in the largest wedge, multiple loops we need
-            nloops_per_angle = _compute_loops_per_angle(nloops, edge_angles)
-
-            idx = 0
-            for theta1, theta2, nloops in nloops_per_angle:
-                # Angular size of each loop in this wedge
-                delta = (theta2 - theta1) / nloops
-
-                # Iterate over individual loops
-                for j in range(nloops):
-                    thetaj1 = theta1 + j * delta + max(delta - loopmaxangle, 0) / 2
-                    thetaj2 = thetaj1 + min(delta, loopmaxangle)
-
-                    # Get the path for this loop
-                    path = _compute_loop_path(
-                        vcoord_fig,
-                        vpath,
-                        vsize,
-                        thetaj1,
-                        thetaj2,
-                        trans_inv,
-                        looptension=self._style.get("looptension", 2.5),
-                    )
-                    paths[ldict["indices"][idx]] = path
-                    idx += 1
+        if vinfo.get("loops", True):
+            for vid, ldict in loop_vertex_dict.items():
+                vpath = vpaths[ldict["indices"][0]][0]
+                vsize = vsizes[ldict["indices"][0]][0]
+                vcoord_fig = trans(vcenters[ldict["indices"][0]][0])
+                nloops = len(ldict["indices"])
+                edge_angles = ldict["edge_angles"]
+
+                # The space between the existing angles is where we can fit the loops
+                # One loop we can fit in the largest wedge, multiple loops we need
+                nloops_per_angle = _compute_loops_per_angle(nloops, edge_angles)
+
+                idx = 0
+                for theta1, theta2, nloops in nloops_per_angle:
+                    # Angular size of each loop in this wedge
+                    delta = (theta2 - theta1) / nloops
+
+                    # Iterate over individual loops
+                    for j in range(nloops):
+                        thetaj1 = theta1 + j * delta + max(delta - loopmaxangle, 0) / 2
+                        thetaj2 = thetaj1 + min(delta, loopmaxangle)
+
+                        # Get the path for this loop
+                        path = _compute_loop_path(
+                            vcoord_fig,
+                            vpath,
+                            vsize,
+                            thetaj1,
+                            thetaj2,
+                            trans_inv,
+                            looptension=self._style.get("looptension", 2.5),
+                        )
+                        paths[ldict["indices"][idx]] = path
+                        idx += 1
 
         self._paths = paths
 
@@ -629,6 +633,7 @@ def make_stub_patch(**kwargs):
         "offset",
         "paralleloffset",
         "cmap",
+        "norm",
     ]
     for prop in forbidden_props:
         if prop in kwargs:

iplotx/edge/arrow.py

@@ -145,6 +145,8 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
 def make_arrow_patch(marker: str = "|>", width: float = 8, **kwargs):
     """Make a patch of the given marker shape and size."""
     height = kwargs.pop("height", width * 1.3)
+    if height == "width":
+        height = width
 
     # Normalise by the max size, this is taken care of in _transforms
     # subsequently in a way that is nice to dpi scaling
@@ -169,6 +171,38 @@ def make_arrow_patch(marker: str = "|>", width: float = 8, **kwargs):
             codes=[getattr(mpl.path.Path, x) for x in codes],
             closed=True,
         )
+    elif marker == "|\\":
+        codes = ["MOVETO", "LINETO", "LINETO", "CLOSEPOLY"]
+        if "color" in kwargs:
+            kwargs["facecolor"] = kwargs["edgecolor"] = kwargs.pop("color")
+        path = mpl.path.Path(
+            np.array(
+                [
+                    [-height, width * 0.5],
+                    [-height, 0],
+                    [0, 0],
+                    [-height, width * 0.5],
+                ]
+            ),
+            codes=[getattr(mpl.path.Path, x) for x in codes],
+            closed=True,
+        )
+    elif marker == "|/":
+        codes = ["MOVETO", "LINETO", "LINETO", "CLOSEPOLY"]
+        if "color" in kwargs:
+            kwargs["facecolor"] = kwargs["edgecolor"] = kwargs.pop("color")
+        path = mpl.path.Path(
+            np.array(
+                [
+                    [-height, 0],
+                    [-height, -width * 0.5],
+                    [0, 0],
+                    [-height, 0],
+                ]
+            ),
+            codes=[getattr(mpl.path.Path, x) for x in codes],
+            closed=True,
+        )
     elif marker == ">":
         kwargs["facecolor"] = "none"
         if "color" in kwargs:

iplotx/edge/geometry.py

@@ -171,11 +171,28 @@ def _compute_edge_path_straight(
     vsize_fig,
     trans,
     trans_inv,
+    layout_coordinate_system: str = "cartesian",
     **kwargs,
 ):
+    if layout_coordinate_system not in ("cartesian", "polar"):
+        raise ValueError(
+            f"Layout coordinate system not supported for straight edges: {layout_coordinate_system}.",
+        )
+
+    if layout_coordinate_system == "polar":
+        r0, theta0 = vcoord_data[0]
+        r1, theta1 = vcoord_data[1]
+        vcoord_data_cart = np.array(
+            [
+                [r0 * np.cos(theta0), r0 * np.sin(theta0)],
+                [r1 * np.cos(theta1), r1 * np.sin(theta1)],
+            ]
+        )
+    else:
+        vcoord_data_cart = vcoord_data
 
     # Coordinates in figure (default) coords
-    vcoord_fig = trans(vcoord_data)
+    vcoord_fig = trans(vcoord_data_cart)
 
     points = []
 
@@ -305,7 +322,6 @@ def _compute_edge_path_waypoints(
         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(
@@ -314,7 +330,6 @@ def _compute_edge_path_waypoints(
         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:
@@ -438,7 +453,11 @@ def _compute_edge_path(
         )
 
     if tension == 0:
-        return _compute_edge_path_straight(*args, **kwargs)
+        return _compute_edge_path_straight(
+            *args,
+            layout_coordinate_system=layout_coordinate_system,
+            **kwargs,
+        )
 
     return _compute_edge_path_curved(
         tension,

iplotx/edge/leaf.py

@@ -0,0 +1,117 @@
+"""
+Module containing leaf edges, i.e. special edges of tree visualisations
+that connect leaf vertices to the deepest leaf (typically for labeling).
+"""
+
+from typing import (
+    Sequence,
+    Optional,
+    Any,
+)
+import numpy as np
+import pandas as pd
+import matplotlib as mpl
+
+from ..utils.matplotlib import (
+    _forwarder,
+)
+from ..vertex import VertexCollection
+from iplotx.edge import EdgeCollection
+
+
+@_forwarder(
+    (
+        "set_clip_path",
+        "set_clip_box",
+        "set_snap",
+        "set_sketch_params",
+        "set_animated",
+        "set_picker",
+    )
+)
+class LeafEdgeCollection(EdgeCollection):
+    """Artist for leaf edges in tree visualisations."""
+
+    def __init__(
+        self,
+        patches: Sequence[mpl.patches.Patch],
+        vertex_leaf_ids: Sequence[tuple],
+        vertex_collection: VertexCollection,
+        leaf_collection: VertexCollection,
+        *args,
+        transform: mpl.transforms.Transform = mpl.transforms.IdentityTransform(),
+        arrow_transform: mpl.transforms.Transform = mpl.transforms.IdentityTransform(),
+        directed: bool = False,
+        style: Optional[dict[str, Any]] = None,
+        **kwargs,
+    ) -> None:
+        """Initialise a LeafEdgeCollection.
+
+        Parameters:
+            patches: A sequence (usually, list) of matplotlib `Patch`es describing the edges.
+            vertex_ids: A sequence of pairs `(v1, v2)`, each defining the ids of vertices at the
+                end of an edge.
+            vertex_collection: The VertexCollection instance containing the Artist for the
+                vertices. This is needed to compute vertex borders and adjust edges accordingly.
+            transform: The matplotlib transform for the edges, usually transData.
+            arrow_transform: The matplotlib transform for the arrow patches. This is not the
+                *offset_transform* of arrows, which is set equal to the edge transform (previous
+                parameter). Instead, it specifies how arrow size scales, similar to vertex size.
+                This is usually the identity transform.
+            directed: Whether the graph is directed (in which case arrows are drawn, possibly
+                with zero size or opacity to obtain an "arrowless" effect).
+            style: The edge style (subdictionary: "edge") to use at creation.
+        """
+        self._leaf_collection = leaf_collection
+        super().__init__(
+            patches=patches,
+            vertex_ids=vertex_leaf_ids,
+            vertex_collection=vertex_collection,
+            *args,
+            transform=transform,
+            arrow_transform=arrow_transform,
+            directed=directed,
+            style=style,
+            **kwargs,
+        )
+
+    def _get_adjacent_vertices_info(self):
+        lindex = self._leaf_collection.get_index()
+        lindex = pd.Series(
+            np.arange(len(lindex)),
+            index=lindex,
+        )
+        vindex = self._vertex_collection.get_index()
+        vindex = pd.Series(
+            np.arange(len(vindex)),
+            index=vindex,
+        ).loc[lindex.index]
+
+        voffsets = []
+        vpaths = []
+        vsizes = []
+        for vid in self._vertex_ids:
+            # NOTE: these are in the original layout coordinate system
+            # not cartesianised yet.
+            offset1 = self._vertex_collection.get_layout().values[vindex[vid]]
+            offset2 = self._leaf_collection.get_layout().values[lindex[vid]]
+            voffsets.append((offset1, offset2))
+
+            path1 = self._vertex_collection.get_paths()[vindex[vid]]
+            path2 = self._leaf_collection.get_paths()[lindex[vid]]
+            vpaths.append((path1, path2))
+
+            # NOTE: This needs to be computed here because the
+            # VertexCollection._transforms are reset each draw in order to
+            # accomodate for DPI changes on the canvas
+            size1 = self._vertex_collection.get_sizes_dpi()[vindex[vid]]
+            size2 = self._leaf_collection.get_sizes_dpi()[lindex[vid]]
+            vsizes.append((size1, size2))
+
+        return {
+            "ids": [(vid, vid) for vid in self._vertex_ids],
+            "offsets": voffsets,
+            "paths": vpaths,
+            "sizes": vsizes,
+            "loops": False,
+        }

iplotx/ingest/__init__.py

@@ -95,8 +95,7 @@ def ingest_network_data(
             f"Currently installed supported libraries: {sup}."
         )
 
-    result = provider()(
-        network=network,
+    result = provider(network)(
         layout=layout,
         vertex_labels=vertex_labels,
         edge_labels=edge_labels,
@@ -108,7 +107,6 @@ def ingest_network_data(
 def ingest_tree_data(
     tree: TreeType,
     layout: Optional[str] = "horizontal",
-    orientation: Optional[str] = None,
     directed: bool | str = False,
     layout_style: Optional[dict[str, str | int | float]] = None,
     vertex_labels: Optional[Sequence[str] | dict[Hashable, str] | pd.Series] = None,
@@ -133,7 +131,6 @@ def ingest_tree_data(
         tree=tree,
     )(
         layout=layout,
-        orientation=orientation,
         directed=directed,
         layout_style=layout_style,
         vertex_labels=vertex_labels,
@@ -142,8 +139,6 @@ def ingest_tree_data(
     )
     result["tree_library"] = tl
 
-    # TODO: cascading thing here
-
     return result
 
 

iplotx/ingest/heuristics.py

@@ -13,42 +13,13 @@ import pandas as pd
 
 from ..layout import compute_tree_layout
 from ..typing import (
-    GraphType,
     GroupingType,
     LayoutType,
 )
 
 
-def number_of_vertices(network: GraphType) -> int:
-    """Get the number of vertices in the network."""
-    from . import network_library
-
-    if network_library(network) == "igraph":
-        return network.vcount()
-    if network_library(network) == "networkx":
-        return network.number_of_nodes()
-    raise TypeError("Unsupported graph type. Supported types are igraph and networkx.")
-
-
-def detect_directedness(
-    network: GraphType,
-) -> bool:
-    """Detect if the network is directed or not."""
-    from . import network_library
-
-    nl = network_library(network)
-
-    if nl == "igraph":
-        return network.is_directed()
-    if nl == "networkx":
-        import networkx as nx
-
-        if isinstance(network, (nx.DiGraph, nx.MultiDiGraph)):
-            return True
-    return False
-
-
-def normalise_layout(layout, network=None):
+# TODO: some of this logic should be moved into individual providers
+def normalise_layout(layout, network=None, nvertices=None):
     """Normalise the layout to a pandas.DataFrame."""
     from . import network_library
 
@@ -58,7 +29,7 @@ def normalise_layout(layout, network=None):
         ig = None
 
     if layout is None:
-        if (network is not None) and (number_of_vertices(network) == 0):
+        if (network is not None) and (nvertices == 0):
             return pd.DataFrame(np.zeros((0, 2)))
         return None
     if (network is not None) and isinstance(layout, str):

iplotx/ingest/providers/network/igraph.py

@@ -12,7 +12,6 @@ from ....typing import (
 )
 from ...heuristics import (
     normalise_layout,
-    detect_directedness,
 )
 from ...typing import (
     NetworkDataProvider,
@@ -26,21 +25,24 @@ from ....utils.internal import (
 class IGraphDataProvider(NetworkDataProvider):
     def __call__(
         self,
-        network: GraphType,
         layout: Optional[LayoutType] = None,
         vertex_labels: Optional[Sequence[str] | dict[Hashable, str] | pd.Series] = None,
         edge_labels: Optional[Sequence[str] | dict[str]] = None,
     ) -> NetworkData:
-        """Create network data object for iplotx from any provider."""
-
-        directed = detect_directedness(network)
+        """Create network data object for iplotx from an igraph object."""
+        network = self.network
+        directed = self.is_directed()
 
         # Recast vertex_labels=False as vertex_labels=None
         if np.isscalar(vertex_labels) and (not vertex_labels):
             vertex_labels = None
 
         # Vertices are ordered integers, no gaps
-        vertex_df = normalise_layout(layout, network=network)
+        vertex_df = normalise_layout(
+            layout,
+            network=network,
+            nvertices=self.number_of_vertices(),
+        )
         ndim = vertex_df.shape[1]
         vertex_df.columns = _make_layout_columns(ndim)
 
@@ -96,3 +98,11 @@ class IGraphDataProvider(NetworkDataProvider):
         import igraph as ig
 
         return ig.Graph
+
+    def is_directed(self):
+        """Whether the network is directed."""
+        return self.network.is_directed()
+
+    def number_of_vertices(self):
+        """The number of vertices/nodes in the network."""
+        return self.network.vcount()

iplotx/ingest/providers/network/networkx.py

@@ -12,7 +12,6 @@ from ....typing import (
 )
 from ...heuristics import (
     normalise_layout,
-    detect_directedness,
 )
 from ...typing import (
     NetworkDataProvider,
@@ -26,16 +25,17 @@ from ....utils.internal import (
 class NetworkXDataProvider(NetworkDataProvider):
     def __call__(
         self,
-        network: GraphType,
         layout: Optional[LayoutType] = None,
         vertex_labels: Optional[Sequence[str] | dict[Hashable, str] | pd.Series] = None,
         edge_labels: Optional[Sequence[str] | dict[str]] = None,
     ) -> NetworkData:
-        """Create network data object for iplotx from any provider."""
+        """Create network data object for iplotx from a networkx object."""
 
         import networkx as nx
 
-        directed = detect_directedness(network)
+        network = self.network
+
+        directed = self.is_directed()
 
         # Recast vertex_labels=False as vertex_labels=None
         if np.isscalar(vertex_labels) and (not vertex_labels):
@@ -45,6 +45,7 @@ class NetworkXDataProvider(NetworkDataProvider):
         vertex_df = normalise_layout(
             layout,
             network=network,
+            nvertices=self.number_of_vertices(),
         ).loc[pd.Index(network.nodes)]
         ndim = vertex_df.shape[1]
         vertex_df.columns = _make_layout_columns(ndim)
@@ -133,3 +134,12 @@ class NetworkXDataProvider(NetworkDataProvider):
         from networkx import Graph
 
         return Graph
+
+    def is_directed(self):
+        import networkx as nx
+
+        return isinstance(self.network, (nx.DiGraph, nx.MultiDiGraph))
+
+    def number_of_vertices(self):
+        """The number of vertices/nodes in the network."""
+        return self.network.number_of_nodes()