hiveplotlib 0.25.1__tar.gz → 0.26.0rc1__tar.gz

{hiveplotlib-0.25.1/src/hiveplotlib.egg-info → hiveplotlib-0.26.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: hiveplotlib
-Version: 0.25.1
+Version: 0.26.0rc1
 Summary: Visualize Network Data with Hive Plots
 Author-email: Gary Koplik <gary.koplik@geomdata.com>
 License: Copyright (c) 2020 - 2024, Geometric Data Analytics, Inc.
@@ -34,6 +34,7 @@ License: Copyright (c) 2020 - 2024, Geometric Data Analytics, Inc.
         
 Project-URL: Documentation, https://hiveplotlib.readthedocs.io/stable/
 Project-URL: Source, https://gitlab.com/geomdata/hiveplotlib
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: matplotlib
@@ -44,27 +45,34 @@ Requires-Dist: bokeh; extra == "bokeh"
 Provides-Extra: datashader
 Requires-Dist: dask[dataframe]; extra == "datashader"
 Requires-Dist: datashader; extra == "datashader"
+Requires-Dist: numba>0.54.0; extra == "datashader"
 Requires-Dist: seaborn; extra == "datashader"
 Provides-Extra: dev
-Requires-Dist: bokeh; extra == "dev"
+Requires-Dist: bokeh<3.7.0; extra == "dev"
 Requires-Dist: cartopy; extra == "dev"
+Requires-Dist: dask[dataframe]; extra == "dev"
 Requires-Dist: datashader; extra == "dev"
-Requires-Dist: geopandas; extra == "dev"
 Requires-Dist: flexitext; extra == "dev"
-Requires-Dist: holoviews; extra == "dev"
+Requires-Dist: geopandas; extra == "dev"
+Requires-Dist: holoviews<1.20.2; 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: pybadges; extra == "dev"
 Requires-Dist: seaborn; extra == "dev"
 Requires-Dist: tqdm; extra == "dev"
 Provides-Extra: docs
+Requires-Dist: myst-parser; extra == "docs"
 Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: pydata-sphinx-theme; extra == "docs"
 Requires-Dist: sphinx; extra == "docs"
-Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
 Requires-Dist: toml; extra == "docs"
 Provides-Extra: holoviews
-Requires-Dist: holoviews; extra == "holoviews"
+Requires-Dist: bokeh<3.7.0; extra == "holoviews"
+Requires-Dist: holoviews<1.20.2; extra == "holoviews"
+Requires-Dist: numba>0.54.0; extra == "holoviews"
 Provides-Extra: networkx
 Requires-Dist: networkx; extra == "networkx"
 Provides-Extra: plotly
@@ -77,31 +85,33 @@ Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: pytest-html; extra == "testing"
 Requires-Dist: pytest-timeout; extra == "testing"
 Requires-Dist: pytest-xdist; extra == "testing"
+Requires-Dist: toml; extra == "testing"
+Dynamic: license-file
 
-![](https://hiveplotlib.readthedocs.io/stable/_static/hiveplotlib.svg)
+![Hiveplotlib Logo](https://hiveplotlib.readthedocs.io/stable/_static/hiveplotlib.svg)
 
 A plotting package for generating and visualizing static Hive Plots in Python.
 
-![](https://gitlab.com/geomdata/hiveplotlib/-/raw/22-add-formal-holoviews-support/.gitlab/python_badge.svg)
+![Supported Python Versions Matches PSF support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/python_badge.svg)
 
-[![](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/matplotlib_badge.svg)](https://matplotlib.org/)
-[![](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/bokeh_badge.svg)](https://docs.bokeh.org/en/latest/)
-[![](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/holoviews_badge.svg)](https://holoviews.org/index.html)
-[![](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/plotly_badge.svg)](https://plotly.com/python/)
-[![](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/datashader_badge.svg)](https://datashader.org/)
+[![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/)
 
 # Installation
 
 `hiveplotlib` can be installed via [pypi](https://pypi.org/project/hiveplotlib/):
 
-```
-$ pip install hiveplotlib
+```bash
+pip install hiveplotlib
 ```
 
 To uninstall, run:
 
-```
-$ pip uninstall hiveplotlib
+```bash
+pip uninstall hiveplotlib
 ```
 
 By default, `hiveplotlib` supports visualization only with the [matplotlib](https://matplotlib.org/) backend, but
@@ -112,32 +122,32 @@ 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]`.
 
-# Contributing
-
-For more on contributing to the project, see [CONTRIBUTING.md](https://gitlab.com/geomdata/hiveplotlib/-/blob/master/CONTRIBUTING.md)
-
 # How to Use and Examples
 
 For more on how to use the software and examples, see the
-[docs](https://hiveplotlib.readthedocs.io/stable/index.html).
+[tutorials](https://hiveplotlib.readthedocs.io/stable/notebooks/index.html) and
+[gallery examples](https://hiveplotlib.readthedocs.io/stable/gallery_examples/index.html).
+
+We recommend starting with our
+[Introduction to Hive Plots](https://hiveplotlib.readthedocs.io/stable/notebooks/introduction_to_hive_plots.html) and
+[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.
 
-If trying to run the example notebooks, note that these are maintained to run in the conda
-environment in the repository, specified by `hiveplot_env.yml`.
-
-To install this `conda` environment and associated `jupyter` kernel, clone the repository and run:
+To install this environment and associated `jupyter` kernel used to run the notebooks, clone the repository and run:
 
+```bash
+cd <path/to/repository>
+bash install.sh
 ```
-$ cd <path/to/repository>
-$ bash install.sh
-```
+
+The resulting `hiveplotlib` kernel can run any of those notebooks.
 
 # More on Hive Plots
 
 For more on Hive Plots, see our
-[Introduction to Hive Plots](https://hiveplotlib.readthedocs.io/stable/introduction_to_hive_plots.html).
+[Introduction to Hive Plots](https://hiveplotlib.readthedocs.io/stable/notebooks/introduction_to_hive_plots.html).
 
 For additional resources, see:
 
@@ -147,9 +157,13 @@ For additional resources, see:
 Visualizing Networks. Briefings in Bioinformatics (early access 9 December 2011,
 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)
+
 ## Acknowledgements
 
 We'd like to thank Rodrigo Garcia-Herrera for his work on
 [`pyveplot`](https://gitlab.com/rgarcia-herrera/pyveplot), which we referenced
 as a starting point for our structural design. We also translated some of his utility
-methods for use in this repository. 
+methods for use in this repository.

{hiveplotlib-0.25.1 → hiveplotlib-0.26.0rc1}/README.md

@@ -1,27 +1,27 @@
-![](https://hiveplotlib.readthedocs.io/stable/_static/hiveplotlib.svg)
+![Hiveplotlib Logo](https://hiveplotlib.readthedocs.io/stable/_static/hiveplotlib.svg)
 
 A plotting package for generating and visualizing static Hive Plots in Python.
 
-![](https://gitlab.com/geomdata/hiveplotlib/-/raw/22-add-formal-holoviews-support/.gitlab/python_badge.svg)
+![Supported Python Versions Matches PSF support](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/python_badge.svg)
 
-[![](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/matplotlib_badge.svg)](https://matplotlib.org/)
-[![](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/bokeh_badge.svg)](https://docs.bokeh.org/en/latest/)
-[![](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/holoviews_badge.svg)](https://holoviews.org/index.html)
-[![](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/plotly_badge.svg)](https://plotly.com/python/)
-[![](https://gitlab.com/geomdata/hiveplotlib/-/raw/master/.gitlab/datashader_badge.svg)](https://datashader.org/)
+[![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/)
 
 # Installation
 
 `hiveplotlib` can be installed via [pypi](https://pypi.org/project/hiveplotlib/):
 
-```
-$ pip install hiveplotlib
+```bash
+pip install hiveplotlib
 ```
 
 To uninstall, run:
 
-```
-$ pip uninstall hiveplotlib
+```bash
+pip uninstall hiveplotlib
 ```
 
 By default, `hiveplotlib` supports visualization only with the [matplotlib](https://matplotlib.org/) backend, but
@@ -32,32 +32,32 @@ 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]`.
 
-# Contributing
-
-For more on contributing to the project, see [CONTRIBUTING.md](https://gitlab.com/geomdata/hiveplotlib/-/blob/master/CONTRIBUTING.md)
-
 # How to Use and Examples
 
 For more on how to use the software and examples, see the
-[docs](https://hiveplotlib.readthedocs.io/stable/index.html).
+[tutorials](https://hiveplotlib.readthedocs.io/stable/notebooks/index.html) and
+[gallery examples](https://hiveplotlib.readthedocs.io/stable/gallery_examples/index.html).
+
+We recommend starting with our
+[Introduction to Hive Plots](https://hiveplotlib.readthedocs.io/stable/notebooks/introduction_to_hive_plots.html) and
+[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.
 
-If trying to run the example notebooks, note that these are maintained to run in the conda
-environment in the repository, specified by `hiveplot_env.yml`.
+To install this environment and associated `jupyter` kernel used to run the notebooks, clone the repository and run:
 
-To install this `conda` environment and associated `jupyter` kernel, clone the repository and run:
-
-```
-$ cd <path/to/repository>
-$ bash install.sh
+```bash
+cd <path/to/repository>
+bash install.sh
 ```
 
+The resulting `hiveplotlib` kernel can run any of those notebooks.
+
 # More on Hive Plots
 
 For more on Hive Plots, see our
-[Introduction to Hive Plots](https://hiveplotlib.readthedocs.io/stable/introduction_to_hive_plots.html).
+[Introduction to Hive Plots](https://hiveplotlib.readthedocs.io/stable/notebooks/introduction_to_hive_plots.html).
 
 For additional resources, see:
 
@@ -67,9 +67,13 @@ For additional resources, see:
 Visualizing Networks. Briefings in Bioinformatics (early access 9 December 2011,
 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)
+
 ## Acknowledgements
 
 We'd like to thank Rodrigo Garcia-Herrera for his work on
 [`pyveplot`](https://gitlab.com/rgarcia-herrera/pyveplot), which we referenced
 as a starting point for our structural design. We also translated some of his utility
-methods for use in this repository. 
+methods for use in this repository.

{hiveplotlib-0.25.1 → hiveplotlib-0.26.0rc1}/pyproject.toml

@@ -6,7 +6,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hiveplotlib"
-version = "0.25.1"
+requires-python = ">=3.9"
+version = "0.26.0rc1"
 authors = [
     {name="Gary Koplik", email="gary.koplik@geomdata.com"}
 ]
@@ -31,19 +32,22 @@ bokeh = [
 datashader = [
     "dask[dataframe]",  # https://github.com/holoviz/datashader/issues/1319
     "datashader",
+    "numba>0.54.0",  # https://github.com/numba/numba/issues/9708
     "seaborn"
 ]
 
 # developer dependencies
 dev = [
-    "bokeh",
+    "bokeh<3.7.0",  # to maintain holoviews compatibility (see note below)
     "cartopy",
+    "dask[dataframe]",  # https://github.com/holoviz/datashader/issues/1319
     "datashader",
-    "geopandas",
     "flexitext",
-    "holoviews",
+    "geopandas",
+    "holoviews<1.20.2",  # to keep from forcing bokeh 3.7 (bokeh 3.6+ dropped python 3.9 compatibility)
     "jupyter",
     "networkx",
+    "numba>0.54.0",  # https://github.com/numba/numba/issues/9708
     "plotly",
     "pybadges",
     "seaborn",
@@ -52,14 +56,18 @@ dev = [
 
 # for building documentation
 docs = [
+    "myst-parser",
     "nbsphinx",
+    "pydata-sphinx-theme",
     "sphinx",
-    "sphinx-rtd-theme",
-    "toml"
+    "sphinx-copybutton",
+    "toml",
 ]
 
 holoviews = [
-    "holoviews"
+    "bokeh<3.7.0",  # to maintain holoviews compatibility (see note below)
+    "holoviews<1.20.2",  # to keep from forcing bokeh 3.7 (bokeh 3.6+ dropped python 3.9 compatibility)
+    "numba>0.54.0",  # https://github.com/numba/numba/issues/9708
 ]
 
 networkx = [
@@ -80,7 +88,8 @@ testing = [
     "pytest-cov",
     "pytest-html",
     "pytest-timeout",
-    "pytest-xdist"
+    "pytest-xdist",
+    "toml",
 ]
 
 [tool.setuptools.packages.find]
@@ -95,7 +104,7 @@ extend-include = ["*.ipynb", "*.pyi"]
 
 # Add files here to be completely skipped by ruff.
 extend-exclude = [
-    "docs",
+    "docs/source/*.ipynb",
     "sandbox"
 ]
 
@@ -107,20 +116,20 @@ target-version = "py311"
 
 [tool.ruff.lint]
 extend-ignore = [
-    "ANN101",  # typing `self` being deprecated (and not particularly useful)
     "ANN003",  # don't require type hints on kwargs (too many possible types to be useful)
     "D200",  # 1-line docstrings will be tolerated
     "D203",  # don't require blank line before class docstring.
     "D212",  # require docstring text starts on the next line after the triple quotes.
     "E203",  # https://black.readthedocs.io/en/stable/faq.html#why-are-flake8-s-e203-and-w503-violated
     "PD901",  # generic `df` name for pandas dataframes will be tolerated
+    "B905",  # this is a python 3.10 convention, drop ignore when we drop 3.9 support 
 ]
 
 extend-select = [
     "A",  # use flake8-builtins (check if variable name shadows python builtin names)
     "ANN",  # use flake8-annotations (checks type annotations)
     "ARG",  # use flake8-unused-arguments (checks for unused arguments)
-    # "B",  # use flake8-bugbear (nice for cleaner code, but appears to only work when min Python constraint is 3.9)
+    "B",  # use flake8-bugbear (nice for cleaner code)
     "C4",  # use flake8-comprehensions (remove unnecessary literals, generators, lists, etc.) 
     "D",  # use pydoc style rules
     "E",  # use pycodestyle warnings
@@ -138,6 +147,9 @@ extend-select = [
     "W",  # use pycodestyle warnings
 ] 
 
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
 [tool.ruff.lint.pycodestyle]
 # allow docstrings to go longer
 max-line-length = 120

hiveplotlib-0.26.0rc1/src/hiveplotlib/__init__.py

@@ -0,0 +1,16 @@
+# __init__.py
+
+"""
+Sets up high-level imports of basic data structures and static methods.
+"""
+
+from hiveplotlib.axis import Axis  # noqa: F401
+from hiveplotlib.edges import Edges  # noqa: F401
+from hiveplotlib.hiveplot import (  # noqa: F401
+    SUPPORTED_VIZ_BACKENDS,
+    BaseHivePlot,
+    HivePlot,
+    hive_plot_n_axes,
+)
+from hiveplotlib.node import Node, NodeCollection  # noqa: F401
+from hiveplotlib.p2cp import P2CP, p2cp_n_axes  # noqa: F401

{hiveplotlib-0.25.1 → hiveplotlib-0.26.0rc1}/src/hiveplotlib/axis.py

@@ -4,9 +4,8 @@
 Definition of ``Axis`` instance and helper static methods for generating and working with ``Axis`` instances.
 """
 
-from typing import Hashable, List, Optional
+from typing import Hashable, Optional
 
-import numpy as np
 import pandas as pd
 
 from hiveplotlib.utils import polar2cartesian
@@ -58,6 +57,7 @@ class Axis:
         end: float = 5,
         angle: float = 0,
         long_name: Optional[Hashable] = None,
+        metadata: Optional[dict] = None,
     ) -> None:
         """
         Initialize ``Axis`` object with start and end positions and angle. Default to axis normalized on [0, 1].
@@ -70,6 +70,8 @@ class Axis:
             0 degrees points East, 90 degrees points North).
         :param long_name: longer name for use when labeling on graph (but not for referencing the axis).
             Default ``None`` sets it to ``axis_id``.
+        :param metadata: optional dictionary of metadata to attach to the axis.
+            Default ``None`` means no metadata is attached.
         """
         self.axis_id = axis_id
 
@@ -87,23 +89,55 @@ class Axis:
         self.polar_end = end
         self.end = polar2cartesian(self.polar_end, self.angle)
 
-        # key from each node's data dictionary that we will use to position the node along the `Axis`
-        self.node_placement_label = None
+        # hold the current sorting variable used to place nodes on an axis in a ``HivePlot`` instance.
+        self.sorting_variable = None
 
-        # hold all the cartesian coordinates, polar rho, and corresponding labels in a pandas dataframe
+        # 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"])
 
+        # hold the current vmin and vmax used to place nodes on an axis in a ``HivePlot`` instance.
+        self.vmin = None
+        self.vmax = None
+
+        # hold whether current vmin and vmax used to place nodes on an axis in a ``HivePlot`` instance were inferred.
+        self.inferred_vmin = None
+        self.inferred_vmax = None
+
+        self.metadata = metadata if metadata is not None else {}
+
+    def __str__(self) -> str:
+        """
+        Make more human-readable, multiline representation for ``Axis`` instance.
+        """
+        return (
+            f"hiveplotlib.Axis '{self.axis_id}'\n"
+            f"Current data vmin: {self.vmin}\n"
+            f"Current data vmax: {self.vmax}\n"
+            f"Current sorting variable used to place nodes on this axis: '{self.sorting_variable}'\n"
+            f"Current polar start: {self.polar_start}\n"
+            f"Current polar end: {self.polar_end}\n"
+            f"Current angle: {self.angle}\n"
+            f"Inferred vmin: {self.inferred_vmin}\n"
+            f"Inferred vmax: {self.inferred_vmax}\n"
+            f"Long name: '{self.long_name}'"
+        )
+
     def __repr__(self) -> str:
         """
-        Make printable representation (repr) for ``Axis`` instance.
+        Make custom repr for ``Axis`` instance.
         """
-        return f"hiveplotlib.Axis {self.axis_id}"
+        return (
+            f"hiveplotlib.Axis(axis_id='{self.axis_id}', start={self.polar_start}, "
+            f"end={self.polar_end}, angle={self.angle}, long_name='{self.long_name}')"
+        )
 
-    def _set_node_placements(
-        self, x: List[float], y: List[float], node_ids: List[Hashable], rho: List[float]
+    def set_node_placements(
+        self,
+        placements_df: pd.DataFrame,
+        unique_id: Hashable,
     ) -> None:
         """
-        Set ``Axis.node_placements`` to a ``pandas.DataFrame``.
+        Set ``Axis.node_placements`` to a ``pandas.DataFrame`` of node placement information with node metadata.
 
         Dataframe consists of x cartesian coordinates, y cartesian coordinates, unique node IDs, and polar *rho* values
         (e.g. distance from the origin).
@@ -112,24 +146,28 @@ class Axis:
             This is an internal setter method to be called downstream by the ``HivePlot.place_nodes_on_axis()``
             method.
 
-        :param x: ``list-like`` of x cartesian coordinates.
-        :param y: ``list-like`` of y cartesian coordinates corresponding to x coordinates.
-        :param node_ids: ``list-like`` of unique node IDs corresponding to x and y coordinates.
-        :param rho: ``list-like`` of polar coordinate distance values corresponding to x, y, and unique ID values.
+        :param placements_df: dataframe of placement information and other node metadata.
+        :param unique_id: column corresponding to node unique IDs.
         :return: ``None``.
         """
-        assert (
-            np.array(x).shape[0]
-            == np.array(y).shape[0]
-            == np.array(node_ids).shape[0]
-            == np.array(rho).shape[0]
-        ), "Must provide the same number of x values, y values, and node IDs"
-
-        self.node_placements = pd.DataFrame.from_dict(
-            {"x": x, "y": y, "unique_id": node_ids, "rho": rho}
+        assert "x" in placements_df.columns.to_numpy(), (
+            "'x' not in `node_df` column names"
+        )
+        assert "y" in placements_df.columns.to_numpy(), (
+            "'y' not in `node_df` column names"
+        )
+        assert unique_id in placements_df.columns.to_numpy(), (
+            f"'{unique_id}' not in `node_df` column names"
+        )
+        assert "rho" in placements_df.columns.to_numpy(), (
+            "'rho' not in `node_df` column names"
         )
 
-    def _set_node_placement_label(self, label: Hashable) -> None:
+        self.node_placements = placements_df.copy()
+
+        return
+
+    def set_sorting_variable(self, label: Hashable) -> None:
         """
         Set which scalar variable in each ``Node`` instance will be used to place each node on the axis when plotting.
 
@@ -140,4 +178,37 @@ class Axis:
         :param label: which scalar variable in the node data to reference.
         :return: ``None``.
         """
-        self.node_placement_label = label
+        self.sorting_variable = label
+
+    def set_node_vmin_and_vmax(
+        self, vmin: float, vmax: float, inferred_vmin: bool, inferred_vmax: bool
+    ) -> None:
+        """
+        Set the vmin and vmax values used to place nodes on the axis.
+
+        .. note::
+            This is an internal setter method to be called downstream by the ``HivePlot.place_nodes_on_axis()``
+            method.
+
+        :param vmin: all node scalar values less than ``vmin`` would have been set to ``vmin``
+        :param vmax: all node scalar values greater than ``vmax`` would have been set to ``vmax``.
+        :param inferred_vmin: whether ``vmin`` value was inferred in ``HivePlot.place_nodes_on_axis()``.
+        :param inferred_vmax: whether ``vmax`` value was inferred in ``HivePlot.place_nodes_on_axis()``.
+        :return: ``None``.
+        """
+        self.vmin = vmin
+        self.vmax = vmax
+        self.inferred_vmin = inferred_vmin
+        self.inferred_vmax = inferred_vmax
+
+    def add_metadata(self, metadata: dict) -> None:
+        """
+        Add metadata to the axis.
+
+        This method will overwrite existing metadata with the same keys.
+
+        :param metadata: dictionary of metadata to add to the axis.
+        :return: ``None``.
+        """
+        self.metadata.update(metadata)
+        return

hiveplotlib-0.26.0rc1/src/hiveplotlib/converters.py

@@ -0,0 +1,41 @@
+# converters.py
+
+"""
+Converters from various data structures to ``hiveplotlib``-ready structures.
+"""
+
+from typing import Tuple
+
+import pandas as pd
+
+from hiveplotlib import Edges, Node, NodeCollection
+from hiveplotlib.node import node_collection_from_node_list
+
+# say the graph type instead of calling `nx.Graph` to keep networkx dep out of this file.
+NetworkXGraph = "networkx.classes.graph.Graph instance"
+
+
+def networkx_to_nodes_edges(
+    graph: NetworkXGraph,
+    unique_id_name: str = "unique_id",
+    check_uniqueness: bool = True,
+) -> Tuple[NodeCollection, Edges]:  # type: ignore
+    """
+    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 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.
+    """
+    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,
+        check_uniqueness=check_uniqueness,
+    ), Edges(data=edge_keys.join(edge_values))

hiveplotlib-0.26.0rc1/src/hiveplotlib/datasets/__init__.py

@@ -0,0 +1,21 @@
+# datasets.py
+
+"""
+Quick example datasets for use in ``hiveplotlib``.
+
+For Hive Plots, many excellent network datasets are available online, including many graphs that can be generated using
+`networkx <https://networkx.org/documentation/stable/reference/generators.html>`_ and
+`pytorch-geometric <https://pytorch-geometric.readthedocs.io/en/latest/notes/data_cheatsheet.html#>`_.
+The `Stanford Large Network Dataset Collection <https://snap.stanford.edu/data/>`_ is also a great general source of
+network datasets. If working with ``networkx`` graphs,
+users can also take advantage of the ``hiveplotlib.converters.networkx_to_nodes_edges()`` method to quickly get those
+graphs into a ``hiveplotlib``-ready format.
+
+For Polar Parallel Coordinates Plots (P2CPs), many datasets are available through packages including
+`statsmodels <https://www.statsmodels.org/stable/datasets/index.html>`_ and
+`scikit-learn <https://scikit-learn.org/stable/datasets.html>`_.
+"""
+
+from hiveplotlib.datasets.international_trade import *  # noqa: F401, F403
+from hiveplotlib.datasets.toy_hive_plots import *  # noqa: F401, F403
+from hiveplotlib.datasets.toy_p2cps import *  # noqa: F401, F403