hiveplotlib 0.24.0__tar.gz → 0.25.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hiveplotlib
-Version: 0.24.0
+Version: 0.25.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.
@@ -41,14 +41,20 @@ Requires-Dist: pandas
 Provides-Extra: bokeh
 Requires-Dist: bokeh; extra == "bokeh"
 Provides-Extra: datashader
+Requires-Dist: dask[dataframe]; extra == "datashader"
 Requires-Dist: datashader; extra == "datashader"
 Requires-Dist: seaborn; extra == "datashader"
 Provides-Extra: dev
 Requires-Dist: bokeh; extra == "dev"
+Requires-Dist: cartopy; extra == "dev"
 Requires-Dist: datashader; extra == "dev"
+Requires-Dist: geopandas; extra == "dev"
 Requires-Dist: flexitext; extra == "dev"
+Requires-Dist: holoviews; extra == "dev"
 Requires-Dist: jupyter; extra == "dev"
 Requires-Dist: networkx; 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
@@ -56,6 +62,8 @@ Requires-Dist: nbsphinx; extra == "docs"
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: sphinx-rtd-theme; extra == "docs"
 Requires-Dist: toml; extra == "docs"
+Provides-Extra: holoviews
+Requires-Dist: holoviews; extra == "holoviews"
 Provides-Extra: networkx
 Requires-Dist: networkx; extra == "networkx"
 Provides-Extra: plotly
@@ -73,7 +81,13 @@ Requires-Dist: pytest-xdist; extra == "testing"
 
 A plotting package for generating and visualizing static Hive Plots in `matplotlib`.
 
-<br>
+![](https://gitlab.com/geomdata/hiveplotlib/-/raw/22-add-formal-holoviews-support/.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/)
 
 # Installation
 
@@ -89,6 +103,14 @@ To uninstall, run:
 $ pip uninstall hiveplotlib
 ```
 
+By default, `hiveplotlib` supports visualization only with the [matplotlib](https://matplotlib.org/) backend, but
+`hiveplotlib` also supports [bokeh](https://docs.bokeh.org/en/latest/), [holoviews](https://holoviews.org/index.html),
+and [plotly](https://plotly.com/python/) visualizations, which can be installed via `pip install hiveplotlib[bokeh]`,
+`pip install hiveplotlib[holoviews]`, and `pip install hiveplotlib[plotly]`, respectively.
+
+`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)

{hiveplotlib-0.24.0 → hiveplotlib-0.25.0}/README.md

@@ -2,7 +2,13 @@
 
 A plotting package for generating and visualizing static Hive Plots in `matplotlib`.
 
-<br>
+![](https://gitlab.com/geomdata/hiveplotlib/-/raw/22-add-formal-holoviews-support/.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/)
 
 # Installation
 
@@ -18,6 +24,14 @@ To uninstall, run:
 $ pip uninstall hiveplotlib
 ```
 
+By default, `hiveplotlib` supports visualization only with the [matplotlib](https://matplotlib.org/) backend, but
+`hiveplotlib` also supports [bokeh](https://docs.bokeh.org/en/latest/), [holoviews](https://holoviews.org/index.html),
+and [plotly](https://plotly.com/python/) visualizations, which can be installed via `pip install hiveplotlib[bokeh]`,
+`pip install hiveplotlib[holoviews]`, and `pip install hiveplotlib[plotly]`, respectively.
+
+`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)

{hiveplotlib-0.24.0 → hiveplotlib-0.25.0}/pyproject.toml

@@ -1,13 +1,12 @@
 [build-system]
 requires = [
     "setuptools",
-    "wheel"
 ]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "hiveplotlib"
-version = "0.24.0"
+version = "0.25.0"
 authors = [
     {name="Gary Koplik", email="gary.koplik@geomdata.com"}
 ]
@@ -30,6 +29,7 @@ bokeh = [
 ]
 
 datashader = [
+    "dask[dataframe]",  # https://github.com/holoviz/datashader/issues/1319
     "datashader",
     "seaborn"
 ]
@@ -37,10 +37,15 @@ datashader = [
 # developer dependencies
 dev = [
     "bokeh",
+    "cartopy",
     "datashader",
+    "geopandas",
     "flexitext",
+    "holoviews",
     "jupyter",
     "networkx",
+    "plotly",
+    "pybadges",
     "seaborn",
     "tqdm",
 ]
@@ -53,6 +58,10 @@ docs = [
     "toml"
 ]
 
+holoviews = [
+    "holoviews"
+]
+
 networkx = [
     "networkx"
 ]
@@ -98,11 +107,11 @@ 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)
+    "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.
+    "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
 ]

{hiveplotlib-0.24.0 → hiveplotlib-0.25.0}/src/hiveplotlib/converters.py

@@ -4,7 +4,6 @@
 Converters from various data structures to ``hiveplotlib``-ready structures.
 """
 
-
 from typing import List, Tuple
 
 import numpy as np

{hiveplotlib-0.24.0 → hiveplotlib-0.25.0}/src/hiveplotlib/datasets/__init__.py

@@ -23,7 +23,7 @@ from typing import Dict, Hashable, List, Optional, Tuple, Union
 import numpy as np
 import pandas as pd
 
-from hiveplotlib import HivePlot, Node, hive_plot_n_axes
+from hiveplotlib import P2CP, HivePlot, Node, hive_plot_n_axes, p2cp_n_axes
 from hiveplotlib.node import dataframe_to_node_list
 
 
@@ -163,7 +163,7 @@ def example_hive_plot(
     :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.hive_plot_n_axes()` call.
+        :py:func:`hiveplotlib.hive_plot_n_axes()` call.
     :return: resulting ``HivePlot`` instance.
     """
     color_dict = {
@@ -266,3 +266,52 @@ def example_nodes_and_edges(
     edges = rng.choice(node_ids, size=num_edges * 2).reshape(-1, 2)
 
     return node_list, node_ids_per_axis, edges
+
+
+def example_p2cp(
+    num_points: int = 50,
+    noise: float = 0.5,
+    random_seed: int = 0,
+    four_colors: Tuple[str, str, str, str] = (
+        "#de8f05",
+        "#029e73",
+        "#cc78bc",
+        "#0173b2",
+    ),
+    **p2cp_n_axes_kwargs,
+) -> P2CP:
+    """
+    Generate example P2CP of four gaussian blobs.
+
+    Points will be generated by calling :py:func:`hiveplotlib.datasets.four_gaussian_blobs_3d()` and turned into a P2CP
+    via :py:func:`hiveplotlib.p2cp_n_axes()`.
+
+    :param num_points: number of points in each Gaussian blob.
+    :param noise: noisiness of Gaussian blobs.
+    :param random_seed: random seed to generate consistent data between calls.
+    :param four_colors: four colors to use for four Gaussian blobs.
+    :param p2cp_n_axes_kwargs: additional keyword arguments for the underlying
+        :py:func:`hiveplotlib.p2cp_n_axes()` call.
+    :return: resulting ``P2CP`` instance.
+    """
+    # color palette for the blobs
+    df = four_gaussian_blobs_3d(
+        num_points=num_points,
+        noise=noise,
+        random_seed=random_seed,
+    )
+
+    # the first (0) blob needs to be plotted last, so let's give it the last label for pandas to sort to plot last
+    df.loc[df["Label"] == 0, "Label"] = 4
+
+    # align the colors with the figure from the paper
+    indices_dict = [{"color": color} for color in four_colors]
+
+    return p2cp_n_axes(
+        data=df,
+        split_on="Label",
+        vmins=[-1] * 3,
+        vmaxes=[6] * 3,
+        indices_list_kwargs=indices_dict,
+        **p2cp_n_axes_kwargs,
+    )

hiveplotlib-0.25.0/src/hiveplotlib/viz/base.py

@@ -0,0 +1,165 @@
+# base.py
+
+"""
+Base (viz back-end-agnostic) functionality for visualizations in ``hiveplotlib``.
+"""
+
+import warnings
+from typing import Hashable, List, Literal, Tuple
+
+from hiveplotlib import Axis, HivePlot
+
+
+def get_axis_label_alignment(
+    axis: Axis,
+    backend: Literal["matplotlib", "bokeh", "holoviews", "plotly"],
+    horizontal_angle_span: float = 60,
+    vertical_angle_span: float = 60,
+) -> Tuple[Literal["bottom", "middle", "top"], Literal["left", "center", "right"]]:
+    """
+    Generate appropriate horizontal and vertical alignment for text at the radial end point of an ``Axis`` instance.
+
+    ``horizontal_angle_span`` and ``vertical_angle_span`` dictate the text alignment partition, measured in degrees. See
+    the below parameter descriptions for how each value is used to partition the angle space.
+
+    :param axis: ``Axis`` for which to generate the appropriate text alignment.
+    :param backend: which plotting back end to use. (Different back ends have different string names for their
+        alignment options.)
+    :param horizontal_angle_span: ``[-horizontal_angle_span, horizontal_angle_span]`` will be ``"left"`` aligned.
+        ``[180 - horizontal_angle_span, 180 + horizontal_angle_span]`` will be ``right`` aligned, and all other angles
+        will be ``"center"`` aligned.
+    :param vertical_angle_span: ``[90 - vertical_angle_span, 90 + vertical_angle_span]`` will be ``"bottom"`` aligned.
+        ``[270 - vertical_angle_span, 270 + vertical_angle_span]`` will be ``top`` aligned, and all other angles
+        will be ``"middle"`` aligned.
+    :return: vertical alignment string and horizontal alignment string appropriate for the edge of the provided
+        ``Axis`` instance.
+    """
+    horizontal_alignment_dict = {"left": "left", "center": "center", "right": "right"}
+    vertical_alignment_dict = {"bottom": "bottom", "middle": "middle", "top": "top"}
+
+    # matplotlib and holoviews have different naming convention than default
+    if backend in ["matplotlib", "holoviews"]:
+        vertical_alignment_dict["middle"] = "center"
+
+    # range in each direction from 0, 180 to specify horizontal alignment
+    if (
+        axis.angle >= 360 - horizontal_angle_span
+        or axis.angle <= 0 + horizontal_angle_span
+    ):
+        horizontalalignment = horizontal_alignment_dict["left"]
+    elif 180 + horizontal_angle_span >= axis.angle >= 180 - horizontal_angle_span:
+        horizontalalignment = horizontal_alignment_dict["right"]
+    else:
+        horizontalalignment = horizontal_alignment_dict["center"]
+
+    # range in each direction from 90, 270 to specify vertical alignment
+    if 90 + vertical_angle_span >= axis.angle >= 90 - vertical_angle_span:
+        verticalalignment = vertical_alignment_dict["bottom"]
+    elif 270 - vertical_angle_span <= axis.angle <= 270 + vertical_angle_span:
+        verticalalignment = vertical_alignment_dict["top"]
+    else:
+        verticalalignment = vertical_alignment_dict["middle"]
+
+    return verticalalignment, horizontalalignment
+
+
+def edge_viz_preparation(
+    hive_plot: HivePlot,
+    name: Literal["Hive Plot", "P2CP"],
+    from_axis: Hashable,
+    to_axis: Hashable,
+    tag: Hashable,
+    already_warned_p2cp_tags: List[Hashable],
+    edge_kwargs: dict,
+    line_width_name: str,
+    line_alpha_name: str,
+    line_color_name: str,
+    default_line_width: float = 1.5,
+    default_line_alpha: float = 0.5,
+    default_line_color: str = "black",
+    include_line_alpha: bool = True,
+    include_line_width: bool = True,
+) -> Tuple[dict, List[Hashable]]:
+    """
+    Warning checks and keyword argument tracking specifically for ``edge_viz()`` for a subset of edges to plot.
+
+    This code is abstracted to ``hiveplotlib.viz.base`` to avoid redundancy for the ``edge_viz()`` calls with the
+    various back ends, but this function not intended for use outside of within ``edge_viz()``.
+
+    :param hive_plot: underlying hive plot to plot. Should never provide a ``P2CP`` instance here.
+    :param name: "Hive Plot" or "P2CP" being plotted (this affects which warning checks to perform).
+    :param from_axis: the "from" axis of edges currently being prepared for viz.
+    :param to_axis: the "to" axis of edges currently being prepared for viz.
+    :param tag: which tag of edges we are plotting.
+    :param already_warned_p2cp_tags: which tags we've already warned about (this avoids repeated warnings when plotting
+        ill-specified P2CPs).
+    :param edge_kwargs: user-provided edge kwargs to an ``edge_viz()`` call.
+    :param line_width_name: name of line width for viz back end.
+    :param line_alpha_name: name of line alpha for viz back end.
+    :param line_color_name: name of line color for viz back end.
+    :param default_line_width: default line width value.
+    :param default_line_alpha: default line alpha value.
+    :param default_line_color: default line color value.
+    :param include_line_alpha: whether to include the line alpha parameter or not. (We always want line alpha, but the
+        ``plotly`` back end requires including line alpha via the RGBA value, as standalone line alpha is not supported
+        for lines in ``plotly``.)
+    :param include_line_width: whether to include the line width parameter or not. (All viz back ends have a line width,
+        but the historical ``matplotlib`` implementation did not set a default width, which we will preserve going
+        forward.)
+    :return: dictionary of the resulting kwargs for the given edges being plotted and a list of P2CP tags that have been
+        warned about (the provided ``tag`` will be added if the provided P2CP is ill-specified).
+    """
+    temp_edge_kwargs = edge_kwargs.copy()
+
+    # only run plotting of edges that exist
+    if "curves" in hive_plot.edges[from_axis][to_axis][tag]:
+        # create edge_kwargs key if needed
+        if "edge_kwargs" not in hive_plot.edges[from_axis][to_axis][tag]:
+            hive_plot.edges[from_axis][to_axis][tag]["edge_kwargs"] = {}
+
+        # don't use kwargs specified in this function call if already specified
+        for k in list(temp_edge_kwargs.keys()):
+            if k in hive_plot.edges[from_axis][to_axis][tag]["edge_kwargs"]:
+                if name == "Hive Plot":
+                    warnings.warn(
+                        f"Specified kwarg {k} but already set as kwarg for edge tag {tag} "
+                        f"going from edges {from_axis} to {to_axis}. Preserving kwargs already set.\n"
+                        "(These kwargs can be changed using the `add_edge_kwargs()` method "
+                        "for your `HivePlot` instance)",
+                        stacklevel=3,
+                    )
+                # only warn once per tag over all axes
+                elif name == "P2CP" and tag not in already_warned_p2cp_tags:
+                    warnings.warn(
+                        f"Specified kwarg {k} but already set as kwarg for edge tag {tag}. "
+                        f"Preserving kwargs already set.\n"
+                        "(These kwargs can be changed using the `add_edge_kwargs()` method "
+                        "for your `P2CP` instance)",
+                        stacklevel=3,
+                    )
+                    already_warned_p2cp_tags.append(tag)
+                del temp_edge_kwargs[k]
+
+        # some default kwargs for the axes if not specified anywhere
+        if (
+            line_color_name
+            not in hive_plot.edges[from_axis][to_axis][tag]["edge_kwargs"]
+            and line_color_name not in temp_edge_kwargs
+        ):
+            temp_edge_kwargs[line_color_name] = default_line_color
+        if (
+            line_alpha_name
+            not in hive_plot.edges[from_axis][to_axis][tag]["edge_kwargs"]
+            and line_alpha_name not in temp_edge_kwargs
+            and include_line_alpha
+        ):
+            temp_edge_kwargs[line_alpha_name] = default_line_alpha
+        if (
+            line_width_name
+            not in hive_plot.edges[from_axis][to_axis][tag]["edge_kwargs"]
+            and line_width_name not in temp_edge_kwargs
+            and include_line_width
+        ):
+            temp_edge_kwargs[line_width_name] = default_line_width
+
+    return temp_edge_kwargs, already_warned_p2cp_tags

{hiveplotlib-0.24.0 → hiveplotlib-0.25.0}/src/hiveplotlib/viz/bokeh.py

@@ -12,14 +12,13 @@ except ImportError:  # pragma: no cover
         "bokeh not installed, but can be installed by running `pip install hiveplotlib[bokeh]`"
     )
 
-import warnings
 from typing import Hashable, List, Optional, Union
 
 import numpy as np
 
 from hiveplotlib import P2CP, HivePlot
 from hiveplotlib.utils import polar2cartesian
-from hiveplotlib.viz.base import get_axis_label_alignment
+from hiveplotlib.viz.base import edge_viz_preparation, get_axis_label_alignment
 from hiveplotlib.viz.input_checks import input_check
 
 
@@ -384,54 +383,21 @@ def edge_viz(
             )
 
             for tag in tags_to_plot:
-                temp_edge_kwargs = edge_kwargs.copy()
+                temp_edge_kwargs, already_warned_p2cp_tags = edge_viz_preparation(
+                    hive_plot=hive_plot,
+                    name=name,
+                    from_axis=a0,
+                    to_axis=a1,
+                    tag=tag,
+                    already_warned_p2cp_tags=already_warned_p2cp_tags,
+                    edge_kwargs=edge_kwargs,
+                    line_width_name="line_width",
+                    line_alpha_name="alpha",
+                    line_color_name="color",
+                )
 
                 # only run plotting of edges that exist
                 if "curves" in hive_plot.edges[a0][a1][tag]:
-                    # create edge_kwargs key if needed
-                    if "edge_kwargs" not in hive_plot.edges[a0][a1][tag]:
-                        hive_plot.edges[a0][a1][tag]["edge_kwargs"] = {}
-
-                    # don't use kwargs specified in this function call if already specified
-                    for k in list(temp_edge_kwargs.keys()):
-                        if k in hive_plot.edges[a0][a1][tag]["edge_kwargs"]:
-                            if name == "Hive Plot":
-                                warnings.warn(
-                                    f"Specified kwarg {k} but already set as kwarg for edge tag {tag} "
-                                    f"going from edges {a0} to {a1}. Preserving kwargs already set.\n"
-                                    "(These kwargs can be changed using the `add_edge_kwargs()` method "
-                                    "for your `HivePlot` instance)",
-                                    stacklevel=2,
-                                )
-                            # only warn once per tag over all axes
-                            elif name == "P2CP" and tag not in already_warned_p2cp_tags:
-                                warnings.warn(
-                                    f"Specified kwarg {k} but already set as kwarg for edge tag {tag}. "
-                                    f"Preserving kwargs already set.\n"
-                                    "(These kwargs can be changed using the `add_edge_kwargs()` method "
-                                    "for your `P2CP` instance)",
-                                    stacklevel=2,
-                                )
-                                already_warned_p2cp_tags.append(tag)
-                            del temp_edge_kwargs[k]
-
-                    # some default kwargs for the axes if not specified anywhere
-                    if (
-                        "color" not in hive_plot.edges[a0][a1][tag]["edge_kwargs"]
-                        and "color" not in temp_edge_kwargs
-                    ):
-                        temp_edge_kwargs["color"] = "black"
-                    if (
-                        "alpha" not in hive_plot.edges[a0][a1][tag]["edge_kwargs"]
-                        and "alpha" not in temp_edge_kwargs
-                    ):
-                        temp_edge_kwargs["alpha"] = 0.5
-                    if (
-                        "line_width" not in hive_plot.edges[a0][a1][tag]["edge_kwargs"]
-                        and "line_width" not in temp_edge_kwargs
-                    ):
-                        temp_edge_kwargs["line_width"] = 1.5
-
                     # grab the requested array of discretized curves
                     edge_arr = hive_plot.edges[a0][a1][tag]["curves"]
                     # if there's no actual edges there, don't plot
@@ -545,7 +511,7 @@ def hive_plot_viz(
         **axes_kwargs,
     )
 
-    # do the centering / redim-ing if requested only before the last call, otherwise it will be overridden
+    # do the centering / redim-ing if requested only on the last call, otherwise it will be overridden
     node_viz(
         instance=hive_plot,
         fig=fig,
@@ -644,7 +610,7 @@ def p2cp_viz(
         **axes_kwargs,
     )
 
-    # do the centering / redim-ing if requested only before the last call, otherwise it will be overridden
+    # do the centering / redim-ing if requested only on the last call, otherwise it will be overridden
     node_viz(
         instance=p2cp,
         fig=fig,