hiveplotlib 0.27.0__tar.gz → 0.28.0__tar.gz

{hiveplotlib-0.27.0 → hiveplotlib-0.28.0}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2020 - 2024, Geometric Data Analytics, Inc.
+Copyright (c) 2020 - 2026, Gary Koplik
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,
@@ -11,7 +11,7 @@ Redistributions in binary form must reproduce the above copyright notice,
 this list of conditions and the following disclaimer in the documentation
 and/or other materials provided with the distribution.
 
-Neither the name of Geometric Data Analytics nor the names of any contributors
+Neither the name of Gary Koplik nor the names of any contributors
 may be used to endorse or promote products derived from this software
 without specific prior written permission.
 

{hiveplotlib-0.27.0/src/hiveplotlib.egg-info → hiveplotlib-0.28.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: hiveplotlib
-Version: 0.27.0
+Version: 0.28.0
 Summary: Visualize Network Data with Hive Plots
-Author-email: Gary Koplik <gary.koplik@geomdata.com>
-License: Copyright (c) 2020 - 2024, Geometric Data Analytics, Inc.
+Author-email: Gary Koplik <gary.koplik@gmail.com>
+License: Copyright (c) 2020 - 2026, Gary Koplik
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without modification,
@@ -16,7 +16,7 @@ License: Copyright (c) 2020 - 2024, Geometric Data Analytics, Inc.
         this list of conditions and the following disclaimer in the documentation
         and/or other materials provided with the distribution.
         
-        Neither the name of Geometric Data Analytics nor the names of any contributors
+        Neither the name of Gary Koplik nor the names of any contributors
         may be used to endorse or promote products derived from this software
         without specific prior written permission.
         
@@ -33,7 +33,7 @@ License: Copyright (c) 2020 - 2024, Geometric Data Analytics, Inc.
         THE POSSIBILITY OF SUCH DAMAGE.
         
 Project-URL: Documentation, https://hiveplotlib.readthedocs.io/stable/
-Project-URL: Source, https://gitlab.com/geomdata/hiveplotlib
+Project-URL: Source, https://gitlab.com/hiveplotlib/hiveplotlib
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -48,19 +48,18 @@ Requires-Dist: datashader; extra == "datashader"
 Requires-Dist: numba>0.54.0; extra == "datashader"
 Requires-Dist: seaborn; extra == "datashader"
 Provides-Extra: dev
-Requires-Dist: bokeh>=3.0.0; extra == "dev"
 Requires-Dist: cartopy; extra == "dev"
-Requires-Dist: dask[dataframe]; extra == "dev"
-Requires-Dist: datashader; extra == "dev"
 Requires-Dist: flexitext; extra == "dev"
 Requires-Dist: geopandas; extra == "dev"
+Requires-Dist: hiveplotlib[bokeh]; extra == "dev"
+Requires-Dist: hiveplotlib[datashader]; extra == "dev"
+Requires-Dist: hiveplotlib[holoviews]; extra == "dev"
+Requires-Dist: hiveplotlib[networkx]; extra == "dev"
+Requires-Dist: hiveplotlib[plotly]; extra == "dev"
 Requires-Dist: holoviews>=1.15; extra == "dev"
 Requires-Dist: jupyter; extra == "dev"
-Requires-Dist: networkx; extra == "dev"
-Requires-Dist: numba>0.54.0; extra == "dev"
-Requires-Dist: plotly; extra == "dev"
+Requires-Dist: nx-parallel; extra == "dev"
 Requires-Dist: pybadges; extra == "dev"
-Requires-Dist: seaborn; extra == "dev"
 Requires-Dist: tqdm; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: ipywidgets; extra == "docs"
@@ -76,6 +75,7 @@ Requires-Dist: holoviews>=1.15; extra == "holoviews"
 Requires-Dist: numba>0.54.0; extra == "holoviews"
 Provides-Extra: networkx
 Requires-Dist: networkx; extra == "networkx"
+Requires-Dist: scipy; extra == "networkx"
 Provides-Extra: perf
 Requires-Dist: pyinstrument; extra == "perf"
 Requires-Dist: snakeviz; extra == "perf"
@@ -99,13 +99,14 @@ Dynamic: license-file
 
 A plotting package for generating and visualizing static Hive Plots in Python.
 
-![Supported Python Versions Matches PSF support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/python_badge.svg)
+![Supported Python Versions Matches PSF support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/python_badge.svg)
 
-[![Matplotlib Support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/matplotlib_badge.svg)](https://matplotlib.org/)
-[![Bokeh Support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/bokeh_badge.svg)](https://docs.bokeh.org/en/latest/)
-[![Holoviews Support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/holoviews_badge.svg)](https://holoviews.org/index.html)
-[![Plotly Support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/plotly_badge.svg)](https://plotly.com/python/)
-[![Datashader Support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/datashader_badge.svg)](https://datashader.org/)
+[![Matplotlib Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/matplotlib_badge.svg)](https://matplotlib.org/)
+[![Bokeh Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/bokeh_badge.svg)](https://docs.bokeh.org/en/latest/)
+[![Holoviews Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/holoviews_badge.svg)](https://holoviews.org/index.html)
+[![Plotly Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/plotly_badge.svg)](https://plotly.com/python/)
+[![Datashader Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/datashader_badge.svg)](https://datashader.org/)
+[![NetworkX Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/networkx_badge.svg)](https://networkx.org/)
 
 # Installation
 
@@ -129,6 +130,10 @@ and [plotly](https://plotly.com/python/) visualizations, which can be installed
 `hiveplotlib` also supports large network visualization via the [datashader](https://datashader.org/) backend,
 which can be installed as `pip install hiveplotlib[datashader]`.
 
+Beyond the visualization backends, `hiveplotlib` integrates with [networkx](https://networkx.org/): build a hive plot
+directly from a `networkx` graph and compute graph metrics on it. Install this integration with
+`pip install hiveplotlib[networkx]`.
+
 # How to Use and Examples
 
 For more on how to use the software and examples, see the
@@ -140,7 +145,7 @@ We recommend starting with our
 [Quick Start Hive Plots](https://hiveplotlib.readthedocs.io/stable/notebooks/quick_hive_plots.html) pages.
 
 All the example notebooks are available for download as `jupyter` notebooks in the repository under the
-[examples](https://gitlab.com/geomdata/hiveplotlib/-/tree/master/examples) directory.
+[examples](https://gitlab.com/hiveplotlib/hiveplotlib/-/tree/master/examples) directory.
 
 To install this environment and associated `jupyter` kernel used to run the notebooks, clone the repository and run:
 
@@ -158,7 +163,7 @@ For more on Hive Plots, see our
 
 For additional resources, see:
 
-- [http://www.hiveplot.com/](http://www.hiveplot.com/)
+- [https://hiveplot.com/](https://hiveplot.com/)
 
 - Krzywinski M, Birol I, Jones S, Marra M (2011). Hive Plots — Rational Approach to
 Visualizing Networks. Briefings in Bioinformatics (early access 9 December 2011,
@@ -166,7 +171,7 @@ doi: 10.1093/bib/bbr069).
 
 # Contributing
 
-For more on contributing to the project, see [CONTRIBUTING.md](https://gitlab.com/geomdata/hiveplotlib/-/blob/master/CONTRIBUTING.md)
+For more on contributing to the project, see [CONTRIBUTING.md](https://gitlab.com/hiveplotlib/hiveplotlib/-/blob/master/CONTRIBUTING.md)
 
 ## Acknowledgements
 

{hiveplotlib-0.27.0 → hiveplotlib-0.28.0}/README.md

@@ -2,13 +2,14 @@
 
 A plotting package for generating and visualizing static Hive Plots in Python.
 
-![Supported Python Versions Matches PSF support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/python_badge.svg)
+![Supported Python Versions Matches PSF support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/python_badge.svg)
 
-[![Matplotlib Support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/matplotlib_badge.svg)](https://matplotlib.org/)
-[![Bokeh Support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/bokeh_badge.svg)](https://docs.bokeh.org/en/latest/)
-[![Holoviews Support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/holoviews_badge.svg)](https://holoviews.org/index.html)
-[![Plotly Support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/plotly_badge.svg)](https://plotly.com/python/)
-[![Datashader Support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/datashader_badge.svg)](https://datashader.org/)
+[![Matplotlib Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/matplotlib_badge.svg)](https://matplotlib.org/)
+[![Bokeh Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/bokeh_badge.svg)](https://docs.bokeh.org/en/latest/)
+[![Holoviews Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/holoviews_badge.svg)](https://holoviews.org/index.html)
+[![Plotly Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/plotly_badge.svg)](https://plotly.com/python/)
+[![Datashader Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/datashader_badge.svg)](https://datashader.org/)
+[![NetworkX Support](https://gitlab.com/hiveplotlib/hiveplotlib/-/raw/master/.gitlab/networkx_badge.svg)](https://networkx.org/)
 
 # Installation
 
@@ -32,6 +33,10 @@ and [plotly](https://plotly.com/python/) visualizations, which can be installed
 `hiveplotlib` also supports large network visualization via the [datashader](https://datashader.org/) backend,
 which can be installed as `pip install hiveplotlib[datashader]`.
 
+Beyond the visualization backends, `hiveplotlib` integrates with [networkx](https://networkx.org/): build a hive plot
+directly from a `networkx` graph and compute graph metrics on it. Install this integration with
+`pip install hiveplotlib[networkx]`.
+
 # How to Use and Examples
 
 For more on how to use the software and examples, see the
@@ -43,7 +48,7 @@ We recommend starting with our
 [Quick Start Hive Plots](https://hiveplotlib.readthedocs.io/stable/notebooks/quick_hive_plots.html) pages.
 
 All the example notebooks are available for download as `jupyter` notebooks in the repository under the
-[examples](https://gitlab.com/geomdata/hiveplotlib/-/tree/master/examples) directory.
+[examples](https://gitlab.com/hiveplotlib/hiveplotlib/-/tree/master/examples) directory.
 
 To install this environment and associated `jupyter` kernel used to run the notebooks, clone the repository and run:
 
@@ -61,7 +66,7 @@ For more on Hive Plots, see our
 
 For additional resources, see:
 
-- [http://www.hiveplot.com/](http://www.hiveplot.com/)
+- [https://hiveplot.com/](https://hiveplot.com/)
 
 - Krzywinski M, Birol I, Jones S, Marra M (2011). Hive Plots — Rational Approach to
 Visualizing Networks. Briefings in Bioinformatics (early access 9 December 2011,
@@ -69,7 +74,7 @@ doi: 10.1093/bib/bbr069).
 
 # Contributing
 
-For more on contributing to the project, see [CONTRIBUTING.md](https://gitlab.com/geomdata/hiveplotlib/-/blob/master/CONTRIBUTING.md)
+For more on contributing to the project, see [CONTRIBUTING.md](https://gitlab.com/hiveplotlib/hiveplotlib/-/blob/master/CONTRIBUTING.md)
 
 ## Acknowledgements
 

{hiveplotlib-0.27.0 → hiveplotlib-0.28.0}/pyproject.toml

@@ -7,14 +7,14 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "hiveplotlib"
 requires-python = ">=3.10"
-version = "0.27.0"
+version = "0.28.0"
 authors = [
-    {name="Gary Koplik", email="gary.koplik@geomdata.com"}
+    {name="Gary Koplik", email="gary.koplik@gmail.com"}
 ]
 description = "Visualize Network Data with Hive Plots"
 readme = "README.md"
 license = {file = "LICENSE"}
-urls = {Documentation="https://hiveplotlib.readthedocs.io/stable/", Source="https://gitlab.com/geomdata/hiveplotlib" }
+urls = {Documentation="https://hiveplotlib.readthedocs.io/stable/", Source="https://gitlab.com/hiveplotlib/hiveplotlib" }
 
 
 dependencies = [
@@ -38,19 +38,18 @@ datashader = [
 
 # developer dependencies
 dev = [
-    "bokeh>=3.0.0",
     "cartopy",
-    "dask[dataframe]",  # https://github.com/holoviz/datashader/issues/1319
-    "datashader",
     "flexitext",
     "geopandas",
+    "hiveplotlib[bokeh]",
+    "hiveplotlib[datashader]",
+    "hiveplotlib[holoviews]",
+    "hiveplotlib[networkx]",
+    "hiveplotlib[plotly]",
     "holoviews>=1.15",
     "jupyter",
-    "networkx",
-    "numba>0.54.0",  # https://github.com/numba/numba/issues/9708
-    "plotly",
+    "nx-parallel",  # CI-testable networkx dispatch backend for `graph_metric_backend` tests
     "pybadges",
-    "seaborn",
     "tqdm",
 ]
 
@@ -72,7 +71,8 @@ holoviews = [
 ]
 
 networkx = [
-    "networkx"
+    "networkx",
+    "scipy",  # for some graph feature computations
 ]
 
 # performance profiling extras

{hiveplotlib-0.27.0 → hiveplotlib-0.28.0}/src/hiveplotlib/__init__.py

@@ -10,7 +10,6 @@ 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,

hiveplotlib-0.28.0/src/hiveplotlib/converters.py

@@ -0,0 +1,166 @@
+# converters.py
+
+"""
+Converters from various data structures to ``hiveplotlib``-ready structures.
+"""
+
+from typing import Optional
+
+import pandas as pd
+
+from hiveplotlib import Edges, NodeCollection
+
+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: nx.Graph,
+    unique_id_name: str = "unique_id",
+    check_uniqueness: bool = True,
+) -> 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 (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: a ``(NodeCollection, Edges)`` pair of ``hiveplotlib`` data structures.
+    """
+    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_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-0.27.0 → hiveplotlib-0.28.0}/src/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

{hiveplotlib-0.27.0 → hiveplotlib-0.28.0}/src/hiveplotlib/datasets/toy_hive_plots.py

@@ -11,8 +11,8 @@ from hiveplotlib import (
     BaseHivePlot,
     Node,
     NodeCollection,
-    hive_plot_n_axes,
 )
+from hiveplotlib.axis import Axis
 from hiveplotlib.datasets.international_trade import international_trade_data
 from hiveplotlib.edges import Edges
 from hiveplotlib.hiveplot import HivePlot
@@ -23,18 +23,17 @@ def example_base_hive_plot(
     num_nodes: int = 15,
     num_edges: int = 30,
     seed: int = 0,
-    **hive_plot_n_axes_kwargs,
 ) -> BaseHivePlot:
     """
     Generate example hive plot with ``"Low"``, ``"Medium"``, and ``"High"`` axes (plus repeat axes).
 
-    Nodes and edges will be generated and placed randomly.
+    Nodes and edges will be generated and placed randomly. The resulting ``BaseHivePlot`` has 6 axes
+    (each main axis paired with a ``"_repeat"`` sibling) arranged at 120° apart with 40° between each
+    pair of repeat axes.
 
     :param num_nodes: number of nodes to generate.
     :param num_edges: number of edges to generate.
     :param seed: random seed to use when generating nodes and edges.
-    :param hive_plot_n_axes_kwargs: additional keyword arguments for the underlying
-        :py:func:`hiveplotlib.hive_plot_n_axes()` call.
     :return: resulting ``BaseHivePlot`` instance.
     """
     color_dict = {
@@ -61,20 +60,62 @@ def example_base_hive_plot(
 
     edges = rng.choice(data["unique_id"].to_numpy(), size=num_edges * 2).reshape(-1, 2)
 
-    hp = hive_plot_n_axes(
-        nodes=NodeCollection(data=data, unique_id_column="unique_id"),
-        edges=edges,
-        axes_assignments=[
-            np.arange(num_nodes)[: num_nodes // 3],
-            np.arange(num_nodes)[num_nodes // 3 : 2 * num_nodes // 3],
-            np.arange(num_nodes)[2 * num_nodes // 3 :],
-        ],
-        sorting_variables=["low", "med", "high"],
-        repeat_axes=[True, True, True],
-        axes_names=["Low", "Medium", "High"],
-        orient_angle=-30,
-        **hive_plot_n_axes_kwargs,
-    )
+    nodes = NodeCollection(data=data, unique_id_column="unique_id")
+    axis_assignments = {
+        "Low": np.arange(num_nodes)[: num_nodes // 3],
+        "Medium": np.arange(num_nodes)[num_nodes // 3 : 2 * num_nodes // 3],
+        "High": np.arange(num_nodes)[2 * num_nodes // 3 :],
+    }
+    sorting_variable = {"Low": "low", "Medium": "med", "High": "high"}
+
+    # 3 partitions evenly spaced 120° apart, with the first axis center at -30°
+    base_angles = {"Low": -30, "Medium": 90, "High": 210}
+    angle_between_repeat_axes = 40
+
+    hp = BaseHivePlot()
+    hp.add_nodes(nodes)
+
+    for partition, base_angle in base_angles.items():
+        main_axis_angle = base_angle - angle_between_repeat_axes / 2
+        repeat_axis_angle = base_angle + angle_between_repeat_axes / 2
+        hp.add_axes(
+            [
+                Axis(axis_id=partition, angle=main_axis_angle),
+                Axis(axis_id=f"{partition}_repeat", angle=repeat_axis_angle),
+            ]
+        )
+        partition_node_df = data.iloc[axis_assignments[partition]]
+        for axis_id in (partition, f"{partition}_repeat"):
+            hp.place_nodes_on_axis(
+                axis_id=axis_id,
+                node_df=partition_node_df,
+                sorting_feature_to_use=sorting_variable[partition],
+            )
+
+    # connect each main axis to its repeat (intra-partition edges).
+    # Use one direction only so each edge is filed exactly once.
+    for partition in base_angles:
+        hp.connect_axes(
+            edges=edges,
+            axis_id_1=partition,
+            axis_id_2=f"{partition}_repeat",
+            a2_to_a1=False,
+            warn_on_no_edges=False,
+        )
+
+    # connect consecutive partitions counterclockwise via repeat→next-main pairs.
+    cyclic_pairs = [
+        ("Low_repeat", "Medium"),
+        ("Medium_repeat", "High"),
+        ("High_repeat", "Low"),
+    ]
+    for axis_id_1, axis_id_2 in cyclic_pairs:
+        hp.connect_axes(
+            edges=edges,
+            axis_id_1=axis_id_1,
+            axis_id_2=axis_id_2,
+            warn_on_no_edges=False,
+        )
 
     # set colors according to above-defined color dictionary
     #  (so we can replicate more easily in other viz later)
@@ -319,6 +360,7 @@ def example_nodes_and_edges(
 def example_hive_plot(
     num_nodes: int = 100,
     num_edges: int = 100,
+    drop_duplicate_edges: bool = False,
     partition_data_column: Literal["low", "med", "high"] = "low",
     labels: Optional[List[Hashable]] = ["A", "B", "C"],  # noqa: B006
     cutoffs: Union[List[Union[int, float]], int] = 3,
@@ -346,6 +388,10 @@ def example_hive_plot(
     :param num_nodes: how many nodes to randomly generate. Node unique IDs will be the integers 0, 1, ... ,
         ``num_nodes - 1``.
     :param num_edges: how many example edges to randomly generate.
+    :param drop_duplicate_edges: whether to drop row-wise duplicate ``(from, to)`` edges from the randomly generated
+        edge set before building the hive plot. Default ``False`` keeps every generated edge. Setting ``True`` removes
+        same-direction duplicates, so the resulting hive plot may have fewer than ``num_edges`` edges when the random
+        generation produced repeats.
     :param partition_data_column: which column of data in the underlying ``data`` attribute to use to partition the
         node data. Node data generated via :py:func:`hiveplotlib.datasets.toy_hive_plots.example_node_data()`.
     :param labels: labels assigned to each bin. Only referenced when ``cutoffs`` is not ``None``. ``None``
@@ -375,11 +421,14 @@ def example_hive_plot(
         seed=seed,
         unique_id_column=node_unique_id_column,
     )
-    edges = example_edges(
+    edge_df = example_edge_data(
         nodes=node_collection,
         num_edges=num_edges,
         seed=seed,
     )
+    if drop_duplicate_edges:
+        edge_df = edge_df.drop_duplicates(subset=["from", "to"], ignore_index=True)
+    edges = Edges(data=edge_df)
 
     temp_df = (
         edges._data[0]
@@ -418,6 +467,7 @@ def example_hpm_nodes_and_edges(
     nodes_per_group: int = 10,
     edge_tag_counts: Optional[Dict[str, int]] = None,
     edge_structure: Optional[Dict[str, str]] = None,
+    drop_duplicate_edges: bool = False,
     seed: int = 42,
 ) -> Tuple["NodeCollection", "Edges"]:
     """
@@ -458,6 +508,13 @@ def example_hpm_nodes_and_edges(
         - ``"intergroup"``: edges connect nodes in different groups only.
 
         Tags not listed in this dictionary default to ``"random"``.
+    :param drop_duplicate_edges: whether to drop same-direction duplicate ``(from, to)`` edges before building the
+        ``Edges`` object. Default ``False`` keeps every randomly generated edge. Setting ``True`` deduplicates across
+        the *union* of all tags (keeping the first occurrence by tag insertion order, then row order), so an edge
+        appearing under multiple tags is retained only under the earliest tag. This mirrors how graph-metric
+        computation collapses parallel edges when ``graph_multigraph=False``, so the resulting dataset will not emit
+        duplicate-edge warnings when computing edge metrics. Tags may end up with fewer edges than requested in
+        ``edge_tag_counts``.
     :param seed: base random seed. Seeds ``seed``, ``seed+1``, ... are used for
         successive edge tags respectively.
     :return: tuple of ``(NodeCollection, Edges)``.
@@ -537,12 +594,26 @@ def example_hpm_nodes_and_edges(
             {"from": from_nodes, "to": to_nodes},
         )
 
-    edges = Edges(
-        data={
-            tag: _make_edges(count, seed + i, edge_structure.get(tag, "random"))
-            for i, (tag, count) in enumerate(edge_tag_counts.items())
+    edge_frames = {
+        tag: _make_edges(count, seed + i, edge_structure.get(tag, "random"))
+        for i, (tag, count) in enumerate(edge_tag_counts.items())
+    }
+
+    if drop_duplicate_edges:
+        # dedup across the union of all tags, keeping the first occurrence by tag
+        # insertion order (then row order), matching the multigraph edge collapse.
+        combined = pd.concat(
+            [df.assign(_tag=tag) for tag, df in edge_frames.items()],
+            ignore_index=True,
+        ).drop_duplicates(subset=["from", "to"], keep="first")
+        edge_frames = {
+            tag: combined.loc[combined["_tag"] == tag, ["from", "to"]].reset_index(
+                drop=True
+            )
+            for tag in edge_frames
         }
-    )
+
+    edges = Edges(data=edge_frames)
     return nodes, edges