neo4j-viz 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

neo4j_viz/__init__.py

@@ -1,6 +1,25 @@
 from .node import Node
-from .options import CaptionAlignment, Layout, Renderer
+from .options import (
+    CaptionAlignment,
+    Direction,
+    ForceDirectedLayoutOptions,
+    HierarchicalLayoutOptions,
+    Layout,
+    Packing,
+    Renderer,
+)
 from .relationship import Relationship
 from .visualization_graph import VisualizationGraph
 
-__all__ = ["VisualizationGraph", "Node", "Relationship", "CaptionAlignment", "Layout", "Renderer"]
+__all__ = [
+    "VisualizationGraph",
+    "Node",
+    "Relationship",
+    "CaptionAlignment",
+    "Layout",
+    "Renderer",
+    "ForceDirectedLayoutOptions",
+    "HierarchicalLayoutOptions",
+    "Direction",
+    "Packing",
+]

neo4j_viz/gds.py

@@ -2,15 +2,17 @@ from __future__ import annotations
 
 from itertools import chain
 from typing import Optional
+from uuid import uuid4
 
 import pandas as pd
 from graphdatascience import Graph, GraphDataScience
+from pandas import Series
 
 from .pandas import _from_dfs
 from .visualization_graph import VisualizationGraph
 
 
-def _node_dfs(
+def _fetch_node_dfs(
     gds: GraphDataScience, G: Graph, node_properties: list[str], node_labels: list[str]
 ) -> dict[str, pd.DataFrame]:
     return {
@@ -21,7 +23,21 @@ def _node_dfs(
     }
 
 
-def _rel_df(gds: GraphDataScience, G: Graph) -> pd.DataFrame:
+def _fetch_rel_df(gds: GraphDataScience, G: Graph) -> pd.DataFrame:
+    relationship_properties = G.relationship_properties()
+    assert isinstance(relationship_properties, Series)
+
+    relationship_properties_per_type = relationship_properties.tolist()
+    property_set: set[str] = set()
+    for props in relationship_properties_per_type:
+        if props:
+            property_set.update(props)
+
+    if len(property_set) > 0:
+        return gds.graph.relationshipProperties.stream(
+            G, relationship_properties=list(property_set), separate_property_columns=True
+        )
+
     return gds.graph.relationships.stream(G)
 
 
@@ -31,6 +47,7 @@ def from_gds(
     size_property: Optional[str] = None,
     additional_node_properties: Optional[list[str]] = None,
     node_radius_min_max: Optional[tuple[float, float]] = (3, 60),
+    max_node_count: int = 10_000,
 ) -> VisualizationGraph:
     """
     Create a VisualizationGraph from a GraphDataScience object and a Graph object.
@@ -49,10 +66,14 @@ def from_gds(
     size_property : str, optional
         Property to use for node size, by default None.
     additional_node_properties : list[str], optional
-        Additional properties to include in the visualization node, by default None. They can be used later for modifying the node appearance.
+        Additional properties to include in the visualization node, by default None which means that all node
+        properties will be fetched.
     node_radius_min_max : tuple[float, float], optional
         Minimum and maximum node radius, by default (3, 60).
         To avoid tiny or huge nodes in the visualization, the node sizes are scaled to fit in the given range.
+    max_node_count : int, optional
+        The maximum number of nodes to fetch from the graph. The graph will be sampled using random walk with restarts
+        if its node count exceeds this number.
     """
     node_properties_from_gds = G.node_properties()
     assert isinstance(node_properties_from_gds, pd.Series)
@@ -61,7 +82,9 @@ def from_gds(
     if size_property is not None and size_property not in actual_node_properties:
         raise ValueError(f"There is no node property '{size_property}' in graph '{G.name()}'")
 
-    if additional_node_properties is not None:
+    if additional_node_properties is None:
+        additional_node_properties = actual_node_properties
+    else:
         for prop in additional_node_properties:
             if prop not in actual_node_properties:
                 raise ValueError(f"There is no node property '{prop}' in graph '{G.name()}'")
@@ -69,14 +92,40 @@ def from_gds(
     node_properties = set()
     if additional_node_properties is not None:
         node_properties.update(additional_node_properties)
-
     if size_property is not None:
         node_properties.add(size_property)
-
     node_properties = list(node_properties)
-    node_dfs = _node_dfs(gds, G, node_properties, G.node_labels())
+
+    node_count = G.node_count()
+    if node_count > max_node_count:
+        sampling_ratio = float(max_node_count) / node_count
+        sample_name = f"neo4j-viz_sample_{uuid4()}"
+        G_fetched, _ = gds.graph.sample.rwr(sample_name, G, samplingRatio=sampling_ratio, nodeLabelStratification=True)
+    else:
+        G_fetched = G
+
+    property_name = None
+    try:
+        # Since GDS does not allow us to only fetch node IDs, we add the degree property
+        # as a temporary property to ensure that we have at least one property to fetch
+        if len(actual_node_properties) == 0:
+            property_name = f"neo4j-viz_property_{uuid4()}"
+            gds.degree.mutate(G_fetched, mutateProperty=property_name)
+            node_properties = [property_name]
+
+        node_dfs = _fetch_node_dfs(gds, G_fetched, node_properties, G_fetched.node_labels())
+        rel_df = _fetch_rel_df(gds, G_fetched)
+    finally:
+        if G_fetched.name() != G.name():
+            G_fetched.drop()
+        elif property_name is not None:
+            gds.graph.nodeProperties.drop(G_fetched, node_properties=[property_name])
+
     for df in node_dfs.values():
         df.rename(columns={"nodeId": "id"}, inplace=True)
+        if property_name is not None and property_name in df.columns:
+            df.drop(columns=[property_name], inplace=True)
+    rel_df.rename(columns={"sourceNodeId": "source", "targetNodeId": "target"}, inplace=True)
 
     node_props_df = pd.concat(node_dfs.values(), ignore_index=True, axis=0).drop_duplicates()
     if size_property is not None:
@@ -89,12 +138,21 @@ def from_gds(
             df.rename(columns={"labels": "__labels"}, inplace=True)
         df["labels"] = lbl
 
-    node_lbls_df = pd.concat([df[["id", "labels"]] for df in node_dfs.values()], ignore_index=True, axis=0)
-    node_lbls_df = node_lbls_df.groupby("id").agg({"labels": list})
+    node_labels_df = pd.concat([df[["id", "labels"]] for df in node_dfs.values()], ignore_index=True, axis=0)
+    node_labels_df = node_labels_df.groupby("id").agg({"labels": list})
 
-    node_df = node_props_df.merge(node_lbls_df, on="id")
+    node_df = node_props_df.merge(node_labels_df, on="id")
 
-    rel_df = _rel_df(gds, G)
-    rel_df.rename(columns={"sourceNodeId": "source", "targetNodeId": "target"}, inplace=True)
+    if "caption" not in actual_node_properties:
+        node_df["caption"] = node_df["labels"].astype(str)
 
-    return _from_dfs(node_df, rel_df, node_radius_min_max=node_radius_min_max, rename_properties={"__size": "size"})
+    try:
+        return _from_dfs(node_df, rel_df, node_radius_min_max=node_radius_min_max, rename_properties={"__size": "size"})
+    except ValueError as e:
+        err_msg = str(e)
+        if "column" in err_msg:
+            err_msg = err_msg.replace("column", "property")
+            if ("'size'" in err_msg) and (size_property is not None):
+                err_msg = err_msg.replace("'size'", f"'{size_property}'")
+            raise ValueError(err_msg)
+        raise e

neo4j_viz/gql_create.py

@@ -2,6 +2,8 @@ import re
 import uuid
 from typing import Any, Optional
 
+from pydantic import BaseModel, ValidationError
+
 from neo4j_viz import Node, Relationship, VisualizationGraph
 
 
@@ -249,13 +251,22 @@ def from_gql_create(
     node_pattern = re.compile(r"^\(([^)]*)\)$")
     rel_pattern = re.compile(r"^\(([^)]*)\)-\s*\[\s*:(\w+)\s*(\{[^}]*\})?\s*\]->\(([^)]*)\)$")
 
-    node_top_level_keys = set(Node.model_fields.keys())
-    node_top_level_keys.remove("id")
-
-    rel_top_level_keys = set(Relationship.model_fields.keys())
-    rel_top_level_keys.remove("id")
-    rel_top_level_keys.remove("source")
-    rel_top_level_keys.remove("target")
+    node_top_level_keys = Node.all_validation_aliases(exempted_fields=["id"])
+    rel_top_level_keys = Relationship.all_validation_aliases(exempted_fields=["id", "source", "target"])
+
+    def _parse_validation_error(e: ValidationError, entity_type: type[BaseModel]) -> None:
+        for err in e.errors():
+            loc = err["loc"][0]
+            if (loc == "size") and size_property is not None:
+                loc = size_property
+            if loc == "caption":
+                if (entity_type == Node) and (node_caption is not None):
+                    loc = node_caption
+                elif (entity_type == Relationship) and (relationship_caption is not None):
+                    loc = relationship_caption
+            raise ValueError(
+                f"Error for {entity_type.__name__.lower()} property '{loc}' with provided input '{err['input']}'. Reason: {err['msg']}"
+            )
 
     nodes = []
     relationships = []
@@ -272,7 +283,10 @@ def from_gql_create(
                 anonymous_count += 1
             if alias not in alias_to_id:
                 alias_to_id[alias] = str(uuid.uuid4())
-            nodes.append(Node(id=alias_to_id[alias], **top_level, properties=props))
+            try:
+                nodes.append(Node(id=alias_to_id[alias], **top_level, properties=props))
+            except ValidationError as e:
+                _parse_validation_error(e, Node)
 
             continue
 
@@ -288,7 +302,10 @@ def from_gql_create(
                 anonymous_count += 1
                 if left_alias not in alias_to_id:
                     alias_to_id[left_alias] = str(uuid.uuid4())
-                nodes.append(Node(id=alias_to_id[left_alias], **left_top_level, properties=left_props))
+                try:
+                    nodes.append(Node(id=alias_to_id[left_alias], **left_top_level, properties=left_props))
+                except ValidationError as e:
+                    _parse_validation_error(e, Node)
             elif left_alias not in alias_to_id:
                 snippet = _get_snippet(query, query.index(left_node))
                 raise ValueError(f"Relationship references unknown node alias: '{left_alias}' near: `{snippet}`.")
@@ -300,7 +317,10 @@ def from_gql_create(
                 anonymous_count += 1
                 if right_alias not in alias_to_id:
                     alias_to_id[right_alias] = str(uuid.uuid4())
-                nodes.append(Node(id=alias_to_id[right_alias], **right_top_level, properties=right_props))
+                try:
+                    nodes.append(Node(id=alias_to_id[right_alias], **right_top_level, properties=right_props))
+                except ValidationError as e:
+                    _parse_validation_error(e, Node)
             elif right_alias not in alias_to_id:
                 snippet = _get_snippet(query, query.index(right_node))
                 raise ValueError(f"Relationship references unknown node alias: '{right_alias}' near: `{snippet}`.")
@@ -318,15 +338,20 @@ def from_gql_create(
             if "type" in props:
                 props["__type"] = props["type"]
             props["type"] = rel_type
-            relationships.append(
-                Relationship(
-                    id=rel_id,
-                    source=alias_to_id[left_alias],
-                    target=alias_to_id[right_alias],
-                    **top_level,
-                    properties=props,
+
+            try:
+                relationships.append(
+                    Relationship(
+                        id=rel_id,
+                        source=alias_to_id[left_alias],
+                        target=alias_to_id[right_alias],
+                        **top_level,
+                        properties=props,
+                    )
                 )
-            )
+            except ValidationError as e:
+                _parse_validation_error(e, Relationship)
+
             continue
 
         snippet = part[:30]
@@ -351,6 +376,10 @@ def from_gql_create(
 
     VG = VisualizationGraph(nodes=nodes, relationships=relationships)
     if (node_radius_min_max is not None) and (size_property is not None):
-        VG.resize_nodes(node_radius_min_max=node_radius_min_max)
+        try:
+            VG.resize_nodes(node_radius_min_max=node_radius_min_max)
+        except TypeError:
+            loc = "size" if size_property is None else size_property
+            raise ValueError(f"Error for node property '{loc}'. Reason: must be a numerical value")
 
     return VG

neo4j_viz/neo4j.py

@@ -4,12 +4,21 @@ from typing import Optional, Union
 
 import neo4j.graph
 from neo4j import Result
+from pydantic import BaseModel, ValidationError
 
 from neo4j_viz.node import Node
 from neo4j_viz.relationship import Relationship
 from neo4j_viz.visualization_graph import VisualizationGraph
 
 
+def _parse_validation_error(e: ValidationError, entity_type: type[BaseModel]) -> None:
+    for err in e.errors():
+        loc = err["loc"][0]
+        raise ValueError(
+            f"Error for {entity_type.__name__.lower()} property '{loc}' with provided input '{err['input']}'. Reason: {err['msg']}"
+        )
+
+
 def from_neo4j(
     result: Union[neo4j.graph.Graph, Result],
     size_property: Optional[str] = None,
@@ -47,12 +56,33 @@ def from_neo4j(
     else:
         raise ValueError(f"Invalid input type `{type(result)}`. Expected `neo4j.Graph` or `neo4j.Result`")
 
-    nodes = [_map_node(node, size_property, caption_property=node_caption) for node in graph.nodes]
+    all_node_field_aliases = Node.all_validation_aliases()
+    all_rel_field_aliases = Relationship.all_validation_aliases()
+
+    try:
+        nodes = [
+            _map_node(node, all_node_field_aliases, size_property, caption_property=node_caption)
+            for node in graph.nodes
+        ]
+    except ValueError as e:
+        err_msg = str(e)
+        if ("'size'" in err_msg) and (size_property is not None):
+            err_msg = err_msg.replace("'size'", f"'{size_property}'")
+        elif ("'caption'" in err_msg) and (node_caption is not None):
+            err_msg = err_msg.replace("'caption'", f"'{node_caption}'")
+        raise ValueError(err_msg)
+
     relationships = []
-    for rel in graph.relationships:
-        mapped_rel = _map_relationship(rel, caption_property=relationship_caption)
-        if mapped_rel:
-            relationships.append(mapped_rel)
+    try:
+        for rel in graph.relationships:
+            mapped_rel = _map_relationship(rel, all_rel_field_aliases, caption_property=relationship_caption)
+            if mapped_rel:
+                relationships.append(mapped_rel)
+    except ValueError as e:
+        err_msg = str(e)
+        if ("'caption'" in err_msg) and (relationship_caption is not None):
+            err_msg = err_msg.replace("'caption'", f"'{relationship_caption}'")
+        raise ValueError(err_msg)
 
     VG = VisualizationGraph(nodes, relationships)
 
@@ -62,7 +92,12 @@ def from_neo4j(
     return VG
 
 
-def _map_node(node: neo4j.graph.Node, size_property: Optional[str], caption_property: Optional[str]) -> Node:
+def _map_node(
+    node: neo4j.graph.Node,
+    all_node_field_aliases: set[str],
+    size_property: Optional[str],
+    caption_property: Optional[str],
+) -> Node:
     top_level_fields = {"id": node.element_id}
 
     if size_property:
@@ -78,7 +113,7 @@ def _map_node(node: neo4j.graph.Node, size_property: Optional[str], caption_prop
 
     properties = {}
     for prop, value in node.items():
-        if prop not in Node.model_fields.keys():
+        if prop not in all_node_field_aliases:
             properties[prop] = value
             continue
 
@@ -92,10 +127,17 @@ def _map_node(node: neo4j.graph.Node, size_property: Optional[str], caption_prop
         properties["__labels"] = properties["labels"]
     properties["labels"] = labels
 
-    return Node(**top_level_fields, properties=properties)
+    try:
+        viz_node = Node(**top_level_fields, properties=properties)
+    except ValidationError as e:
+        _parse_validation_error(e, Node)
 
+    return viz_node
 
-def _map_relationship(rel: neo4j.graph.Relationship, caption_property: Optional[str]) -> Optional[Relationship]:
+
+def _map_relationship(
+    rel: neo4j.graph.Relationship, all_rel_field_aliases: set[str], caption_property: Optional[str]
+) -> Optional[Relationship]:
     if rel.start_node is None or rel.end_node is None:
         return None
 
@@ -109,7 +151,7 @@ def _map_relationship(rel: neo4j.graph.Relationship, caption_property: Optional[
 
     properties = {}
     for prop, value in rel.items():
-        if prop not in Relationship.model_fields.keys():
+        if prop not in all_rel_field_aliases:
             properties[prop] = value
             continue
 
@@ -123,4 +165,9 @@ def _map_relationship(rel: neo4j.graph.Relationship, caption_property: Optional[
         properties["__type"] = properties["type"]
     properties["type"] = rel.type
 
-    return Relationship(**top_level_fields, properties=properties)
+    try:
+        viz_rel = Relationship(**top_level_fields, properties=properties)
+    except ValidationError as e:
+        _parse_validation_error(e, Relationship)
+
+    return viz_rel

neo4j_viz/node.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 from typing import Any, Optional, Union
 
-from pydantic import AliasChoices, BaseModel, Field, field_serializer, field_validator
+from pydantic import AliasChoices, AliasGenerator, BaseModel, Field, field_serializer, field_validator
+from pydantic.alias_generators import to_camel
 from pydantic_extra_types.color import Color, ColorType
 
 from .node_size import RealNumber
@@ -11,29 +12,46 @@ from .options import CaptionAlignment
 NodeIdType = Union[str, int]
 
 
-class Node(BaseModel, extra="allow"):
+def create_aliases(field_name: str) -> AliasChoices:
+    valid_names = [field_name]
+
+    if field_name == "id":
+        valid_names.extend(["nodeid", "node_id"])
+
+    choices = [[choice, choice.upper(), to_camel(choice)] for choice in valid_names]
+
+    return AliasChoices(*[alias for aliases in choices for alias in aliases])
+
+
+class Node(
+    BaseModel,
+    extra="forbid",
+    alias_generator=AliasGenerator(
+        validation_alias=create_aliases,
+        serialization_alias=lambda field_name: to_camel(field_name),
+    ),
+):
     """
     A node in a graph to visualize.
 
+    Each field is case-insensitive for input, and camelCase is also accepted.
+    For example, "CAPTION_ALIGN", "captionAlign" are also valid inputs keys for the `caption_align` field.
+    Upon construction however, the field names are converted to snake_case.
+
     For more info on each field, see the NVL library docs: https://neo4j.com/docs/nvl/current/base-library/#_nodes
     """
 
     #: Unique identifier for the node
-    id: NodeIdType = Field(
-        validation_alias=AliasChoices("id", "nodeId", "node_id"), description="Unique identifier for the node"
-    )
+    id: NodeIdType = Field(description="Unique identifier for the node")
     #: The caption of the node
     caption: Optional[str] = Field(None, description="The caption of the node")
     #: The alignment of the caption text
-    caption_align: Optional[CaptionAlignment] = Field(
-        None, serialization_alias="captionAlign", description="The alignment of the caption text"
-    )
+    caption_align: Optional[CaptionAlignment] = Field(None, description="The alignment of the caption text")
     #: The size of the caption text. The font size to node radius ratio
     caption_size: Optional[int] = Field(
         None,
         ge=1,
         le=3,
-        serialization_alias="captionSize",
         description="The size of the caption text. The font size to node radius ratio",
     )
     #: The size of the node as radius in pixel
@@ -70,3 +88,12 @@ class Node(BaseModel, extra="allow"):
 
     def to_dict(self) -> dict[str, Any]:
         return self.model_dump(exclude_none=True, by_alias=True)
+
+    @staticmethod
+    def all_validation_aliases(exempted_fields: Optional[list[str]] = None) -> set[str]:
+        if exempted_fields is None:
+            exempted_fields = []
+
+        by_field = [v.validation_alias.choices for k, v in Node.model_fields.items() if k not in exempted_fields]  # type: ignore
+
+        return {str(alias) for aliases in by_field for alias in aliases}

neo4j_viz/nvl.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import uuid
 from importlib.resources import files
+from typing import Union
 
 from IPython.display import HTML
 
@@ -40,10 +41,28 @@ class NVL:
         with screenshot_path.open("r", encoding="utf-8") as file:
             self.screenshot_svg = file.read()
 
-    def unsupported_field_type_error(self, e: TypeError, entity: str) -> Exception:
-        if "not JSON serializable" in str(e):
-            return ValueError(f"A field of a {entity} object is not supported: {str(e)}")
-        return e
+    @staticmethod
+    def _serialize_entity(entity: Union[Node, Relationship]) -> str:
+        try:
+            entity_dict = entity.to_dict()
+            return json.dumps(entity_dict)
+        except TypeError:
+            props_as_strings = {}
+            for k, v in entity_dict["properties"].items():
+                try:
+                    json.dumps(v)
+                except TypeError:
+                    props_as_strings[k] = str(v)
+            entity_dict["properties"].update(props_as_strings)
+
+            try:
+                return json.dumps(entity_dict)
+            except TypeError as e:
+                # This should never happen anymore, but just in case
+                if "not JSON serializable" in str(e):
+                    raise ValueError(f"A field of a {type(entity).__name__} object is not supported: {str(e)}")
+                else:
+                    raise e
 
     def render(
         self,
@@ -54,14 +73,8 @@ class NVL:
         height: str,
         show_hover_tooltip: bool,
     ) -> HTML:
-        try:
-            nodes_json = json.dumps([node.to_dict() for node in nodes])
-        except TypeError as e:
-            raise self.unsupported_field_type_error(e, "node")
-        try:
-            rels_json = json.dumps([rel.to_dict() for rel in relationships])
-        except TypeError as e:
-            raise self.unsupported_field_type_error(e, "relationship")
+        nodes_json = f"[{','.join([self._serialize_entity(node) for node in nodes])}]"
+        rels_json = f"[{','.join([self._serialize_entity(rel) for rel in relationships])}]"
 
         render_options_json = json.dumps(render_options.to_dict())
         container_id = str(uuid.uuid4())
@@ -112,7 +125,7 @@ class NVL:
         <script>
             getTheme = () => {{
                 const backgroundColorString = window.getComputedStyle(document.body, null).getPropertyValue('background-color')
-                const colorsArray = backgroundColorString.match(/\d+/g);
+                const colorsArray = backgroundColorString.match(/\\d+/g);
                 const brightness = Number(colorsArray[0]) * 0.2126 + Number(colorsArray[1]) * 0.7152 + Number(colorsArray[2]) * 0.0722
                 return brightness < 128 ? "dark" : "light"
             }}

neo4j_viz/options.py

@@ -2,10 +2,10 @@ from __future__ import annotations
 
 import warnings
 from enum import Enum
-from typing import Any, Optional
+from typing import Any, Optional, Union
 
 import enum_tools.documentation
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, ValidationError, model_validator
 
 
 @enum_tools.documentation.document_enum
@@ -33,6 +33,69 @@ class Layout(str, Enum):
     GRID = "grid"
 
 
+@enum_tools.documentation.document_enum
+class Direction(str, Enum):
+    """
+    The direction in which the layout should be oriented
+    """
+
+    LEFT = "left"
+    RIGHT = "right"
+    UP = "up"
+    DOWN = "down"
+
+
+@enum_tools.documentation.document_enum
+class Packing(str, Enum):
+    """
+    The packing method to be used
+    """
+
+    BIN = "bin"
+    STACK = "stack"
+
+
+class HierarchicalLayoutOptions(BaseModel, extra="forbid"):
+    """
+    The options for the hierarchical layout.
+    """
+
+    direction: Optional[Direction] = None
+    packaging: Optional[Packing] = None
+
+
+class ForceDirectedLayoutOptions(BaseModel, extra="forbid"):
+    """
+    The options for the force-directed layout.
+    """
+
+    gravity: Optional[float] = None
+    simulationStopVelocity: Optional[float] = None
+
+
+LayoutOptions = Union[HierarchicalLayoutOptions, ForceDirectedLayoutOptions]
+
+
+def construct_layout_options(layout: Layout, options: dict[str, Any]) -> Optional[LayoutOptions]:
+    if not options:
+        return None
+
+    if layout == Layout.FORCE_DIRECTED:
+        try:
+            return ForceDirectedLayoutOptions(**options)
+        except ValidationError as e:
+            _parse_validation_error(e, ForceDirectedLayoutOptions)
+    elif layout == Layout.HIERARCHICAL:
+        try:
+            return HierarchicalLayoutOptions(**options)
+        except ValidationError as e:
+            _parse_validation_error(e, ForceDirectedLayoutOptions)
+
+    raise ValueError(
+        f"Layout options only supported for layouts `{Layout.FORCE_DIRECTED}` and `{Layout.HIERARCHICAL}`, but was `{layout}`"
+    )
+
+
 @enum_tools.documentation.document_enum
 class Renderer(str, Enum):
     """
@@ -72,6 +135,9 @@ class RenderOptions(BaseModel, extra="allow"):
     """
 
     layout: Optional[Layout] = None
+    layout_options: Optional[Union[HierarchicalLayoutOptions, ForceDirectedLayoutOptions]] = Field(
+        None, serialization_alias="layoutOptions"
+    )
     renderer: Optional[Renderer] = None
 
     pan_X: Optional[float] = Field(None, serialization_alias="panX")
@@ -84,5 +150,34 @@ class RenderOptions(BaseModel, extra="allow"):
     min_zoom: Optional[float] = Field(None, serialization_alias="minZoom", description="The minimum zoom level allowed")
     allow_dynamic_min_zoom: Optional[bool] = Field(None, serialization_alias="allowDynamicMinZoom")
 
+    @model_validator(mode="after")
+    def check_layout_options_match(self) -> RenderOptions:
+        if self.layout_options is None:
+            return self
+
+        if self.layout == Layout.HIERARCHICAL and not isinstance(self.layout_options, HierarchicalLayoutOptions):
+            raise ValueError("layout_options must be of type HierarchicalLayoutOptions for hierarchical layout")
+        if self.layout == Layout.FORCE_DIRECTED and not isinstance(self.layout_options, ForceDirectedLayoutOptions):
+            raise ValueError("layout_options must be of type ForceDirectedLayoutOptions for force-directed layout")
+        return self
+
     def to_dict(self) -> dict[str, Any]:
         return self.model_dump(exclude_none=True, by_alias=True)
+
+
+def _parse_validation_error(e: ValidationError, entity_type: type[BaseModel]) -> None:
+    for err in e.errors():
+        loc = err["loc"][0]
+        if err["type"] == "missing":
+            raise ValueError(
+                f"Mandatory `{entity_type.__name__}` parameter '{loc}' is missing. Expected one of {entity_type.model_fields[loc].validation_alias.choices} to be present"  # type: ignore
+            )
+        elif err["type"] == "extra_forbidden":
+            raise ValueError(
+                f"Unexpected `{entity_type.__name__}` parameter '{loc}' with provided input '{err['input']}'. "
+                f"Allowed parameters are: {', '.join(entity_type.model_fields.keys())}"
+            )
+        else:
+            raise ValueError(
+                f"Error for `{entity_type.__name__}` parameter '{loc}' with provided input '{err['input']}'. Reason: {err['msg']}"
+            )

neo4j_viz/pandas.py

@@ -4,6 +4,7 @@ from collections.abc import Iterable
 from typing import Optional, Union
 
 from pandas import DataFrame
+from pydantic import BaseModel, ValidationError
 
 from .node import Node
 from .relationship import Relationship
@@ -12,17 +13,55 @@ from .visualization_graph import VisualizationGraph
 DFS_TYPE = Union[DataFrame, Iterable[DataFrame]]
 
 
+def _parse_validation_error(e: ValidationError, entity_type: type[BaseModel]) -> None:
+    for err in e.errors():
+        loc = err["loc"][0]
+        if err["type"] == "missing":
+            raise ValueError(
+                f"Mandatory {entity_type.__name__.lower()} column '{loc}' is missing. Expected one of {entity_type.model_fields[loc].validation_alias.choices} to be present"  # type: ignore
+            )
+        else:
+            raise ValueError(
+                f"Error for {entity_type.__name__.lower()} column '{loc}' with provided input '{err['input']}'. Reason: {err['msg']}"
+            )
+
+
 def _from_dfs(
-    node_dfs: DFS_TYPE,
+    node_dfs: Optional[DFS_TYPE],
     rel_dfs: DFS_TYPE,
     node_radius_min_max: Optional[tuple[float, float]] = (3, 60),
     rename_properties: Optional[dict[str, str]] = None,
 ) -> VisualizationGraph:
+    relationships = _parse_relationships(rel_dfs, rename_properties=rename_properties)
+
+    if node_dfs is None:
+        has_size = False
+        node_ids = set()
+        for rel in relationships:
+            node_ids.add(rel.source)
+            node_ids.add(rel.target)
+        nodes = [Node(id=id) for id in node_ids]
+    else:
+        nodes, has_size = _parse_nodes(node_dfs, rename_properties=rename_properties)
+
+    VG = VisualizationGraph(nodes=nodes, relationships=relationships)
+
+    if node_radius_min_max is not None and has_size:
+        VG.resize_nodes(node_radius_min_max=node_radius_min_max)
+
+    return VG
+
+
+def _parse_nodes(node_dfs: DFS_TYPE, rename_properties: Optional[dict[str, str]]) -> tuple[list[Node], bool]:
     if isinstance(node_dfs, DataFrame):
         node_dfs_iter: Iterable[DataFrame] = [node_dfs]
+    elif node_dfs is None:
+        node_dfs_iter = []
     else:
         node_dfs_iter = node_dfs
 
+    all_node_field_aliases = Node.all_validation_aliases()
+
     has_size = True
     nodes = []
     for node_df in node_dfs_iter:
@@ -31,45 +70,52 @@ def _from_dfs(
             top_level = {}
             properties = {}
             for key, value in row.to_dict().items():
-                if key in Node.model_fields.keys():
+                if key in all_node_field_aliases:
                     top_level[key] = value
                 else:
                     if rename_properties and key in rename_properties:
                         key = rename_properties[key]
                     properties[key] = value
 
-            nodes.append(Node(**top_level, properties=properties))
+            try:
+                nodes.append(Node(**top_level, properties=properties))
+            except ValidationError as e:
+                _parse_validation_error(e, Node)
+
+    return nodes, has_size
+
+
+def _parse_relationships(rel_dfs: DFS_TYPE, rename_properties: Optional[dict[str, str]]) -> list[Relationship]:
+    all_rel_field_aliases = Relationship.all_validation_aliases()
 
     if isinstance(rel_dfs, DataFrame):
         rel_dfs_iter: Iterable[DataFrame] = [rel_dfs]
     else:
         rel_dfs_iter = rel_dfs
+    relationships: list[Relationship] = []
 
-    relationships = []
     for rel_df in rel_dfs_iter:
         for _, row in rel_df.iterrows():
             top_level = {}
             properties = {}
             for key, value in row.to_dict().items():
-                if key in Relationship.model_fields.keys():
+                if key in all_rel_field_aliases:
                     top_level[key] = value
                 else:
                     if rename_properties and key in rename_properties:
                         key = rename_properties[key]
                     properties[key] = value
 
-            relationships.append(Relationship(**top_level, properties=properties))
+            try:
+                relationships.append(Relationship(**top_level, properties=properties))
+            except ValidationError as e:
+                _parse_validation_error(e, Relationship)
 
-    VG = VisualizationGraph(nodes=nodes, relationships=relationships)
-
-    if node_radius_min_max is not None and has_size:
-        VG.resize_nodes(node_radius_min_max=node_radius_min_max)
-
-    return VG
+    return relationships
 
 
 def from_dfs(
-    node_dfs: DFS_TYPE,
+    node_dfs: Optional[DFS_TYPE],
     rel_dfs: DFS_TYPE,
     node_radius_min_max: Optional[tuple[float, float]] = (3, 60),
 ) -> VisualizationGraph:
@@ -82,8 +128,9 @@ def from_dfs(
 
     Parameters
     ----------
-    node_dfs: Union[DataFrame, Iterable[DataFrame]]
+    node_dfs: Optional[Union[DataFrame, Iterable[DataFrame]]]
         DataFrame or iterable of DataFrames containing node data.
+        If None, the nodes will be created from the source and target node ids in the rel_dfs.
     rel_dfs: Union[DataFrame, Iterable[DataFrame]]
         DataFrame or iterable of DataFrames containing relationship data.
     node_radius_min_max : tuple[float, float], optional

neo4j_viz/relationship.py

@@ -3,16 +3,41 @@ from __future__ import annotations
 from typing import Any, Optional, Union
 from uuid import uuid4
 
-from pydantic import AliasChoices, BaseModel, Field, field_serializer, field_validator
+from pydantic import AliasChoices, AliasGenerator, BaseModel, Field, field_serializer, field_validator
+from pydantic.alias_generators import to_camel
 from pydantic_extra_types.color import Color, ColorType
 
 from .options import CaptionAlignment
 
 
-class Relationship(BaseModel, extra="allow"):
+def create_aliases(field_name: str) -> AliasChoices:
+    valid_names = [field_name]
+
+    if field_name == "source":
+        valid_names.extend(["sourcenodeid", "source_node_id", "from"])
+    if field_name == "target":
+        valid_names.extend(["targetnodeid", "target_node_id", "to"])
+
+    choices = [[choice, choice.upper(), to_camel(choice)] for choice in valid_names]
+
+    return AliasChoices(*[alias for aliases in choices for alias in aliases])
+
+
+class Relationship(
+    BaseModel,
+    extra="forbid",
+    alias_generator=AliasGenerator(
+        validation_alias=create_aliases,
+        serialization_alias=lambda field_name: to_camel(field_name),
+    ),
+):
     """
     A relationship in a graph to visualize.
 
+    Each field is case-insensitive for input, and camelCase is also accepted.
+    For example, "CAPTION_ALIGN", "captionAlign" are also valid inputs keys for the `caption_align` field.
+    Upon construction however, the field names are converted to snake_case.
+
     For more info on each field, see the NVL library docs: https://neo4j.com/docs/nvl/current/base-library/#_relationships
     """
 
@@ -23,25 +48,19 @@ class Relationship(BaseModel, extra="allow"):
     #: Node ID where the relationship points from
     source: Union[str, int] = Field(
         serialization_alias="from",
-        validation_alias=AliasChoices("source", "sourceNodeId", "source_node_id", "from"),
         description="Node ID where the relationship points from",
     )
     #: Node ID where the relationship points to
     target: Union[str, int] = Field(
         serialization_alias="to",
-        validation_alias=AliasChoices("target", "targetNodeId", "target_node_id", "to"),
         description="Node ID where the relationship points to",
     )
     #: The caption of the relationship
     caption: Optional[str] = Field(None, description="The caption of the relationship")
     #: The alignment of the caption text
-    caption_align: Optional[CaptionAlignment] = Field(
-        None, serialization_alias="captionAlign", description="The alignment of the caption text"
-    )
+    caption_align: Optional[CaptionAlignment] = Field(None, description="The alignment of the caption text")
     #: The size of the caption text
-    caption_size: Optional[Union[int, float]] = Field(
-        None, gt=0.0, serialization_alias="captionSize", description="The size of the caption text"
-    )
+    caption_size: Optional[Union[int, float]] = Field(None, gt=0.0, description="The size of the caption text")
     #: The color of the relationship. Allowed input is for example "#FF0000", "red" or (255, 0, 0)
     color: Optional[ColorType] = Field(None, description="The color of the relationship")
     #: Additional properties of the relationship that do not directly impact the visualization
@@ -76,3 +95,16 @@ class Relationship(BaseModel, extra="allow"):
 
     def to_dict(self) -> dict[str, Any]:
         return self.model_dump(exclude_none=True, by_alias=True)
+
+    @staticmethod
+    def all_validation_aliases(exempted_fields: Optional[list[str]] = None) -> set[str]:
+        if exempted_fields is None:
+            exempted_fields = []
+
+        by_field = [
+            v.validation_alias.choices  # type: ignore
+            for k, v in Relationship.model_fields.items()
+            if k not in exempted_fields
+        ]
+
+        return {str(alias) for aliases in by_field for alias in aliases}

neo4j_viz/visualization_graph.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import warnings
 from collections.abc import Iterable
-from typing import Any, Callable, Hashable, Optional
+from typing import Any, Callable, Hashable, Optional, Union
 
 from IPython.display import HTML
 from pydantic_extra_types.color import Color, ColorType
@@ -11,7 +11,13 @@ from .colors import NEO4J_COLORS_CONTINUOUS, NEO4J_COLORS_DISCRETE, ColorSpace,
 from .node import Node, NodeIdType
 from .node_size import RealNumber, verify_radii
 from .nvl import NVL
-from .options import Layout, Renderer, RenderOptions
+from .options import (
+    Layout,
+    LayoutOptions,
+    Renderer,
+    RenderOptions,
+    construct_layout_options,
+)
 from .relationship import Relationship
 
 
@@ -42,6 +48,7 @@ class VisualizationGraph:
     def render(
         self,
         layout: Optional[Layout] = None,
+        layout_options: Union[dict[str, Any], LayoutOptions, None] = None,
         renderer: Renderer = Renderer.CANVAS,
         width: str = "100%",
         height: str = "600px",
@@ -60,6 +67,8 @@ class VisualizationGraph:
         ----------
         layout:
             The `Layout` to use.
+        layout_options:
+            The `LayoutOptions` to use.
         renderer:
             The `Renderer` to use.
         width:
@@ -92,8 +101,19 @@ class VisualizationGraph:
 
         Renderer.check(renderer, num_nodes)
 
+        if not layout:
+            layout = Layout.FORCE_DIRECTED
+        if not layout_options:
+            layout_options = {}
+
+        if isinstance(layout_options, dict):
+            layout_options_typed = construct_layout_options(layout, layout_options)
+        else:
+            layout_options_typed = layout_options
+
         render_options = RenderOptions(
             layout=layout,
+            layout_options=layout_options_typed,
             renderer=renderer,
             pan_X=pan_position[0] if pan_position is not None else None,
             pan_Y=pan_position[1] if pan_position is not None else None,

{neo4j_viz-0.3.0.dist-info → neo4j_viz-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: neo4j-viz
-Version: 0.3.0
+Version: 0.4.0
 Summary: A simple graph visualization tool
 Author-email: Neo4j <team-gds@neo4j.org>
 Project-URL: Homepage, https://neo4j.com/

neo4j_viz-0.4.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+neo4j_viz/__init__.py,sha256=Q-VZlJe3_kAow_-F_-9RsHCQfbOfv5on26YD9ihw27o,504
+neo4j_viz/colors.py,sha256=IvOCTmCu7WTMna_wNLZ3GrThTwFyIoKtNkmZYDLdYac,6694
+neo4j_viz/gds.py,sha256=Cu-0RDi6YtWiuWP1N06h5P0zd5mQx0z5cafr0fs2K24,6637
+neo4j_viz/gql_create.py,sha256=K33cT6dOj8eJPGNNJXiXlCfLIzNxTwcW4n_2AG3_zaY,14751
+neo4j_viz/neo4j.py,sha256=_bZkj1XQKazueRM7Ti0pIPdSI8fVd432mZbQsxFO2yw,6112
+neo4j_viz/node.py,sha256=MiLoghsn2NLs_iV65NuW7u3iaxP8MTKoNy6La9TdreY,3886
+neo4j_viz/node_size.py,sha256=c_sMtQSD8eJ_6Y0Kr6ku0LOs9VoEDxfYCUUzUWZ-1Xo,1197
+neo4j_viz/nvl.py,sha256=ZN3tyWar9ugR88r5N6txW3ThfNEWOt5A1KzrrRnLKwk,5262
+neo4j_viz/options.py,sha256=eOpiLcIfFvUiPoozyT44F9MHGRkqCfBZFmh0u_6DfwY,6400
+neo4j_viz/pandas.py,sha256=Ajn77VRcen4lqrVQp0O9yUG5bZ7QkjiCIpjj0UFCD0w,5162
+neo4j_viz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+neo4j_viz/relationship.py,sha256=sRgGjNzlqt6wPmiB3WXBTxR_W_5Z40VofpHUZvkRS1I,4143
+neo4j_viz/visualization_graph.py,sha256=Fizmzm8p4p3Fbd3gsiTymkXgI3crpdmr5ipv4gFv3SY,13760
+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/base.js,sha256=QfFjqd7Uo2F-plgFlPfLzUcjqzTzqUh533VaBemJhLI,1816247
+neo4j_viz/resources/nvl_entrypoint/styles.css,sha256=JjeTSB9OJT2KMfb8yFUUMLMG7Rzrf3o60hSCD547zTk,1123
+neo4j_viz-0.4.0.dist-info/METADATA,sha256=J3KTYHc4S8w50RqS4VbTaOQ4EaAWjGqyzVQn9zfU7OY,7074
+neo4j_viz-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+neo4j_viz-0.4.0.dist-info/top_level.txt,sha256=jPUM3z8MOtxqDanc2VzqkxG4HJn8aaq4S7rnCFNk_Vs,10
+neo4j_viz-0.4.0.dist-info/RECORD,,

{neo4j_viz-0.3.0.dist-info → neo4j_viz-0.4.0.dist-info}/WHEEL

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

neo4j_viz-0.3.0.dist-info/RECORD

@@ -1,22 +0,0 @@
-neo4j_viz/__init__.py,sha256=ATDPdaupFWIWaOWtJtfCGVRVuuwXKNe1hNdENofgRLk,270
-neo4j_viz/colors.py,sha256=IvOCTmCu7WTMna_wNLZ3GrThTwFyIoKtNkmZYDLdYac,6694
-neo4j_viz/gds.py,sha256=v6b3XdSoWSoOu-U2MWQM-5QXLiPT3_9gGOv7haxuozE,4135
-neo4j_viz/gql_create.py,sha256=Eqo_fFxtsrsoKV0gjXIpHZdeBqjX2q-vwe_xBCJU7OI,13354
-neo4j_viz/neo4j.py,sha256=0urKoYwtCyyKXMu_tWPspehyjOFF5ETyiWuYVNA1Wfc,4589
-neo4j_viz/node.py,sha256=NgB8preP2v1PWW177iU4YeojvfWafz8yIyY7MQrP6iE,2850
-neo4j_viz/node_size.py,sha256=c_sMtQSD8eJ_6Y0Kr6ku0LOs9VoEDxfYCUUzUWZ-1Xo,1197
-neo4j_viz/nvl.py,sha256=32NTuNCaf78bHEVD1nWQD5jUHS2ZUBemxKktuIpiCK0,4774
-neo4j_viz/options.py,sha256=QBeHLqHOJFtSCjzHvv-2A9TzTbnIaC6_onQq9fUlT_4,3079
-neo4j_viz/pandas.py,sha256=4ArBUV6DKOhwbplD8edJd5DsIilDNKyCpPjqrus0bPk,3269
-neo4j_viz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-neo4j_viz/relationship.py,sha256=DmmBUHup_jtqnenQKACCfz4Mz7CjbCnDmOZfsSj6qiQ,3042
-neo4j_viz/visualization_graph.py,sha256=ogYhxAyPzqOcSogYSesGAV6iRQDLIA-YhBImEShuCPM,13175
-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/base.js,sha256=QfFjqd7Uo2F-plgFlPfLzUcjqzTzqUh533VaBemJhLI,1816247
-neo4j_viz/resources/nvl_entrypoint/styles.css,sha256=JjeTSB9OJT2KMfb8yFUUMLMG7Rzrf3o60hSCD547zTk,1123
-neo4j_viz-0.3.0.dist-info/METADATA,sha256=wCM57O61k4kllIiYOqopDJiQPBzyftooJwhwz9h8oSw,7074
-neo4j_viz-0.3.0.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
-neo4j_viz-0.3.0.dist-info/top_level.txt,sha256=jPUM3z8MOtxqDanc2VzqkxG4HJn8aaq4S7rnCFNk_Vs,10
-neo4j_viz-0.3.0.dist-info/RECORD,,