hiveplotlib 0.25.0__tar.gz → 0.26.0__tar.gz

{hiveplotlib-0.25.0 → hiveplotlib-0.26.0}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2020 - 2023, Geometric Data Analytics, Inc.
+Copyright (c) 2020 - 2024, Geometric Data Analytics, Inc.
 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 Anaconda nor the names of any contributors
+Neither the name of Geometric Data Analytics nor the names of any contributors
 may be used to endorse or promote products derived from this software
 without specific prior written permission.
 
@@ -25,4 +25,4 @@ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
-THE POSSIBILITY OF SUCH DAMAGE.
+THE POSSIBILITY OF SUCH DAMAGE.

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

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: hiveplotlib
-Version: 0.25.0
+Version: 0.26.0
 Summary: Visualize Network Data with Hive Plots
 Author-email: Gary Koplik <gary.koplik@geomdata.com>
-License: Copyright (c) 2020 - 2023, Geometric Data Analytics, Inc.
+License: Copyright (c) 2020 - 2024, Geometric Data Analytics, Inc.
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without modification,
@@ -16,7 +16,7 @@ License: Copyright (c) 2020 - 2023, 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 Anaconda nor the names of any contributors
+        Neither the name of Geometric Data Analytics nor the names of any contributors
         may be used to endorse or promote products derived from this software
         without specific prior written permission.
         
@@ -31,8 +31,10 @@ License: Copyright (c) 2020 - 2023, Geometric Data Analytics, Inc.
         CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
         ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
         THE POSSIBILITY OF SUCH DAMAGE.
+        
 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
@@ -43,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
@@ -76,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 `matplotlib`.
+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
@@ -111,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:
 
@@ -146,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.0 → hiveplotlib-0.26.0}/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 `matplotlib`.
+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.0 → hiveplotlib-0.26.0}/pyproject.toml

@@ -6,7 +6,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hiveplotlib"
-version = "0.25.0"
+requires-python = ">=3.9"
+version = "0.26.0"
 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.0/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.0 → hiveplotlib-0.26.0}/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.0/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))