neo4j-viz 0.7.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

neo4j_viz/visualization_graph.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import warnings
-from collections.abc import Iterable
-from typing import Any, Callable, Hashable, Optional, Union
+from collections.abc import Hashable, Iterable
+from typing import Any, Callable
 
 from IPython.display import HTML
 from pydantic.alias_generators import to_snake
@@ -22,7 +22,6 @@ from .options import (
 from .relationship import Relationship
 
 
-# TODO helper for map properties to fields. helper for set caption (simplicity)
 class VisualizationGraph:
     """
     A graph to visualize.
@@ -86,13 +85,13 @@ class VisualizationGraph:
 
     def render(
         self,
-        layout: Optional[Layout] = None,
-        layout_options: Union[dict[str, Any], LayoutOptions, None] = None,
+        layout: Layout | None = None,
+        layout_options: dict[str, Any] | LayoutOptions | None = None,
         renderer: Renderer = Renderer.CANVAS,
         width: str = "100%",
         height: str = "600px",
-        pan_position: Optional[tuple[float, float]] = None,
-        initial_zoom: Optional[float] = None,
+        pan_position: tuple[float, float] | None = None,
+        initial_zoom: float | None = None,
         min_zoom: float = 0.075,
         max_zoom: float = 10,
         allow_dynamic_min_zoom: bool = True,
@@ -197,8 +196,8 @@ class VisualizationGraph:
     def set_node_captions(
         self,
         *,
-        field: Optional[str] = None,
-        property: Optional[str] = None,
+        field: str | None = None,
+        property: str | None = None,
         override: bool = True,
     ) -> None:
         """
@@ -265,9 +264,9 @@ class VisualizationGraph:
 
     def resize_nodes(
         self,
-        sizes: Optional[dict[NodeIdType, RealNumber]] = None,
-        node_radius_min_max: Optional[tuple[RealNumber, RealNumber]] = (3, 60),
-        property: Optional[str] = None,
+        sizes: dict[NodeIdType, RealNumber] | None = None,
+        node_radius_min_max: tuple[RealNumber, RealNumber] | None = (3, 60),
+        property: str | None = None,
     ) -> None:
         """
         Resize the nodes in the graph.
@@ -334,6 +333,57 @@ class VisualizationGraph:
 
             node.size = size
 
+    def resize_relationships(
+        self,
+        widths: dict[str | int, RealNumber] | None = None,
+        property: str | None = None,
+    ) -> None:
+        """
+        Resize the width of relationships in the graph.
+
+        Parameters
+        ----------
+        widths:
+            A dictionary mapping from relationship ID to the new width of the relationship.
+            If a relationship ID is not in the dictionary, the width of the relationship is not changed.
+            Must be None if `property` is provided.
+        property:
+            The property of the relationships to use for sizing. Must be None if `widths` is provided.
+        """
+        if widths is not None and property is not None:
+            raise ValueError("At most one of the arguments `widths` and `property` can be provided")
+
+        if widths is None and property is None:
+            raise ValueError("At least one of `widths` or `property` must be given")
+
+        # Gather relationship widths
+        all_widths = {}
+        if widths is not None:
+            for rel in self.relationships:
+                width = widths.get(rel.id, rel.width)
+                if width is not None:
+                    all_widths[rel.id] = width
+        elif property is not None:
+            for rel in self.relationships:
+                width = rel.properties.get(property, rel.width)
+                if width is not None:
+                    all_widths[rel.id] = width
+
+        # Validate and apply relationship widths
+        for rel in self.relationships:
+            width = all_widths.get(rel.id)
+
+            if width is None:
+                continue
+
+            if not isinstance(width, (int, float)):
+                raise ValueError(f"Width for relationship '{rel.id}' must be a real number, but was {width}")
+
+            if width <= 0:
+                raise ValueError(f"Width for relationship '{rel.id}' must be positive, but was {width}")
+
+            rel.width = width
+
     @staticmethod
     def _normalize_values(
         node_map: dict[NodeIdType, RealNumber], min_max: tuple[float, float] = (0, 1)
@@ -359,9 +409,9 @@ class VisualizationGraph:
     def color_nodes(
         self,
         *,
-        field: Optional[str] = None,
-        property: Optional[str] = None,
-        colors: Optional[ColorsType] = None,
+        field: str | None = None,
+        property: str | None = None,
+        colors: ColorsType | None = None,
         color_space: ColorSpace = ColorSpace.DISCRETE,
         override: bool = True,
     ) -> None:
@@ -406,6 +456,7 @@ class VisualizationGraph:
         >>> VG = VisualizationGraph(nodes=nodes)
 
         Color nodes based on a discrete field such as "label":
+
         >>> VG.color_nodes(field="label", color_space=ColorSpace.DISCRETE)
 
         Color nodes based on a continuous field such as "score":
@@ -428,6 +479,7 @@ class VisualizationGraph:
 
             def node_to_attr(node: Node) -> Any:
                 return node.properties.get(attribute)
+
         else:
             assert field is not None
             attribute = to_snake(field)
@@ -456,39 +508,151 @@ class VisualizationGraph:
             }
 
         if isinstance(colors, dict):
-            self._color_nodes_dict(colors, override, node_to_attr)
+            self._color_items_dict(self.nodes, colors, override, node_to_attr)
         else:
-            self._color_nodes_iter(attribute, colors, override, node_to_attr)
+            self._color_items_iter(self.nodes, attribute, colors, override, node_to_attr)
 
-    def _color_nodes_dict(
-        self, colors: dict[str, ColorType], override: bool, node_to_attr: Callable[[Node], Any]
+    def color_relationships(
+        self,
+        *,
+        field: str | None = None,
+        property: str | None = None,
+        colors: ColorsType | None = None,
+        color_space: ColorSpace = ColorSpace.DISCRETE,
+        override: bool = True,
     ) -> None:
-        for node in self.nodes:
-            color = colors.get(node_to_attr(node))
+        """
+        Color the relationships in the graph based on either a relationship field, or a relationship property.
+
+        It's possible to color the relationships based on a discrete or continuous color space. In the discrete case,
+        a new color from the `colors` provided is assigned to each unique value of the relationship field/property.
+        In the continuous case, the `colors` should be a list of colors representing a range that are used to
+        create a gradient of colors based on the values of the relationship field/property.
+
+        Parameters
+        ----------
+        field:
+            The field of the relationships to base the coloring on. The type of this field must be hashable, or be a
+            list, set or dict containing only hashable types. Must be None if `property` is provided.
+        property:
+            The property of the relationships to base the coloring on. The type of this property must be hashable, or be a
+            list, set or dict containing only hashable types. Must be None if `field` is provided.
+        colors:
+            The colors to use for the relationships.
+            If `color_space` is `ColorSpace.DISCRETE`, the colors can be a dictionary mapping from field/property value
+            to color, or an iterable of colors in which case the colors are used in order.
+            If `color_space` is `ColorSpace.CONTINUOUS`, the colors must be a list of colors representing a range.
+            Allowed color values are for example “#FF0000”, “red” or (255, 0, 0) (full list: https://docs.pydantic.dev/2.0/usage/types/extra_types/color_types/).
+            The default colors are the Neo4j graph colors.
+        color_space:
+            The type of space of the provided `colors`. Either `ColorSpace.DISCRETE` or `ColorSpace.CONTINUOUS`. It determines whether
+            colors are assigned based on unique field/property values or a gradient of the values of the field/property.
+        override:
+            Whether to override existing colors of the relationships, if they have any.
+
+        Examples
+        --------
+
+        Given a VisualizationGraph `VG`:
+
+        >>> nodes = [Node(id="0"), Node(id="1")]
+        >>> relationships = [
+        ...    Relationship(source="0", target="1", caption="ACTED_IN", properties={"score": 10}),
+        ...    Relationship(source="1", target="0", caption="DIRECTED", properties={"score": 20}),
+        ... ]
+        >>> VG = VisualizationGraph(nodes=nodes, relationships=relationships)
+
+        Color relationships based on a discrete field such as "caption":
+
+        >>> VG.color_relationships(field="caption", color_space=ColorSpace.DISCRETE)
+
+        Color relationships based on a continuous field such as "score":
+
+        >>> VG.color_relationships(property="score", color_space=ColorSpace.CONTINUOUS)
+        """
+        if not ((field is None) ^ (property is None)):
+            raise ValueError(
+                f"Exactly one of the arguments `field` (received '{field}') and `property` (received '{property}') must be provided"
+            )
+
+        if field is None:
+            assert property is not None
+            attribute = property
+
+            def rel_to_attr(rel: Relationship) -> Any:
+                return rel.properties.get(attribute)
+
+        else:
+            assert field is not None
+            attribute = to_snake(field)
+
+            def rel_to_attr(rel: Relationship) -> Any:
+                return getattr(rel, attribute)
+
+        if color_space == ColorSpace.DISCRETE:
+            if colors is None:
+                colors = NEO4J_COLORS_DISCRETE
+        else:
+            rel_map = {rel.id: rel_to_attr(rel) for rel in self.relationships if rel_to_attr(rel) is not None}
+            normalized_map = self._normalize_values(rel_map)
+
+            if colors is None:
+                colors = NEO4J_COLORS_CONTINUOUS
+
+            if not isinstance(colors, list):
+                raise ValueError("For continuous properties, `colors` must be a list of colors representing a range")
+
+            num_colors = len(colors)
+            colors = {
+                rel_to_attr(rel): colors[round(normalized_map[rel.id] * (num_colors - 1))]
+                for rel in self.relationships
+                if rel_to_attr(rel) is not None
+            }
+
+        if isinstance(colors, dict):
+            self._color_items_dict(self.relationships, colors, override, rel_to_attr)
+        else:
+            self._color_items_iter(self.relationships, attribute, colors, override, rel_to_attr)
+
+    def _color_items_dict(
+        self,
+        items: list[Node] | list[Relationship],
+        colors: dict[Hashable, ColorType],
+        override: bool,
+        item_to_attr: Callable[[Any], Any],
+    ) -> None:
+        for item in items:
+            color = colors.get(item_to_attr(item))
 
             if color is None:
                 continue
 
-            if node.color is not None and not override:
+            if item.color is not None and not override:
                 continue
 
             if not isinstance(color, Color):
-                node.color = Color(color)
+                item.color = Color(color)
             else:
-                node.color = color
+                item.color = color
 
-    def _color_nodes_iter(
-        self, attribute: str, colors: Iterable[ColorType], override: bool, node_to_attr: Callable[[Node], Any]
+    def _color_items_iter(
+        self,
+        items: list[Node] | list[Relationship],
+        attribute: str,
+        colors: Iterable[ColorType],
+        override: bool,
+        item_to_attr: Callable[[Any], Any],
     ) -> None:
         exhausted_colors = False
         prop_to_color = {}
         colors_iter = iter(colors)
-        for node in self.nodes:
-            raw_prop = node_to_attr(node)
+        for item in items:
+            raw_prop = item_to_attr(item)
             try:
                 prop = self._make_hashable(raw_prop)
             except ValueError:
-                raise ValueError(f"Unable to color nodes by unhashable property type '{type(raw_prop)}'")
+                item_type = "nodes" if isinstance(item, Node) else "relationships"
+                raise ValueError(f"Unable to color {item_type} by unhashable property type '{type(raw_prop)}'")
 
             if prop not in prop_to_color:
                 next_color = next(colors_iter, None)
@@ -500,13 +664,13 @@ class VisualizationGraph:
 
             color = prop_to_color[prop]
 
-            if node.color is not None and not override:
+            if item.color is not None and not override:
                 continue
 
             if not isinstance(color, Color):
-                node.color = Color(color)
+                item.color = Color(color)
             else:
-                node.color = color
+                item.color = color
 
         if exhausted_colors:
             warnings.warn(

{neo4j_viz-0.7.0.dist-info → neo4j_viz-1.1.0.dist-info}/METADATA

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: neo4j-viz
-Version: 0.7.0
+Version: 1.1.0
 Summary: A simple graph visualization tool
 Author-email: Neo4j <team-gds@neo4j.org>
 License-Expression: GPL-3.0-only
 Project-URL: Homepage, https://neo4j.com/
 Project-URL: Repository, https://github.com/neo4j/python-graph-visualization
 Project-URL: Issues, https://github.com/neo4j/python-graph-visualization/issues
-Project-URL: Documentation, https://neo4j.com/docs/nvl-python/preview
+Project-URL: Documentation, https://neo4j.com/docs/python-graph-visualization/
 Keywords: graph,visualization,neo4j
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -32,22 +32,6 @@ Requires-Dist: ipython<10,>=7
 Requires-Dist: pydantic<3,>=2
 Requires-Dist: pydantic-extra-types<3,>=2
 Requires-Dist: enum-tools==0.13.0
-Provides-Extra: dev
-Requires-Dist: ruff==0.14.1; extra == "dev"
-Requires-Dist: mypy==1.18.2; extra == "dev"
-Requires-Dist: pytest==8.4.2; extra == "dev"
-Requires-Dist: selenium==4.32.0; extra == "dev"
-Requires-Dist: ipykernel==6.30.1; extra == "dev"
-Requires-Dist: palettable==3.3.3; extra == "dev"
-Requires-Dist: pytest-mock==3.14.0; extra == "dev"
-Requires-Dist: nbconvert==7.16.6; extra == "dev"
-Requires-Dist: streamlit==1.45.0; extra == "dev"
-Requires-Dist: matplotlib>=3.9.4; extra == "dev"
-Provides-Extra: docs
-Requires-Dist: sphinx==8.1.3; extra == "docs"
-Requires-Dist: enum-tools[sphinx]; extra == "docs"
-Requires-Dist: nbsphinx==0.9.7; extra == "docs"
-Requires-Dist: nbsphinx-link==1.3.1; extra == "docs"
 Provides-Extra: pandas
 Requires-Dist: pandas<3,>=2; extra == "pandas"
 Requires-Dist: pandas-stubs<3,>=2; extra == "pandas"
@@ -57,14 +41,6 @@ Provides-Extra: neo4j
 Requires-Dist: neo4j; extra == "neo4j"
 Provides-Extra: snowflake
 Requires-Dist: snowflake-snowpark-python<2,>=1; extra == "snowflake"
-Provides-Extra: notebook
-Requires-Dist: ipykernel>=6.29.5; extra == "notebook"
-Requires-Dist: pykernel>=0.1.6; extra == "notebook"
-Requires-Dist: neo4j>=5.26.0; extra == "notebook"
-Requires-Dist: ipywidgets>=8.0.0; extra == "notebook"
-Requires-Dist: palettable>=3.3.3; extra == "notebook"
-Requires-Dist: matplotlib>=3.9.4; extra == "notebook"
-Requires-Dist: snowflake-snowpark-python==1.37.0; extra == "notebook"
 Dynamic: license-file
 
 # Graph Visualization for Python by Neo4j
@@ -84,9 +60,6 @@ Alternatively, you can export the output to a file and view it in a web browser.
 
 The package wraps the [Neo4j Visualization JavaScript library (NVL)](https://neo4j.com/docs/nvl/current/).
 
-> [!WARNING]
-> This package is still in development and the API is subject to change.
-
 
 ![Example Graph](https://github.com/neo4j/python-graph-visualization/blob/main/examples/example_cora_graph.png)
 

{neo4j_viz-0.7.0.dist-info → neo4j_viz-1.1.0.dist-info}/RECORD

@@ -7,21 +7,21 @@ neo4j_viz/node.py,sha256=qXjPzsNLksY7yh_Lxe174lOQw0QjHZ9-ka9R9uJpG_A,3843
 neo4j_viz/node_size.py,sha256=c_sMtQSD8eJ_6Y0Kr6ku0LOs9VoEDxfYCUUzUWZ-1Xo,1197
 neo4j_viz/nvl.py,sha256=ZN3tyWar9ugR88r5N6txW3ThfNEWOt5A1KzrrRnLKwk,5262
 neo4j_viz/options.py,sha256=oai-yI03WxWyl6-9cFWEbQkqpXAcI8oG4G6rSVF1Bt0,6495
-neo4j_viz/pandas.py,sha256=gFQW9SlWxiSrVCi2kHGUKpDXDhYtlFkk2AR2DzxYTWE,4759
+neo4j_viz/pandas.py,sha256=Y-td7ZyorXtfRGCiROsjApzFjxkA0DqZvJ0KEWw9Sdw,4921
 neo4j_viz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-neo4j_viz/relationship.py,sha256=aVj8_6umHSm1rg53CU-oci21W845J91AFKv1AJudmD8,4112
+neo4j_viz/relationship.py,sha256=CC2Yycr1LPJh8bZNpAGiQ9wVh7hHpRcMrvpixbPvCu4,4248
 neo4j_viz/snowflake.py,sha256=Md3bW6qaBVnq8A_2fx8POkdbpKQuPc1qNaNzwDvQ8CE,12683
-neo4j_viz/visualization_graph.py,sha256=G4MHAQ_sgVMDqf3gI76l4m8tnFzfW0hM_lrxWFWojVc,19490
+neo4j_viz/visualization_graph.py,sha256=LjhFhyp_zmupbTbWFpQAprKUE68YNjh4Xu0iQL8YRgY,26405
 neo4j_viz/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neo4j_viz/resources/icons/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neo4j_viz/resources/icons/screenshot.svg,sha256=Ns9Yi2Iq4lIaiFvzc0pXBmjxt4fcmBO-I4cI8Xiu1HE,311
 neo4j_viz/resources/icons/zoom-in.svg,sha256=PsO5yFkA1JnGM2QV_qxHKG13qmoR-RrlWARpaXNp5qU,415
 neo4j_viz/resources/icons/zoom-out.svg,sha256=OQRADAoe2bxbCeFufg6W22nR41q5NlI8QspT9l5pXUw,400
 neo4j_viz/resources/nvl_entrypoint/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-neo4j_viz/resources/nvl_entrypoint/base.js,sha256=2Z_ofAXO1TFONMqYXjBjPd6l4U3an-h8ZNwgoMiKuPI,1820251
+neo4j_viz/resources/nvl_entrypoint/base.js,sha256=UtqPbkh9qhXpt05yz0DvoaCpEMifZaUCy9cHsTUsKjI,1889766
 neo4j_viz/resources/nvl_entrypoint/styles.css,sha256=sRA-0i4Bc-P2S3FHg8FjTBiChr0ikC8f0UOYduXAXT0,1354
-neo4j_viz-0.7.0.dist-info/licenses/LICENSE,sha256=tWSeLI0mRp2u8Pnumaxq51JltfXLVSXl2w_D6kxhRMI,36006
-neo4j_viz-0.7.0.dist-info/METADATA,sha256=JW_fVOFBIyLGU5ooY02mwpN8_vSUwHr3UhlFLIKdVVw,7120
-neo4j_viz-0.7.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-neo4j_viz-0.7.0.dist-info/top_level.txt,sha256=jPUM3z8MOtxqDanc2VzqkxG4HJn8aaq4S7rnCFNk_Vs,10
-neo4j_viz-0.7.0.dist-info/RECORD,,
+neo4j_viz-1.1.0.dist-info/licenses/LICENSE,sha256=tWSeLI0mRp2u8Pnumaxq51JltfXLVSXl2w_D6kxhRMI,36006
+neo4j_viz-1.1.0.dist-info/METADATA,sha256=hTcIDJoQfykzPrpGyHVJEchrUv2ZfiXSW8HVoVstWL0,5925
+neo4j_viz-1.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+neo4j_viz-1.1.0.dist-info/top_level.txt,sha256=jPUM3z8MOtxqDanc2VzqkxG4HJn8aaq4S7rnCFNk_Vs,10
+neo4j_viz-1.1.0.dist-info/RECORD,,

{neo4j_viz-0.7.0.dist-info → neo4j_viz-1.1.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any