Slim down neo4j api

Author: FlorentinD

changelog.md

@@ -4,13 +4,9 @@
 
 - Do not automatically derive size and caption for `from_neo4j` and `from_gql_create`. Use the `size_property` and `node_caption` parameters to explicitly configure them.
 - Change API of integrations to only provide basic parameters. Any further configuration should happen ons the Visualization Graph object:
-  - `from_gds`
-    - Drop parameters `size_property`, `node_radius_min_max`. Use `VG.resize_nodes(property=...)` instead
-    - rename additional_node_properties to node_properties
-    - Don't derive fields from properties. Use `VG.map_properties_to_fields` instead
   - `from_pandas`
     - Drop `node_radius_min_max` parameter. `VG.resize_nodes(...)` instead
-  - `from_gql_create`
+  - `from_neo4j`, `from_gds`, `from_gql_create`
     - Drop parameters `size_property`, `node_radius_min_max`. Use `VG.resize_nodes(property=...)` instead
     - rename additional_node_properties to node_properties
     - Don't derive fields from properties. Use `VG.map_properties_to_fields` instead

docs/source/integration.rst

@@ -164,22 +164,9 @@ The ``from_neo4j`` method takes one mandatory positional parameter:
 A ``data`` argument representing either a query result in the shape of a ``neo4j.graph.Graph`` or ``neo4j.Result``, or a
 ``neo4j.Driver`` in which case a simple default query will be executed internally to retrieve the graph data.
 
-We can also provide an optional ``size_property`` parameter, which should refer to a node property,
-and will be used to determine the sizes of the nodes in the visualization.
-
-The ``node_caption`` and ``relationship_caption`` parameters are also optional, and indicate the node and relationship
-properties to use for the captions of each element in the visualization.
-By default, the captions will be set to the node labels relationship types, but you can specify any property that
-exists on these entities.
-
-The last optional property, ``node_radius_min_max``, can be used (and is used by default) to scale the node sizes for
-the visualization.
-It is a tuple of two numbers, representing the radii (sizes) in pixels of the smallest and largest nodes respectively in
-the visualization.
-The node sizes will be scaled such that the smallest node will have the size of the first value, and the largest node
-will have the size of the second value.
-The other nodes will be scaled linearly between these two values according to their relative size.
-This can be useful if node sizes vary a lot, or are all very small or very big.
+The optional ``max_rows`` parameter can be used to limit the number of relationships shown in the visualization.
+By default, it is set to 10.000, meaning that if the database has more than 10.000 rows, a warning will be raised.
+Note, this only applies if the ``data`` parameter is a ``neo4j.Driver``.
 
 
 Example
@@ -269,39 +256,14 @@ The ``from_snowflake`` method takes two mandatory positional parameters:
 * A `project configuration <https://neo4j.com/docs/snowflake-graph-analytics/current/jobs/#jobs-project>`_ as a dictionary, that specifies how you want your tables to be projected as a graph.
   This configuration is the same as the project configuration of the `Neo4j Snowflake Graph Analytics application <https://neo4j.com/docs/snowflake-graph-analytics/current/>`_.
 
-``from_snowflake`` also takes an optional property, ``node_radius_min_max``, that can be used (and is used by default) to
-scale the node sizes for the visualization.
-It is a tuple of two numbers, representing the radii (sizes) in pixels of the smallest and largest nodes respectively in
-the visualization.
-The node sizes will be scaled such that the smallest node will have the size of the first value, and the largest node
-will have the size of the second value.
-The other nodes will be scaled linearly between these two values according to their relative size.
-This can be useful if node sizes vary a lot, or are all very small or very big.
-
-
-Special columns
-~~~~~~~~~~~~~~~
-
-It is possible to modify the visualization directly by including columns of certain specific names in the node and relationship tables.
-
-All such special columns can be found :doc:`here <./api-reference/node>` for nodes and :doc:`here <./api-reference/relationship>` for relationships.
-Though listed in ``snake_case`` here, ``SCREAMING_SNAKE_CASE`` and ``camelCase`` are also supported.
-Some of the most commonly used special columns are:
-
-* **Node sizes**: The sizes of nodes can be controlled by including a column named "SIZE" in node tables.
-  The values in these columns should be of a numeric type. This can be useful for visualizing the relative importance or size of nodes in the graph, for example using a computed centrality score.
-
-* **Captions**: The caption text of nodes and relationships can be controlled by including a column named "CAPTION" in the tables.
-  The values in these columns should be of a string type. This can be useful for displaying additional information about the nodes, such as their names or labels. If no "CAPTION" column is provided, the default captions in the visualization will be the names of the corresponding node and relationship tables.
-
-Please also note that you can further customize the visualization after the `VisualizationGraph` has been created, by using the methods described in the :doc:`Customizing the visualization <./customizing>` section.
+You can further customize the visualization after the `VisualizationGraph` has been created, by using the methods described in the :doc:`Customizing the visualization <./customizing>` section.
 
 
 Default behavior
 ~~~~~~~~~~~~~~~~
 
-Unless there are "CAPTION" columns in the tables, the node and relationship captions will be set to the names of the corresponding tables.
-Similarly, if there are are no "COLOR" node table columns, the nodes will be colored be colored so that nodes from the same table have the same color, and different tables have different colors.
+The node and relationship captions will be set to the names of the corresponding tables.
+The nodes will be colored so that nodes from the same table have the same color, and different tables have different colors.
 
 
 Example

python-wrapper/src/neo4j_viz/neo4j.py

@@ -7,6 +7,7 @@
 from neo4j import Driver, Result, RoutingControl
 from pydantic import BaseModel, ValidationError
 
+from neo4j_viz.colors import NEO4J_COLORS_DISCRETE, ColorSpace
 from neo4j_viz.node import Node
 from neo4j_viz.relationship import Relationship
 from neo4j_viz.visualization_graph import VisualizationGraph
@@ -22,34 +23,25 @@ def _parse_validation_error(e: ValidationError, entity_type: type[BaseModel]) ->
 
 def from_neo4j(
     data: Union[neo4j.graph.Graph, Result, Driver],
-    size_property: Optional[str] = None,
-    node_caption: Optional[str] = "labels",
-    relationship_caption: Optional[str] = "type",
-    node_radius_min_max: Optional[tuple[float, float]] = (3, 60),
     row_limit: int = 10_000,
 ) -> VisualizationGraph:
     """
     Create a VisualizationGraph from a Neo4j `Graph`, Neo4j `Result` or Neo4j `Driver`.
 
-    All node and relationship properties will be included in the visualization graph.
-    If the properties are named as the fields of the `Node` or `Relationship` classes, they will be included as
-    top level fields of the respective objects. Otherwise, they will be included in the `properties` dictionary.
+    By default:
+
+    * the caption of a node will be based on its `labels`.
+    * the caption of a relationship will be based on its `type`.
+    * the color of nodes will be set based on their label, unless there are more than 12 unique labels.
+
+    All node and relationship properties will be included in the visualization graph under the `properties` field.
     Additionally, a "labels" property will be added for nodes and a "type" property for relationships.
 
     Parameters
     ----------
     data : Union[neo4j.graph.Graph, neo4j.Result, neo4j.Driver]
         Either a query result in the shape of a `neo4j.graph.Graph` or `neo4j.Result`, or a `neo4j.Driver` in
         which case a simple default query will be executed internally to retrieve the graph data.
-    size_property : str, optional
-        Property to use for node size, by default None.
-    node_caption : str, optional
-        Property to use as the node caption, by default the node labels will be used.
-    relationship_caption : str, optional
-        Property to use as the relationship caption, by default the relationship type will be used.
-    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.
     row_limit : int, optional
         Maximum number of rows to return from the query, by default 10_000.
         This is only used if a `neo4j.Driver` is passed as `result` argument, otherwise the limit is ignored.
@@ -77,117 +69,62 @@ def from_neo4j(
     else:
         raise ValueError(f"Invalid input type `{type(data)}`. Expected `neo4j.Graph`, `neo4j.Result` or `neo4j.Driver`")
 
-    all_node_field_aliases = Node.all_validation_aliases(exempted_fields=["size", "caption"])
-    all_rel_field_aliases = Relationship.all_validation_aliases(exempted_fields=["caption"])
-
-    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)
+    nodes = [_map_node(node) for node in graph.nodes]
 
     relationships = []
-    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)
+
+    for rel in graph.relationships:
+        mapped_rel = _map_relationship(rel)
+        if mapped_rel:
+            relationships.append(mapped_rel)
 
     VG = VisualizationGraph(nodes, 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)
+    for node in VG.nodes:
+        node.caption = ":".join(node.properties["labels"])
+    for r in VG.relationships:
+        r.caption = r.properties["type"]
+
+    number_of_colors = len({n.caption for n in VG.nodes})
+    if number_of_colors <= len(NEO4J_COLORS_DISCRETE):
+        VG.color_nodes(field="caption", color_space=ColorSpace.DISCRETE, colors=NEO4J_COLORS_DISCRETE)
 
     return VG
 
 
 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:
-        top_level_fields["size"] = node.get(size_property)
-
     labels = sorted([label for label in node.labels])
-    if caption_property:
-        if caption_property == "labels":
-            if len(labels) > 0:
-                top_level_fields["caption"] = ":".join([label for label in labels])
-        else:
-            top_level_fields["caption"] = str(node.get(caption_property))
-
-    properties = {}
-    for prop, value in node.items():
-        if prop not in all_node_field_aliases:
-            properties[prop] = value
-            continue
 
-        if prop in top_level_fields:
-            properties[prop] = value
-            continue
-
-        top_level_fields[prop] = value
+    properties = {prop: value for prop, value in node.items()}
 
     if "labels" in properties:
         properties["__labels"] = properties["labels"]
     properties["labels"] = labels
 
     try:
-        viz_node = Node(**top_level_fields, properties=properties)
+        viz_node = Node(id=node.element_id, properties=properties)
     except ValidationError as e:
         _parse_validation_error(e, Node)
 
     return viz_node
 
 
-def _map_relationship(
-    rel: neo4j.graph.Relationship, all_rel_field_aliases: set[str], caption_property: Optional[str]
-) -> Optional[Relationship]:
+def _map_relationship(rel: neo4j.graph.Relationship) -> Optional[Relationship]:
     if rel.start_node is None or rel.end_node is None:
         return None
 
-    top_level_fields = {"id": rel.element_id, "source": rel.start_node.element_id, "target": rel.end_node.element_id}
-
-    if caption_property:
-        if caption_property == "type":
-            top_level_fields["caption"] = rel.type
-        else:
-            top_level_fields["caption"] = str(rel.get(caption_property))
-
-    properties = {}
-    for prop, value in rel.items():
-        if prop not in all_rel_field_aliases:
-            properties[prop] = value
-            continue
-
-        if prop in top_level_fields:
-            properties[prop] = value
-            continue
-
-        top_level_fields[prop] = value
+    properties = {prop: value for prop, value in rel.items()}
 
     if "type" in properties:
         properties["__type"] = properties["type"]
     properties["type"] = rel.type
 
     try:
-        viz_rel = Relationship(**top_level_fields, properties=properties)
+        viz_rel = Relationship(
+            id=rel.element_id, source=rel.start_node.element_id, target=rel.end_node.element_id, properties=properties
+        )
     except ValidationError as e:
         _parse_validation_error(e, Relationship)
 

python-wrapper/src/neo4j_viz/node.py

@@ -90,15 +90,6 @@ def cast_color(cls, color: ColorType) -> Color:
     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}
-
     @staticmethod
     def basic_fields_validation_aliases() -> set[str]:
         mandatory_fields = ["id"]

python-wrapper/src/neo4j_viz/relationship.py

@@ -97,19 +97,6 @@ def cast_color(cls, color: ColorType) -> Color:
     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}
-
     @staticmethod
     def basic_fields_validation_aliases() -> set[str]:
         basic_fields = ["id", "source", "target"]

python-wrapper/src/neo4j_viz/snowflake.py

@@ -317,9 +317,11 @@ def from_snowflake(
     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.
+
     Otherwise, columns will be included as properties on the nodes and relationships.
 
     Args: