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

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.",
+    )

iplotx/ingest/providers/network/igraph.py

@@ -0,0 +1,96 @@
+from typing import (
+    Optional,
+    Sequence,
+)
+from collections.abc import Hashable
+import numpy as np
+import pandas as pd
+
+from ....typing import (
+    GraphType,
+    LayoutType,
+)
+from ...heuristics import (
+    normalise_layout,
+    detect_directedness,
+)
+from ...typing import (
+    NetworkDataProvider,
+    NetworkData,
+)
+from ....utils.internal import (
+    _make_layout_columns,
+)
+
+
+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)
+
+        # 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)
+        ndim = vertex_df.shape[1]
+        vertex_df.columns = _make_layout_columns(ndim)
+
+        # Vertex labels
+        if vertex_labels is not None:
+            if np.isscalar(vertex_labels):
+                vertex_df["label"] = vertex_df.index.astype(str)
+            elif len(vertex_labels) != len(vertex_df):
+                raise ValueError(
+                    "Vertex labels must be the same length as the number of vertices."
+                )
+            else:
+                vertex_df["label"] = vertex_labels
+
+        # Edges are a list of tuples, because of multiedges
+        tmp = []
+        for edge in network.es:
+            row = {"_ipx_source": edge.source, "_ipx_target": edge.target}
+            row.update(edge.attributes())
+            tmp.append(row)
+        if len(tmp):
+            edge_df = pd.DataFrame(tmp)
+        else:
+            edge_df = pd.DataFrame(columns=["_ipx_source", "_ipx_target"])
+        del tmp
+
+        # Edge labels
+        if edge_labels is not None:
+            if len(edge_labels) != len(edge_df):
+                raise ValueError(
+                    "Edge labels must be the same length as the number of edges."
+                )
+            edge_df["label"] = edge_labels
+
+        network_data = {
+            "vertex_df": vertex_df,
+            "edge_df": edge_df,
+            "directed": directed,
+            "ndim": ndim,
+        }
+        return network_data
+
+    def check_dependencies(self) -> bool:
+        try:
+            import igraph
+        except ImportError:
+            return False
+        return True
+
+    def graph_type(self):
+        import igraph as ig
+
+        return ig.Graph

iplotx/ingest/providers/network/networkx.py

@@ -0,0 +1,133 @@
+from typing import (
+    Optional,
+    Sequence,
+)
+from collections.abc import Hashable
+import numpy as np
+import pandas as pd
+
+from ....typing import (
+    GraphType,
+    LayoutType,
+)
+from ...heuristics import (
+    normalise_layout,
+    detect_directedness,
+)
+from ...typing import (
+    NetworkDataProvider,
+    NetworkData,
+)
+from ....utils.internal import (
+    _make_layout_columns,
+)
+
+
+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."""
+
+        import networkx as nx
+
+        directed = detect_directedness(network)
+
+        # Recast vertex_labels=False as vertex_labels=None
+        if np.isscalar(vertex_labels) and (not vertex_labels):
+            vertex_labels = None
+
+        # Vertices are indexed by node ID
+        vertex_df = normalise_layout(
+            layout,
+            network=network,
+        ).loc[pd.Index(network.nodes)]
+        ndim = vertex_df.shape[1]
+        vertex_df.columns = _make_layout_columns(ndim)
+
+        # Vertex internal properties
+        tmp = pd.DataFrame(dict(network.nodes.data())).T
+        # Arrays become a single column, which we have already anyway
+        if isinstance(layout, str) and (layout in tmp.columns):
+            del tmp[layout]
+        for col in tmp.columns:
+            vertex_df[col] = tmp[col]
+        del tmp
+
+        # Vertex labels
+        if vertex_labels is None:
+            if "label" in vertex_df:
+                del vertex_df["label"]
+        else:
+            if (
+                np.isscalar(vertex_labels)
+                and (not vertex_labels)
+                and ("label" in vertex_df)
+            ):
+                del vertex_df["label"]
+            elif vertex_labels is True:
+                if "label" not in vertex_df:
+                    vertex_df["label"] = vertex_df.index
+            elif (not np.isscalar(vertex_labels)) and (
+                len(vertex_labels) != len(vertex_df)
+            ):
+                raise ValueError(
+                    "Vertex labels must be the same length as the number of vertices."
+                )
+            elif isinstance(vertex_labels, nx.classes.reportviews.NodeDataView):
+                vertex_df["label"] = pd.Series(dict(vertex_labels))
+            else:
+                vertex_df["label"] = vertex_labels
+
+        # Edges are a list of tuples, because of multiedges
+        tmp = []
+        for u, v, d in network.edges.data():
+            row = {"_ipx_source": u, "_ipx_target": v}
+            row.update(d)
+            tmp.append(row)
+        if len(tmp):
+            edge_df = pd.DataFrame(tmp)
+        else:
+            edge_df = pd.DataFrame(columns=["_ipx_source", "_ipx_target"])
+        del tmp
+
+        # Edge labels
+        # Even though they could exist in the dataframe, request the to be explicitely mentioned
+        if (edge_labels is None) and ("label" in edge_df):
+            del edge_df["label"]
+        elif edge_labels is not None:
+            if np.isscalar(edge_labels):
+                if (not edge_labels) and ("label" in edge_df):
+                    del edge_df["label"]
+                if (edge_labels is True) and ("label" not in edge_df):
+                    edge_df["label"] = [str(i) for i in edge_df.index]
+            else:
+                if len(edge_labels) != len(edge_df):
+                    raise ValueError(
+                        "Edge labels must be the same length as the number of edges."
+                    )
+                edge_df["label"] = edge_labels
+
+        network_data = {
+            "vertex_df": vertex_df,
+            "edge_df": edge_df,
+            "directed": directed,
+            "ndim": ndim,
+        }
+        return network_data
+
+    def check_dependencies(self) -> bool:
+        try:
+            import networkx
+        except ImportError:
+            return False
+        return True
+
+    def graph_type(self):
+        from networkx import Graph
+
+        return Graph

iplotx/ingest/providers/tree/biopython.py

@@ -0,0 +1,105 @@
+from typing import (
+    Optional,
+    Sequence,
+)
+from collections.abc import Hashable
+from operator import attrgetter
+import numpy as np
+import pandas as pd
+
+from ....typing import (
+    TreeType,
+    LayoutType,
+)
+from ...typing import (
+    TreeDataProvider,
+    TreeData,
+)
+from ...heuristics import (
+    normalise_tree_layout,
+)
+
+
+class BiopythonDataProvider(TreeDataProvider):
+    def __call__(
+        self,
+        tree: TreeType,
+        layout: str | LayoutType,
+        orientation: str = "horizontal",
+        directed: bool | str = False,
+        vertex_labels: Optional[
+            Sequence[str] | dict[Hashable, str] | pd.Series | bool
+        ] = None,
+        edge_labels: Optional[Sequence[str] | dict] = None,
+    ) -> TreeData:
+        """Create tree data object for iplotx from BioPython.Phylo.Tree classes."""
+
+        tree_data = {
+            "root": tree.root,
+            "leaves": tree.get_terminals(),
+            "rooted": tree.rooted,
+            "directed": directed,
+            "ndim": 2,
+            "layout_name": layout,
+        }
+
+        # Add vertex_df including layout
+        tree_data["vertex_df"] = normalise_tree_layout(
+            layout,
+            tree=tree,
+            orientation=orientation,
+            root_fun=attrgetter("root"),
+            preorder_fun=lambda tree: tree.find_clades(order="preorder"),
+            postorder_fun=lambda tree: tree.find_clades(order="postorder"),
+            children_fun=attrgetter("clades"),
+            branch_length_fun=attrgetter("branch_length"),
+        )
+        if layout in ("radial",):
+            tree_data["layout_coordinate_system"] = "polar"
+        else:
+            tree_data["layout_coordinate_system"] = "cartesian"
+
+        # Add edge_df
+        edge_data = {"_ipx_source": [], "_ipx_target": []}
+        for node in tree.find_clades(order="preorder"):
+            for child in node.clades:
+                if directed == "parent":
+                    edge_data["_ipx_source"].append(child)
+                    edge_data["_ipx_target"].append(node)
+                else:
+                    edge_data["_ipx_source"].append(node)
+                    edge_data["_ipx_target"].append(child)
+        edge_df = pd.DataFrame(edge_data)
+        tree_data["edge_df"] = edge_df
+
+        # Add vertex labels
+        if vertex_labels is None:
+            vertex_labels = False
+        if np.isscalar(vertex_labels) and vertex_labels:
+            tree_data["vertex_df"]["label"] = [
+                x.name for x in tree_data["vertices"].index
+            ]
+        elif not np.isscalar(vertex_labels):
+            # If a dict-like object is passed, it can be incomplete (e.g. only the leaves):
+            # we fill the rest with empty strings which are not going to show up in the plot.
+            if isinstance(vertex_labels, pd.Series):
+                vertex_labels = dict(vertex_labels)
+            if isinstance(vertex_labels, dict):
+                for vertex in tree_data["vertex_df"].index:
+                    if vertex not in vertex_labels:
+                        vertex_labels[vertex] = ""
+            tree_data["vertex_df"]["label"] = pd.Series(vertex_labels)
+
+        return tree_data
+
+    def check_dependencies(self) -> bool:
+        try:
+            from Bio import Phylo
+        except ImportError:
+            return False
+        return True
+
+    def tree_type(self):
+        from Bio import Phylo
+
+        return Phylo.BaseTree.Tree