hiveplotlib 0.23.0__tar.gz → 0.25.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hiveplotlib
-Version: 0.23.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.
@@ -31,7 +31,7 @@ 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://geomdata.gitlab.io/hiveplotlib/
+Project-URL: Documentation, https://hiveplotlib.readthedocs.io/stable/
 Project-URL: Source, https://gitlab.com/geomdata/hiveplotlib
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -41,13 +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
@@ -55,25 +62,32 @@ 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
 Requires-Dist: plotly; extra == "plotly"
+Provides-Extra: ruff
+Requires-Dist: ruff; extra == "ruff"
 Provides-Extra: testing
-Requires-Dist: black[jupyter]; extra == "testing"
-Requires-Dist: flake8-docstrings; extra == "testing"
-Requires-Dist: Flake8-pyproject; extra == "testing"
 Requires-Dist: pytest; extra == "testing"
 Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: pytest-html; extra == "testing"
 Requires-Dist: pytest-timeout; extra == "testing"
 Requires-Dist: pytest-xdist; extra == "testing"
 
-![](https://geomdata.gitlab.io/hiveplotlib/_static/hiveplotlib.svg)
+![](https://hiveplotlib.readthedocs.io/stable/_static/hiveplotlib.svg)
 
 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)
@@ -96,7 +118,7 @@ For more on contributing to the project, see [CONTRIBUTING.md](https://gitlab.co
 # How to Use and Examples
 
 For more on how to use the software and examples, see the
-[docs](https://geomdata.gitlab.io/hiveplotlib/index.html).
+[docs](https://hiveplotlib.readthedocs.io/stable/index.html).
 
 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.
@@ -114,7 +136,7 @@ $ bash install.sh
 # More on Hive Plots
 
 For more on Hive Plots, see our
-[Introduction to Hive Plots](https://geomdata.gitlab.io/hiveplotlib/introduction_to_hive_plots.html).
+[Introduction to Hive Plots](https://hiveplotlib.readthedocs.io/stable/introduction_to_hive_plots.html).
 
 For additional resources, see:
 

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

@@ -1,8 +1,14 @@
-![](https://geomdata.gitlab.io/hiveplotlib/_static/hiveplotlib.svg)
+![](https://hiveplotlib.readthedocs.io/stable/_static/hiveplotlib.svg)
 
 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)
@@ -25,7 +39,7 @@ For more on contributing to the project, see [CONTRIBUTING.md](https://gitlab.co
 # How to Use and Examples
 
 For more on how to use the software and examples, see the
-[docs](https://geomdata.gitlab.io/hiveplotlib/index.html).
+[docs](https://hiveplotlib.readthedocs.io/stable/index.html).
 
 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.
@@ -43,7 +57,7 @@ $ bash install.sh
 # More on Hive Plots
 
 For more on Hive Plots, see our
-[Introduction to Hive Plots](https://geomdata.gitlab.io/hiveplotlib/introduction_to_hive_plots.html).
+[Introduction to Hive Plots](https://hiveplotlib.readthedocs.io/stable/introduction_to_hive_plots.html).
 
 For additional resources, see:
 

hiveplotlib-0.25.0/pyproject.toml

@@ -0,0 +1,156 @@
+[build-system]
+requires = [
+    "setuptools",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hiveplotlib"
+version = "0.25.0"
+authors = [
+    {name="Gary Koplik", email="gary.koplik@geomdata.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" }
+
+
+dependencies = [
+    "matplotlib",
+    "numpy",
+    "pandas"
+]
+
+[project.optional-dependencies]
+
+bokeh = [
+    "bokeh"
+]
+
+datashader = [
+    "dask[dataframe]",  # https://github.com/holoviz/datashader/issues/1319
+    "datashader",
+    "seaborn"
+]
+
+# developer dependencies
+dev = [
+    "bokeh",
+    "cartopy",
+    "datashader",
+    "geopandas",
+    "flexitext",
+    "holoviews",
+    "jupyter",
+    "networkx",
+    "plotly",
+    "pybadges",
+    "seaborn",
+    "tqdm",
+]
+
+# for building documentation
+docs = [
+    "nbsphinx",
+    "sphinx",
+    "sphinx-rtd-theme",
+    "toml"
+]
+
+holoviews = [
+    "holoviews"
+]
+
+networkx = [
+    "networkx"
+]
+
+plotly = [
+    "plotly"
+]
+
+# ruff code hygeine checks
+ruff = [
+    "ruff" 
+]
+
+testing = [
+    "pytest",
+    "pytest-cov",
+    "pytest-html",
+    "pytest-timeout",
+    "pytest-xdist"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["hiveplotlib*"]
+
+[tool.ruff]
+# ruff performs our linting and formatting.
+# if you receive an error you don't understand, you can run `ruff rule <error code>` to learn more.
+# the full list of ruff rules are here: https://docs.astral.sh/ruff/rules/
+extend-include = ["*.ipynb", "*.pyi"]
+
+# Add files here to be completely skipped by ruff.
+extend-exclude = [
+    "docs",
+    "sandbox"
+]
+
+line-length = 88
+indent-width = 4
+
+output-format = "full"
+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
+]
+
+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)
+    "C4",  # use flake8-comprehensions (remove unnecessary literals, generators, lists, etc.) 
+    "D",  # use pydoc style rules
+    "E",  # use pycodestyle warnings
+    "I",  # use isort rules
+    "ICN",  # use flake-import-conventions (checks that imports use standard names)
+    "N",  # use pep8 naming
+    "NPY",  # numpy-specific rules
+    "PERF",  # linter focused on avoiding performance anti-patterns
+    "PIE",  # use flake8-pie (some misc additional linting)
+    "PD",  # write pandas code more in line with pd recommendations
+    "PT",  # use flake8-pytest-style (linting specifically for pytest)
+    "RET",  # use flake8-return (linting on return / raise)
+    "SIM",  # use flake8-simplify (helps simplify logic in code)
+    "TID",  # use flake8-tidy-imports (to prevent relative imports)
+    "W",  # use pycodestyle warnings
+] 
+
+[tool.ruff.lint.pycodestyle]
+# allow docstrings to go longer
+max-line-length = 120
+
+[tool.ruff.format]
+# like Black, use double quotes for strings.
+quote-style = "double"
+
+# like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+
+# like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+
+# like Black, automatically detect the appropriate line ending.
+line-ending = "auto"

{hiveplotlib-0.23.0 → hiveplotlib-0.25.0}/setup.py

@@ -1,3 +1,7 @@
+"""
+Setup.
+"""
+
 import setuptools
 
 if __name__ == "__main__":

{hiveplotlib-0.23.0 → hiveplotlib-0.25.0}/src/hiveplotlib/axis.py

@@ -4,10 +4,12 @@
 Definition of ``Axis`` instance and helper static methods for generating and working with ``Axis`` instances.
 """
 
-from hiveplotlib.utils import polar2cartesian
+from typing import Hashable, List, Optional
+
 import numpy as np
 import pandas as pd
-from typing import Hashable, List, Optional
+
+from hiveplotlib.utils import polar2cartesian
 
 
 class Axis:
@@ -56,7 +58,7 @@ class Axis:
         end: float = 5,
         angle: float = 0,
         long_name: Optional[Hashable] = None,
-    ):
+    ) -> None:
         """
         Initialize ``Axis`` object with start and end positions and angle. Default to axis normalized on [0, 1].
 
@@ -99,7 +101,7 @@ class Axis:
 
     def _set_node_placements(
         self, x: List[float], y: List[float], node_ids: List[Hashable], rho: List[float]
-    ):
+    ) -> None:
         """
         Set ``Axis.node_placements`` to a ``pandas.DataFrame``.
 
@@ -127,9 +129,7 @@ class Axis:
             {"x": x, "y": y, "unique_id": node_ids, "rho": rho}
         )
 
-        return None
-
-    def _set_node_placement_label(self, label: Hashable):
+    def _set_node_placement_label(self, label: Hashable) -> None:
         """
         Set which scalar variable in each ``Node`` instance will be used to place each node on the axis when plotting.
 
@@ -141,5 +141,3 @@ class Axis:
         :return: ``None``.
         """
         self.node_placement_label = label
-
-        return None

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

@@ -4,16 +4,17 @@
 Converters from various data structures to ``hiveplotlib``-ready structures.
 """
 
+from typing import List, Tuple
 
-from hiveplotlib import Node
 import numpy as np
-from typing import List, Tuple
+
+from hiveplotlib import Node
 
 # 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) -> Tuple[List[Node], np.ndarray]:
+def networkx_to_nodes_edges(graph: NetworkXGraph) -> Tuple[List[Node], np.ndarray]:  # type: ignore
     """
     Take a ``networkx`` graph and return ``hiveplotlib``-friendly data structures.
 

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

@@ -17,11 +17,14 @@ For Polar Parallel Coordinates Plots (P2CPs), many datasets are available throug
 """
 
 import json
+from pathlib import Path
+from typing import Dict, Hashable, List, Optional, Tuple, Union
+
 import numpy as np
-from hiveplotlib import hive_plot_n_axes, HivePlot, Node
 import pandas as pd
-from pathlib import Path
-from typing import Dict, Optional, Tuple, Union
+
+from hiveplotlib import P2CP, HivePlot, Node, hive_plot_n_axes, p2cp_n_axes
+from hiveplotlib.node import dataframe_to_node_list
 
 
 def international_trade_data(
@@ -57,10 +60,7 @@ def international_trade_data(
     # path when grabbing files shipped with hiveplotlib
     internal_path = Path(__path__[0]).joinpath("trade_data_harvard_growth_lab")
 
-    if path is None:
-        path = internal_path
-    else:
-        path = Path(path)
+    path = internal_path if path is None else Path(path)
 
     # grab the shipped year, hs92 values to present what's available on failure
     csv_files = [
@@ -77,12 +77,14 @@ def international_trade_data(
     metadata_path = path.joinpath(
         f"international_exports_metadata_{year}_{hs92_code}.json"
     )
-    assert data_path.exists() and metadata_path.exists(), (
-        f"Could not find data and / or metadata under specified `path`. If you specified your own path, double check "
-        f"that the path is correct. Your file names should be "
-        f"If you are using `hiveplotlib` supported data, note that only the following `year`, "
-        f"`hs29_code` values are supported:\n{hiveplotlib_supported_values}"
-    )
+
+    if not (data_path.exists() and metadata_path.exists()):
+        raise ValueError(
+            "Could not find data and / or metadata under specified `path`. If you specified your own path, double "
+            "check that the path is correct. Your file names should be "
+            "If you are using `hiveplotlib` supported data, note that only the following `year`, "
+            f"`hs29_code` values are supported:\n{hiveplotlib_supported_values}"
+        )
 
     data = pd.read_csv(data_path)
     with open(metadata_path, "r") as openfile:
@@ -141,7 +143,7 @@ def four_gaussian_blobs_3d(
     # make the labels ints
     df.Label = df.Label.astype(int)
     # replace the 4s with 3s so our labels are just range(4)
-    df.Label.values[df.Label.values == 4] = 3
+    df.Label.to_numpy()[df.Label.to_numpy() == 4] = 3
 
     return df
 
@@ -161,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 = {
@@ -187,7 +189,7 @@ def example_hive_plot(
     node_data = data.to_dict(orient="records")
 
     # use the dataframe's index as unique id
-    node_ids = data.index.values
+    node_ids = data.index.to_numpy()
 
     nodes = [
         Node(unique_id=node_id, data=node_data[i]) for i, node_id in enumerate(node_ids)
@@ -217,3 +219,99 @@ def example_hive_plot(
             hp.add_edge_kwargs(axis_id_1=e1, axis_id_2=e2, color=color_dict[e1][e2])
 
     return hp
+
+
+def example_nodes_and_edges(
+    num_nodes: int = 100,
+    num_edges: int = 200,
+    num_axes: int = 3,
+    seed: int = 0,
+) -> Tuple[List[Node], List[List[Hashable]], np.ndarray]:
+    """
+    Generate example nodes, node splits (one list of nodes per intended axis), and edges.
+
+    Each node will have a ``"low"``, ``"med"``, and ``"high"`` value, where these values are randomly generated, and as
+    the names suggest, for the resulting values of each node, ``"low"`` < ``"med"`` < ``"high"``.
+
+    :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 edges to randomly generate.
+    :param num_axes: how many axes into which to partition the randomly generated nodes.
+    :param seed: random seed to use when randomly generating node and edge data.
+    :return: list of generated ``Node`` instances, a list of ``num_axes`` lists that evenly split the node IDs to be
+        allocated to their own axes, and a ``(num_edges, 2)`` shaped array of random edges between nodes.
+    """
+    rng = np.random.default_rng(seed)
+
+    # example data
+    data = pd.DataFrame(
+        np.c_[
+            rng.uniform(low=0, high=9.99, size=num_nodes),
+            rng.uniform(low=10, high=19.99, size=num_nodes),
+            rng.uniform(low=20, high=29.99, size=num_nodes),
+        ],
+        columns=["low", "med", "high"],
+    )
+    # make indices a column
+    data = data.reset_index()
+
+    node_list = dataframe_to_node_list(data, unique_id_column="index")
+    node_ids = data["index"].to_numpy()
+
+    # split node allocation equally among planned axes
+    node_ids_per_axis = np.split(node_ids, num_axes)
+    # coax to list of lists
+    node_ids_per_axis = [i.tolist() for i in node_ids_per_axis]
+
+    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,
+    )