neo4j-viz 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

neo4j_viz/snowflake.py

@@ -37,7 +37,7 @@ from snowflake.snowpark.types import (
 )
 
 from neo4j_viz import VisualizationGraph
-from neo4j_viz.colors import ColorSpace
+from neo4j_viz.colors import NEO4J_COLORS_DISCRETE, ColorSpace
 from neo4j_viz.pandas import from_dfs
 
 
@@ -312,33 +312,41 @@ def _map_tables(
 def from_snowflake(
     session: Session,
     project_config: dict[str, Any],
-    node_radius_min_max: Optional[tuple[float, float]] = (3, 60),
 ) -> VisualizationGraph:
-    project_model = VizProjectConfig.model_validate(project_config, strict=False, context={"session": session})
-    node_dfs, rel_dfs, rel_table_names = _map_tables(session, project_model)
+    """
+    Create a VisualizationGraph from Snowflake tables based on a project configuration.
+
+    By default:
+
+    * The caption of the nodes will be set to the table name.
+    * The caption of the relationships will be set to the table name.
+    * The color of the nodes will be set based on the caption, unless there are more than 12 node tables used.
 
-    node_caption_present = False
-    for node_df in node_dfs:
-        if "CAPTION" in node_df.columns:
-            node_caption_present = True
-            break
+    Otherwise, columns will be included as properties on the nodes and relationships.
 
-    if not node_caption_present:
-        for i, node_df in enumerate(node_dfs):
-            node_df["caption"] = project_model.nodeTables[i].split(".")[-1]
+    Args:
+        session (Session): An active Snowflake session.
+        project_config (dict[str, Any]): A dictionary representing the project configuration.
+    Returns:
+        VisualizationGraph: The resulting visualization graph.
+    """
+    project_model = VizProjectConfig.model_validate(project_config, strict=False, context={"session": session})
+    node_dfs, rel_dfs, rel_table_names = _map_tables(session, project_model)
 
-    rel_caption_present = False
-    for rel_df in rel_dfs:
-        if "CAPTION" in rel_df.columns:
-            rel_caption_present = True
-            break
+    for i, node_df in enumerate(node_dfs):
+        node_df["table"] = project_model.nodeTables[i].split(".")[-1]
+    for i, rel_df in enumerate(rel_dfs):
+        rel_df["table"] = rel_table_names[i].split(".")[-1]
 
-    if not rel_caption_present:
-        for i, rel_df in enumerate(rel_dfs):
-            rel_df["caption"] = rel_table_names[i].split(".")[-1]
+    VG = from_dfs(node_dfs, rel_dfs)
 
-    VG = from_dfs(node_dfs, rel_dfs, node_radius_min_max)
+    for node in VG.nodes:
+        node.caption = node.properties.get("table")
+    for rel in VG.relationships:
+        rel.caption = rel.properties.get("table")
 
-    VG.color_nodes(field="caption", color_space=ColorSpace.DISCRETE)
+    number_of_colors = node_df["table"].drop_duplicates().count()
+    if number_of_colors <= len(NEO4J_COLORS_DISCRETE):
+        VG.color_nodes(field="caption", color_space=ColorSpace.DISCRETE)
 
     return VG

neo4j_viz/visualization_graph.py

@@ -22,9 +22,14 @@ 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.
+
+    The `VisualizationGraph` class represents a collection of nodes and relationships that can be
+    rendered as an interactive graph visualization. You can customize the appearance of nodes and
+    relationships by setting their properties, colors, sizes, and other visual attributes.
     """
 
     #: "The nodes in the graph"
@@ -33,15 +38,48 @@ class VisualizationGraph:
     relationships: list[Relationship]
 
     def __init__(self, nodes: list[Node], relationships: list[Relationship]) -> None:
-        """ "
-        Create a new `VisualizationGraph`.
-
+        """
         Parameters
         ----------
-        nodes:
+        nodes : list[Node]
             The nodes in the graph.
-        relationships:
+        relationships : list[Relationship]
             The relationships in the graph.
+
+        Examples
+        --------
+        Basic usage with nodes and relationships:
+
+        >>> from neo4j_viz import Node, Relationship, VisualizationGraph
+        >>> nodes = [
+        ...     Node(id="1", properties={"name": "Alice", "age": 30}),
+        ...     Node(id="2", properties={"name": "Bob", "age": 25}),
+        ... ]
+        >>> relationships = [
+        ...     Relationship(id="r1", source="1", target="2", properties={"type": "KNOWS"})
+        ... ]
+        >>> VG = VisualizationGraph(nodes=nodes, relationships=relationships)
+
+        Setting a node field such as captions from properties:
+
+        >>> # Set caption from a specific property
+        >>> for node in VG.nodes:
+        ...     node.caption = node.properties.get("name")
+
+        Setting a relationship field such as type from properties:
+
+        >>> # Set relationship caption from property
+        >>> for rel in VG.relationships:
+        ...     rel.caption = rel.properties.get("type")
+
+        Using built-in helper methods:
+
+        >>> # Use the color_nodes method for automatic coloring
+        >>> VG.color_nodes(property="age", color_space=ColorSpace.CONTINUOUS)
+        >>>
+        >>> # Use resize_nodes for automatic sizing
+        >>> VG.resize_nodes(property="degree", node_radius_min_max=(10, 50))
+
         """
         self.nodes = nodes
         self.relationships = relationships
@@ -90,6 +128,12 @@ class VisualizationGraph:
             The maximum allowed number of nodes to render.
         show_hover_tooltip:
             Whether to show an info tooltip when hovering over nodes and relationships.
+
+
+        Example
+        -------
+        Basic rendering of a VisualizationGraph:
+        >>> from neo4j_viz import Node, Relationship, VisualizationGraph
         """
 
         num_nodes = len(self.nodes)
@@ -154,6 +198,7 @@ class VisualizationGraph:
         self,
         sizes: Optional[dict[NodeIdType, RealNumber]] = None,
         node_radius_min_max: Optional[tuple[RealNumber, RealNumber]] = (3, 60),
+        property: Optional[str] = None,
     ) -> None:
         """
         Resize the nodes in the graph.
@@ -163,33 +208,47 @@ class VisualizationGraph:
         sizes:
             A dictionary mapping from node ID to the new size of the node.
             If a node ID is not in the dictionary, the size of the node is not changed.
+            Must be None if `property` is provided.
         node_radius_min_max:
             Minimum and maximum node size radius as a tuple. To avoid tiny or huge nodes in the visualization, the
             node sizes are scaled to fit in the given range. If None, the sizes are used as is.
+        property:
+            The property of the nodes to use for sizing. Must be None if `sizes` is provided.
         """
-        if sizes is None and node_radius_min_max is None:
-            raise ValueError("At least one of `sizes` and `node_radius_min_max` must be given")
+        if sizes is not None and property is not None:
+            raise ValueError("At most one of the arguments `sizes` and `property` can be provided")
 
-        # Gather and verify all node size values we have to work with
-        all_sizes = {}
-        for node in self.nodes:
-            size = None
-            if sizes is not None:
-                size = sizes.get(node.id)
+        if sizes is None and property is None and node_radius_min_max is None:
+            raise ValueError("At least one of `sizes`, `property` or `node_radius_min_max` must be given")
 
+        # Gather node sizes
+        all_sizes = {}
+        if sizes is not None:
+            for node in self.nodes:
+                size = sizes.get(node.id, node.size)
                 if size is not None:
-                    if not isinstance(size, (int, float)):
-                        raise ValueError(f"Size for node '{node.id}' must be a real number, but was {size}")
-
-                    if size < 0:
-                        raise ValueError(f"Size for node '{node.id}' must be non-negative, but was {size}")
-
                     all_sizes[node.id] = size
-
-            if size is None:
+        elif property is not None:
+            for node in self.nodes:
+                size = node.properties.get(property, node.size)
+                if size is not None:
+                    all_sizes[node.id] = size
+        else:
+            for node in self.nodes:
                 if node.size is not None:
                     all_sizes[node.id] = node.size
 
+        # Validate node sizes
+        for id, size in all_sizes.items():
+            if size is None:
+                continue
+
+            if not isinstance(size, (int, float)):
+                raise ValueError(f"Size for node '{id}' must be a real number, but was {size}")
+
+            if size < 0:
+                raise ValueError(f"Size for node '{id}' must be non-negative, but was {size}")
+
         if node_radius_min_max is not None:
             verify_radii(node_radius_min_max)
 
@@ -197,6 +256,7 @@ class VisualizationGraph:
         else:
             final_sizes = all_sizes
 
+        # Apply the final sizes to the nodes
         for node in self.nodes:
             size = final_sizes.get(node.id)
 
@@ -264,6 +324,29 @@ class VisualizationGraph:
             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 nodes, if they have any.
+
+        Examples
+        --------
+
+        Given a VisualizationGraph `VG`:
+
+        >>> nodes = [
+        ...    Node(id="0", properties={"label": "Person", "score": 10}),
+        ...    Node(id="1", properties={"label": "Person", "score": 20}),
+        ... ]
+        >>> 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":
+
+        >>> VG.color_nodes(field="score", color_space=ColorSpace.CONTINUOUS)
+
+        Color nodes based on a custom colors such as from palettable:
+
+        >>> from palettable.wesanderson import Moonrise1_5  # type: ignore[import-untyped]
+        >>> VG.color_nodes(field="label", colors=Moonrise1_5.colors)
         """
         if not ((field is None) ^ (property is None)):
             raise ValueError(

{neo4j_viz-0.5.0.dist-info → neo4j_viz-0.6.0.dist-info}/METADATA

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: neo4j-viz
-Version: 0.5.0
+Version: 0.6.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
@@ -11,12 +12,10 @@ Keywords: graph,visualization,neo4j
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -26,18 +25,19 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: ipython<10,>=7
 Requires-Dist: pydantic<3,>=2
 Requires-Dist: pydantic-extra-types<3,>=2
-Requires-Dist: enum-tools==0.12.0
+Requires-Dist: enum-tools==0.13.0
 Provides-Extra: dev
-Requires-Dist: ruff==0.11.8; extra == "dev"
+Requires-Dist: ruff==0.14.1; extra == "dev"
 Requires-Dist: mypy==1.17.1; extra == "dev"
-Requires-Dist: pytest==8.3.4; extra == "dev"
+Requires-Dist: pytest==8.4.2; extra == "dev"
 Requires-Dist: selenium==4.32.0; extra == "dev"
-Requires-Dist: ipykernel==6.29.5; 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"
@@ -46,7 +46,7 @@ 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.6; 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"
@@ -65,6 +65,7 @@ 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
 

neo4j_viz-0.6.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+neo4j_viz/__init__.py,sha256=Q-VZlJe3_kAow_-F_-9RsHCQfbOfv5on26YD9ihw27o,504
+neo4j_viz/colors.py,sha256=IvOCTmCu7WTMna_wNLZ3GrThTwFyIoKtNkmZYDLdYac,6694
+neo4j_viz/gds.py,sha256=KCnUJ4nTQlM28P-TIVf2JZMlvsvHjneaLROnh95F670,7434
+neo4j_viz/gql_create.py,sha256=2KMHKsOuELV8i-HGXIRAi4SqPrjCdphcMYD8W5VK-Xg,12252
+neo4j_viz/neo4j.py,sha256=5u3mUbQQ0-39NkvpJe-H0BjnUqBOyKOgV_QF3FWCVTc,4643
+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/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+neo4j_viz/relationship.py,sha256=aVj8_6umHSm1rg53CU-oci21W845J91AFKv1AJudmD8,4112
+neo4j_viz/snowflake.py,sha256=GoiFfpzE5fuAorh_PNZCK7QSIv52pIMn_QS2LLsUxCM,12683
+neo4j_viz/visualization_graph.py,sha256=v2OmfGM8t9UDmSDCFLe5uWa6MnPmppby20VK_NjThT4,17161
+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=tICNjZLV8sUen2qvosUZuUlovpHcZIqXpdNzSo4phE4,1820159
+neo4j_viz/resources/nvl_entrypoint/styles.css,sha256=JjeTSB9OJT2KMfb8yFUUMLMG7Rzrf3o60hSCD547zTk,1123
+neo4j_viz-0.6.0.dist-info/licenses/LICENSE,sha256=tWSeLI0mRp2u8Pnumaxq51JltfXLVSXl2w_D6kxhRMI,36006
+neo4j_viz-0.6.0.dist-info/METADATA,sha256=A06tmKgiAI93yfZRX-ofAapiQeJldwSCKkCegzf_LG0,7120
+neo4j_viz-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+neo4j_viz-0.6.0.dist-info/top_level.txt,sha256=jPUM3z8MOtxqDanc2VzqkxG4HJn8aaq4S7rnCFNk_Vs,10
+neo4j_viz-0.6.0.dist-info/RECORD,,