hiveplotlib 0.26.2__py3-none-any.whl → 0.28.0__py3-none-any.whl

hiveplotlib/__init__.py

@@ -10,7 +10,10 @@ from hiveplotlib.hiveplot import (  # noqa: F401
     SUPPORTED_VIZ_BACKENDS,
     BaseHivePlot,
     HivePlot,
-    hive_plot_n_axes,
+)
+from hiveplotlib.hiveplot_matrix import (  # noqa: F401
+    HPM_SUPPORTED_VIZ_BACKENDS,
+    HivePlotMatrix,
 )
 from hiveplotlib.node import Node, NodeCollection  # noqa: F401
 from hiveplotlib.p2cp import P2CP, p2cp_n_axes  # noqa: F401

hiveplotlib/axis.py

@@ -6,6 +6,7 @@ Definition of ``Axis`` instance and helper static methods for generating and wor
 
 from typing import Hashable, Optional
 
+import numpy as np
 import pandas as pd
 
 from hiveplotlib.utils import polar2cartesian
@@ -93,7 +94,9 @@ class Axis:
         self.sorting_variable = None
 
         # hold all the cartesian coordinates, polar rho, corresponding labels, and node metadata in a pandas dataframe
-        self.node_placements = pd.DataFrame(columns=["x", "y", "unique_id", "rho"])
+        self.node_placements = pd.DataFrame(
+            columns=np.array(["x", "y", "unique_id", "rho"])
+        )
 
         # hold the current vmin and vmax used to place nodes on an axis in a ``HivePlot`` instance.
         self.vmin = None

hiveplotlib/converters.py

@@ -4,38 +4,163 @@
 Converters from various data structures to ``hiveplotlib``-ready structures.
 """
 
-from typing import Tuple
+from typing import Optional
 
 import pandas as pd
 
-from hiveplotlib import Edges, Node, NodeCollection
-from hiveplotlib.node import node_collection_from_node_list
+from hiveplotlib import Edges, NodeCollection
 
-# say the graph type instead of calling `nx.Graph` to keep networkx dep out of this file.
-NetworkXGraph = "networkx.classes.graph.Graph instance"
+try:
+    import networkx as nx
+except ImportError as ie:  # pragma: no cover
+    msg = "`networkx` dependencies not installed, but can be installed by running `pip install hiveplotlib[networkx]`"
+    raise ImportError(msg) from ie
 
 
 def networkx_to_nodes_edges(
-    graph: NetworkXGraph,
+    graph: nx.Graph,
     unique_id_name: str = "unique_id",
     check_uniqueness: bool = True,
-) -> Tuple[NodeCollection, Edges]:  # type: ignore
+) -> tuple[NodeCollection, Edges]:
     """
     Take a ``networkx`` graph and return ``hiveplotlib``-friendly data structures.
 
     Specifically, returns a ``NodeCollection`` instance of node data and an ``Edges`` instance of
     edge data. These outputs can be fed directly into :py:func:`~hiveplotlib.HivePlot`.
 
-    :param graph: ``networkx`` graph.
+    :param graph: ``networkx`` graph (any of :py:class:`~networkx.Graph`, :py:class:`~networkx.DiGraph`,
+        :py:class:`~networkx.MultiGraph`, or :py:class:`~networkx.MultiDiGraph`).
     :param unique_id_name: name to use for unique IDs.
     :param check_uniqueness: whether or not to check that provided ``Node`` instances have unique IDs.
-    :return: ``list`` of ``Node`` instances, ``(n, 2)`` ``np.ndarray`` of edges.
+    :return: a ``(NodeCollection, Edges)`` pair of ``hiveplotlib`` data structures.
     """
-    nodes = [Node(unique_id=i, data=data) for i, data in list(graph.nodes.data())]
-    edge_keys = pd.DataFrame(list(graph.edges.keys()), columns=["from", "to"])
-    edge_values = pd.DataFrame(list(graph.edges.values()))
-    return node_collection_from_node_list(
-        node_list=nodes,
-        unique_id_name=unique_id_name,
+    node_data = []
+    for node, attributes in graph.nodes(data=True):
+        node_data.append({unique_id_name: node, **attributes})
+
+    node_df = pd.DataFrame(node_data)
+    edge_df = nx.to_pandas_edgelist(graph, source="from", target="to")
+    return NodeCollection(
+        data=node_df,
+        unique_id_column=unique_id_name,
         check_uniqueness=check_uniqueness,
-    ), Edges(data=edge_keys.join(edge_values))
+    ), Edges(data=edge_df)
+
+
+def nodes_edges_to_networkx(
+    nodes: NodeCollection,
+    edges: Edges,
+    *,
+    directed: bool = True,
+    multigraph: bool = True,
+    tag_attribute_name: str = "tag",
+    source_attribute_name: Optional[str] = None,
+) -> nx.Graph:
+    """
+    Convert a (``NodeCollection``, ``Edges``) pair to a ``networkx`` graph.
+
+    The concrete return type is determined by ``directed`` and ``multigraph``:
+
+    - ``directed=True``,  ``multigraph=True``  → :py:class:`networkx.MultiDiGraph` (default).
+    - ``directed=True``,  ``multigraph=False`` → :py:class:`networkx.DiGraph`.
+    - ``directed=False``, ``multigraph=True``  → :py:class:`networkx.MultiGraph`.
+    - ``directed=False``, ``multigraph=False`` → :py:class:`networkx.Graph`.
+
+    The defaults preserve duplicate edges faithfully and assume directed edges.
+
+    All non-(from / to) ``Edges`` DataFrame columns become edge attributes on the resulting graph. All
+    non-``unique_id_column`` node DataFrame columns become node attributes. The visualization-only attributes
+    ``node_viz_kwargs`` / ``edge_viz_kwargs`` are *not* included.
+
+    Multi-tag :py:class:`hiveplotlib.Edges`: when more than one tag is present, the original tag is written as an edge
+    attribute under ``tag_attribute_name`` (default ``"tag"``). If that name collides with an existing column on any
+    tag's edge DataFrame, a :class:`ValueError` is raised. Single-tag input does not write a tag attribute.
+
+    Optional source-row annotation: pass a string for ``source_attribute_name`` to tag each edge with a
+    ``(tag, row_index)`` tuple pointing back to its source row in the input :py:class:`hiveplotlib.Edges`. This is
+    useful for joining graph-level computations (e.g. edge metrics) back onto the original edge DataFrame (including
+    when there are multiple parallel edges in a multigraph). Default ``None`` skips this annotation.
+
+    .. note::
+        When ``multigraph=False`` but duplicate ``(from, to)`` pairs exist, ``networkx``'s :py:class:`networkx.Graph` /
+        :py:class:`networkx.DiGraph` will silently merge duplicates (last write wins). For an undirected
+        :py:class:`networkx.Graph`, reciprocal ``(a, b)`` / ``(b, a)`` rows likewise merge into a single undirected edge
+        (last write wins), so the merged edge carries only the surviving row's attributes (e.g. a ``weight``). Build
+        with ``multigraph=True`` to retain both edges as parallel edges, or pre-aggregate the weights into a single edge
+        beforehand.
+
+    :param nodes: :py:class:`hiveplotlib.NodeCollection` of node data.
+    :param edges: :py:class:`hiveplotlib.Edges` of edge data (single-tag or multi-tag).
+    :param directed: whether to return a :py:class:`networkx.DiGraph`-family graph. Default ``True``.
+    :param multigraph: whether to return a ``Multi*``-family graph. Default ``True``.
+    :param tag_attribute_name: edge-attribute name to use when storing the original tag on multi-tag inputs. Default
+        ``"tag"``.
+    :param source_attribute_name: optional edge-attribute name under which to store a ``(tag, row_index)`` source-row
+        identifier for every edge, useful for joining graph-level computations back onto the original edge DataFrame.
+        Default ``None`` skips annotation.
+    :return: ``networkx`` graph (one of :py:class:`networkx.Graph`, :py:class:`networkx.DiGraph`,
+        :py:class:`networkx.MultiGraph`, or :py:class:`networkx.MultiDiGraph`).
+    :raises ValueError: if ``tag_attribute_name`` collides with an existing edge column on a multi-tag
+        :py:class:`hiveplotlib.Edges` instance.
+    :raises ValueError: if ``source_attribute_name`` is a string and collides with an existing edge column on any tag.
+    """
+    if directed and multigraph:
+        graph_class = nx.MultiDiGraph
+    elif directed:
+        graph_class = nx.DiGraph
+    elif multigraph:
+        graph_class = nx.MultiGraph
+    else:
+        graph_class = nx.Graph
+    g = graph_class()
+
+    unique_id_column = nodes.unique_id_column
+    node_attr_cols = [c for c in nodes.data.columns if c != unique_id_column]
+    if node_attr_cols:
+        attr_records = nodes.data[node_attr_cols].to_dict(orient="records")
+        g.add_nodes_from(zip(nodes.data[unique_id_column], attr_records, strict=True))
+    else:
+        g.add_nodes_from(nodes.data[unique_id_column])
+
+    from_col = edges.from_column_name
+    to_col = edges.to_column_name
+    multi_tag = len(edges._data) > 1
+
+    if multi_tag:
+        for tag, df in edges._data.items():
+            if tag_attribute_name in df.columns:
+                msg = (
+                    f"Cannot write tag attribute under name '{tag_attribute_name}' "
+                    f"because tag '{tag}' already has a column with that name. "
+                    "Pass `tag_attribute_name='<new_name>'` to choose a different "
+                    "attribute name."
+                )
+                raise ValueError(msg)
+
+    if source_attribute_name is not None:
+        for tag, df in edges._data.items():
+            if source_attribute_name in df.columns:
+                msg = (
+                    f"Cannot write source attribute under name '{source_attribute_name}' "
+                    f"because tag '{tag}' already has a column with that name. "
+                    "Pass `source_attribute_name='<new_name>'` to choose a different "
+                    "attribute name."
+                )
+                raise ValueError(msg)
+
+    for tag, df in edges._data.items():
+        edge_attr_cols = [c for c in df.columns if c not in (from_col, to_col)]
+        attr_records = (
+            df[edge_attr_cols].to_dict(orient="records")
+            if edge_attr_cols
+            else [{} for _ in range(len(df))]
+        )
+        if multi_tag:
+            for attrs in attr_records:
+                attrs[tag_attribute_name] = tag
+        if source_attribute_name is not None:
+            for attrs, row_index in zip(attr_records, df.index, strict=True):
+                attrs[source_attribute_name] = (tag, row_index)
+        g.add_edges_from(zip(df[from_col], df[to_col], attr_records, strict=True))
+
+    return g

hiveplotlib/datasets/international_trade.py

@@ -21,7 +21,7 @@ def international_trade_data(
         roughly 300mb. However, the raw data are available at the
         `Harvard Growth Lab's website <https://doi.org/10.7910/DVN/T4CHWJ>`_, and the runner to produce the necessary
         files to use this reader function is available in the
-        `repository <https://gitlab.com/geomdata/hiveplotlib/-/blob/master/runners/make_trade_network_dataset.py>`_
+        `repository <https://gitlab.com/hiveplotlib/hiveplotlib/-/blob/master/runners/make_trade_network_dataset.py>`_
         (``make_trade_network_dataset.py``).
 
         If you are using the runner to make your own trade datasets that you will read in locally with this
@@ -52,7 +52,7 @@ def international_trade_data(
     csv_years = [i.split("_")[2] for i in csv_files]
     csv_hs92 = [i.split("_")[-1] for i in csv_files]
     hiveplotlib_supported_values = pd.DataFrame(
-        np.c_[csv_years, csv_hs92], columns=["Year", "Trade Code"]
+        np.c_[csv_years, csv_hs92], columns=np.array(["Year", "Trade Code"])
     )
 
     # check that our implied data and metadata files exist