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

iplotx/edge/ports.py

@@ -0,0 +1,47 @@
+"""
+Module for handling edge ports in iplotx.
+"""
+
+import numpy as np
+
+sq2 = np.sqrt(2) / 2
+
+port_dict = {
+    "s": (0, -1),
+    "w": (-1, 0),
+    "n": (0, 1),
+    "e": (1, 0),
+    "sw": (-sq2, -sq2),
+    "nw": (-sq2, sq2),
+    "ne": (sq2, sq2),
+    "se": (sq2, -sq2),
+}
+
+
+def _get_port_unit_vector(
+    portstring,
+    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.
+    v12 = trans_inv(
+        np.array(
+            [
+                [0, 0],
+                [1, 1],
+            ]
+        )
+    )
+    invertx = v12[1, 0] - v12[0, 0] < 0
+    inverty = v12[1, 1] - v12[0, 1] < 0
+
+    if invertx:
+        portstring = portstring.replace("w", "x").replace("e", "w").replace("x", "e")
+    if inverty:
+        portstring = portstring.replace("n", "x").replace("s", "n").replace("x", "s")
+
+    if portstring not in port_dict:
+        raise KeyError(f"Port not found: {portstring}")
+    return np.array(port_dict[portstring])

iplotx/groups.py

@@ -1,19 +1,22 @@
-from typing import Union, Sequence
-from copy import deepcopy
-from collections import defaultdict
+"""
+Module for vertex groupings code, especially the GroupingArtist class.
+"""
+
+from typing import Union
 import numpy as np
-import pandas as pd
 import matplotlib as mpl
 from matplotlib.collections import PatchCollection
 
 
-from .importing import igraph
 from .typing import (
     GroupingType,
     LayoutType,
 )
-from .heuristics import normalise_layout, normalise_grouping
-from .styles import get_style, rotate_style
+from .ingest.heuristics import (
+    normalise_layout,
+    normalise_grouping,
+)
+from .style import get_style, rotate_style
 from .utils.geometry import (
     convex_hull,
     _compute_group_path_with_vertex_padding,
@@ -21,14 +24,23 @@ from .utils.geometry import (
 
 
 class GroupingArtist(PatchCollection):
+    """Matplotlib artist for a vertex grouping (clustering/cover).
+
+    This class is used to plot patches surrounding groups of vertices in a network.
+    """
+
+    _factor = 1.0
+
     def __init__(
         self,
         grouping: GroupingType,
         layout: LayoutType,
         vertexpadding: Union[None, int] = None,
+        points_per_curve: int = 30,
+        transform: mpl.transforms.Transform = mpl.transforms.IdentityTransform(),
         *args,
         **kwargs,
-    ):
+    ) -> None:
         """Container artist for vertex groupings, e.g. covers or clusterings.
 
         Parameters:
@@ -38,21 +50,55 @@ class GroupingArtist(PatchCollection):
             layout: The layout of the vertices. If this object has no keys/index, the
                 vertices are assumed to have IDs corresponding to integers starting from
                 zero.
+            vertexpadding: How may points of padding to leave around each vertex centre.
+            points_per_curve: How many points to use to approximate a round envelope around
+                each convex hull vertex.
+            transform: The matplotlib transform to use for the patches (typically transData).
         """
         if vertexpadding is not None:
             self._vertexpadding = vertexpadding
         else:
             style = get_style(".grouping")
             self._vertexpadding = style.get("vertexpadding", 10)
-        patches, grouping, layout = self._create_patches(grouping, layout, **kwargs)
+
+        self._points_per_curve = points_per_curve
+
+        network = kwargs.pop("network", None)
+        patches, grouping, coords_hulls = self._create_patches(
+            grouping,
+            layout,
+            network,
+            **kwargs,
+        )
+        if "network" in kwargs:
+            del kwargs["network"]
         self._grouping = grouping
-        self._layout = layout
+        self._coords_hulls = coords_hulls
         kwargs["match_original"] = True
 
         super().__init__(patches, *args, **kwargs)
 
-    def _create_patches(self, grouping, layout, **kwargs):
-        layout = normalise_layout(layout)
+        zorder = get_style(".grouping").get("zorder", 1)
+        self.set_zorder(zorder)
+
+        self.set_transform(transform)
+
+    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) -> float:
+        """Get the vertex padding of each group."""
+        return self._vertexpadding
+
+    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
+
+    def _create_patches(self, grouping, layout, network, **kwargs):
+        layout = normalise_layout(layout, network=network)
         grouping = normalise_grouping(grouping, layout)
         style = get_style(".grouping")
         style.pop("vertexpadding", None)
@@ -60,6 +106,7 @@ class GroupingArtist(PatchCollection):
         style.update(kwargs)
 
         patches = []
+        coords_hulls = []
         for i, (name, vids) in enumerate(grouping.items()):
             if len(vids) == 0:
                 continue
@@ -67,6 +114,7 @@ class GroupingArtist(PatchCollection):
             coords = layout.loc[vids].values
             idx_hull = convex_hull(coords)
             coords_hull = coords[idx_hull]
+            coords_hulls.append(coords_hull)
 
             stylei = rotate_style(style, i)
 
@@ -79,23 +127,37 @@ class GroupingArtist(PatchCollection):
             )
 
             patches.append(patch)
-        return patches, grouping, layout
-
-    def _compute_paths(self):
-        if self._vertexpadding > 0:
-            for i, path in enumerate(self._paths):
-                self._paths[i].vertices = _compute_group_path_with_vertex_padding(
-                    path.vertices,
-                    self.get_transform(),
-                    vertexpadding=self._vertexpadding,
-                )
-
-    def _process(self):
-        self.set_transform(self.axes.transData)
-        self._compute_paths()
+        return patches, grouping, coords_hulls
+
+    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(
+                hull,
+                self._paths[i].vertices,
+                self.get_transform(),
+                vertexpadding=self.get_vertexpadding_dpi(dpi),
+                points_per_curve=ppc,
+            )
 
-    def draw(self, renderer):
+    def _process(self) -> None:
         self._compute_paths()
+
+    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)
 
 
@@ -111,24 +173,10 @@ def _compute_group_patch_stub(
         )
 
     # NOTE: Closing point: mpl is a bit quirky here
-    vertices = []
-    codes = []
-    if len(points) == 0:
-        vertices = np.zeros((0, 2))
-    elif len(points) == 1:
-        vertices = [points[0]] * 9
-        codes = ["MOVETO"] + ["CURVE3"] * 8
-    elif len(points) == 2:
-        vertices = [points[0]] * 5 + [points[1]] * 5 + [points[0]]
-        codes = ["MOVETO"] + ["CURVE3"] * 4 + ["LINETO"] + ["CURVE3"] * 4 + ["LINETO"]
-    else:
-        for point in points:
-            vertices.extend([point] * 3)
-            codes.extend(["LINETO", "CURVE3", "CURVE3"])
-        vertices.append(vertices[0])
-        codes.append("LINETO")
-        codes[0] = "MOVETO"
-
+    vertices = np.zeros(
+        (1 + 30 * len(points), 2),
+    )
+    codes = ["MOVETO"] + ["LINETO"] * (len(vertices) - 2) + ["CLOSEPOLY"]
     codes = [getattr(mpl.path.Path, x) for x in codes]
     patch = mpl.patches.PathPatch(
         mpl.path.Path(

iplotx/ingest/__init__.py

@@ -0,0 +1,155 @@
+"""
+This module focuses on how to ingest network data into standard data structures no matter what library they come from.
+"""
+
+import pathlib
+import pkgutil
+import importlib
+import warnings
+from typing import (
+    Optional,
+    Sequence,
+    Protocol,
+)
+from collections.abc import Hashable
+import pandas as pd
+
+from ..typing import (
+    GraphType,
+    LayoutType,
+    TreeType,
+)
+from .typing import (
+    NetworkDataProvider,
+    NetworkData,
+    TreeDataProvider,
+    TreeData,
+)
+
+provider_protocols = {
+    "network": NetworkDataProvider,
+    "tree": TreeDataProvider,
+}
+
+# Internally supported data providers
+data_providers: dict[str, dict[str, Protocol]] = {
+    kind: {} for kind in provider_protocols
+}
+for kind in data_providers:
+    providers_path = pathlib.Path(__file__).parent.joinpath("providers").joinpath(kind)
+    for importer, module_name, _ in pkgutil.iter_modules([providers_path]):
+        module = importlib.import_module(
+            f"iplotx.ingest.providers.{kind}.{module_name}"
+        )
+        for key, val in module.__dict__.items():
+            if key == provider_protocols[kind].__name__:
+                continue
+            if key.endswith("DataProvider"):
+                data_providers[kind][module_name] = val()
+                break
+    del providers_path
+
+
+def network_library(network) -> str:
+    """Guess the network library used to create the network."""
+    for name, provider in data_providers["network"].items():
+        if provider.check_dependencies():
+            graph_type = provider.graph_type()
+            if isinstance(network, graph_type):
+                return name
+    raise ValueError(
+        f"Network {network} did not match any available network library.",
+    )
+
+
+def tree_library(tree) -> str:
+    """Guess the tree library used to create the tree."""
+    for name, provider in data_providers["tree"].items():
+        if provider.check_dependencies():
+            tree_type = provider.tree_type()
+            if isinstance(tree, tree_type):
+                return name
+    raise ValueError(
+        f"Tree {tree} did not match any available tree library.",
+    )
+
+
+# Functions to ingest data from various libraries
+def ingest_network_data(
+    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 internal data for the network."""
+    _update_data_providers("network")
+
+    nl = network_library(network)
+
+    if nl in data_providers["network"]:
+        provider: NetworkDataProvider = data_providers["network"][nl]
+    else:
+        sup = ", ".join(data_providers["network"].keys())
+        raise ValueError(
+            f"Network library '{nl}' is not installed. "
+            f"Currently installed supported libraries: {sup}."
+        )
+
+    result = provider(
+        network=network,
+        layout=layout,
+        vertex_labels=vertex_labels,
+        edge_labels=edge_labels,
+    )
+    result["network_library"] = nl
+    return result
+
+
+def ingest_tree_data(
+    tree: TreeType,
+    layout: Optional[str] = "horizontal",
+    orientation: Optional[str] = "right",
+    directed: bool | str = False,
+    vertex_labels: Optional[Sequence[str] | dict[Hashable, str] | pd.Series] = None,
+    edge_labels: Optional[Sequence[str] | dict[str,]] = None,
+) -> TreeData:
+    """Create internal data for the tree."""
+    _update_data_providers("tree")
+
+    tl = tree_library(tree)
+
+    if tl in data_providers["tree"]:
+        provider: TreeDataProvider = data_providers["tree"][tl]
+    else:
+        sup = ", ".join(data_providers["tree"].keys())
+        raise ValueError(
+            f"Tree library '{tl}' is not installed. "
+            f"Currently installed supported libraries: {sup}."
+        )
+
+    result = provider(
+        tree=tree,
+        layout=layout,
+        orientation=orientation,
+        directed=directed,
+        vertex_labels=vertex_labels,
+        edge_labels=edge_labels,
+    )
+    result["tree_library"] = tl
+    return result
+
+
+# INTERNAL FUNCTIONS
+def _update_data_providers(kind):
+    """Update data provieders dynamically from external packages."""
+    discovered_providers = importlib.metadata.entry_points(
+        group=f"iplotx.{kind}_data_providers"
+    )
+    for entry_point in discovered_providers:
+        if entry_point.name not in data_providers["network"]:
+            try:
+                data_providers[kind][entry_point.name] = entry_point.load()
+            except Exception as e:
+                warnings.warn(
+                    f"Failed to load {kind} data provider '{entry_point.name}': {e}"
+                )

iplotx/ingest/heuristics.py

@@ -0,0 +1,209 @@
+"""
+Heuristics module to funnel certain variable inputs (e.g. layouts) into a standard format.
+"""
+
+from typing import (
+    Optional,
+    Any,
+)
+from collections.abc import Hashable
+from collections import defaultdict
+import numpy as np
+import pandas as pd
+
+from ..layout import compute_tree_layout
+from ..typing import (
+    GraphType,
+    GroupingType,
+    TreeType,
+    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):
+    """Normalise the layout to a pandas.DataFrame."""
+    from . import network_library
+
+    try:
+        import igraph as ig
+    except ImportError:
+        ig = None
+
+    if layout is None:
+        if (network is not None) and (number_of_vertices(network) == 0):
+            return pd.DataFrame(np.zeros((0, 2)))
+        return None
+    if (network is not None) and isinstance(layout, str):
+        if network_library(network) == "igraph":
+            if hasattr(network, layout):
+                layout = network[layout]
+            else:
+                layout = network.layout(layout)
+                # NOTE: This seems like a legit bug in igraph
+                # Sometimes (e.g. sugiyama) the layout has more vertices than the network (?)
+                layout = np.asarray(layout.coords)[: network.vcount()]
+        if network_library(network) == "networkx":
+            layout = dict(network.nodes.data(layout))
+
+    if (ig is not None) and isinstance(layout, ig.layout.Layout):
+        return pd.DataFrame(layout.coords)
+    if isinstance(layout, dict):
+        return pd.DataFrame(layout).T
+    if isinstance(layout, str):
+        raise NotImplementedError("Layout as a string is not supported yet.")
+    if isinstance(layout, (list, tuple)):
+        return pd.DataFrame(np.array(layout))
+    if isinstance(layout, pd.DataFrame):
+        return layout
+    if isinstance(layout, np.ndarray):
+        return pd.DataFrame(layout)
+    raise TypeError("Layout could not be normalised.")
+
+
+def normalise_tree_layout(
+    layout: str | Any,
+    tree: Optional[TreeType] = None,
+    **kwargs,
+) -> pd.DataFrame:
+    """Normalise tree layout from a variety of inputs.
+
+    Parameters:
+        layout: The tree layout to normalise.
+        tree: The correcponding tree object.
+        **kwargs: Additional arguments for the subroutines.
+
+    Returns:
+        A pandas DataFrame with the normalised tree layout.
+
+    NOTE: This function currently only accepts strings and computes
+        the layout internally. This might change in the future.
+    """
+    if isinstance(layout, str):
+        layout = compute_tree_layout(tree, layout, **kwargs)
+    else:
+        raise NotImplementedError(
+            "Only internally computed tree layout currently accepted."
+        )
+
+    if isinstance(layout, dict):
+        # Adjust vertex layout
+        index = []
+        coordinates = []
+        for key, coordinate in layout.items():
+            index.append(key)
+            coordinates.append(coordinate)
+        index = pd.Index(index)
+        coordinates = np.array(coordinates)
+        ndim = len(coordinates[0]) if len(coordinates) > 0 else 2
+        layout_columns = [f"_ipx_layout_{i}" for i in range(ndim)]
+        layout = pd.DataFrame(
+            coordinates,
+            index=index,
+            columns=layout_columns,
+        )
+
+    return layout
+
+
+def normalise_grouping(
+    grouping: GroupingType,
+    layout: LayoutType,
+) -> dict[Hashable, set]:
+    """Normalise network grouping from a variery of inputs.
+
+    Parameters:
+        grouping: Network grouping (e.g. vertex cover).
+        layout: Network layout.
+
+    Returns:
+        A dictionary of sets. Each key is the index of a group, each value is a set of vertices
+        included in that group. If all sets are mutually exclusive, this is a vertex clustering,
+        otherwise it's only a vertex cover.
+    """
+    try:
+        import igraph as ig
+    except ImportError:
+        ig = None
+
+    if len(grouping) == 0:
+        return {}
+
+    if isinstance(grouping, dict):
+        val0 = next(iter(grouping.values()))
+        # If already the right data type or compatible, leave as is
+        if isinstance(val0, (set, frozenset)):
+            return grouping
+
+        # If a dict of integers or strings, assume each key is a vertex id and each value is a
+        # group, convert (i.e. invert the dict)
+        if isinstance(val0, (int, str)):
+            group_dic = defaultdict(set)
+            for key, val in grouping.items():
+                group_dic[val].add(key)
+            return group_dic
+
+    # If an igraph object, convert to a dict of sets
+    if ig is not None:
+        if isinstance(grouping, ig.clustering.Clustering):
+            layout = normalise_layout(layout)
+            group_dic = defaultdict(set)
+            for i, member in enumerate(grouping.membership):
+                group_dic[member].add(i)
+            return group_dic
+
+        if isinstance(grouping, ig.clustering.Cover):
+            layout = normalise_layout(layout)
+            group_dic = defaultdict(set)
+            for i, members in enumerate(grouping.membership):
+                for member in members:
+                    group_dic[member].add(i)
+            return group_dic
+
+    # Assume it's a sequence, so convert to list
+    grouping = list(grouping)
+
+    # If the values are already sets, assume group indices are integers
+    # and values are as is
+    if isinstance(grouping[0], set):
+        return dict(enumerate(grouping))
+
+    # If the values are integers or strings, assume each key is a vertex id and each value is a
+    # group, convert to dict of sets
+    if isinstance(grouping[0], (int, str)):
+        group_dic = defaultdict(set)
+        for i, val in enumerate(grouping):
+            group_dic[val].add(i)
+        return group_dic
+
+    raise TypeError(
+        "Could not standardise grouping from object.",
+    )