diff --git a/docs/source/api-reference/colors.rst b/docs/source/api-reference/colors.rst
new file mode 100644
index 00000000..c2d29283
--- /dev/null
+++ b/docs/source/api-reference/colors.rst
@@ -0,0 +1,2 @@
+.. autoenum:: neo4j_viz.colors.ColorSpace
+ :members:
diff --git a/docs/source/customizing.rst b/docs/source/customizing.rst
index 37918c8e..0619658c 100644
--- a/docs/source/customizing.rst
+++ b/docs/source/customizing.rst
@@ -23,11 +23,11 @@ If you have not yet created a ``VisualizationGraph`` object, please refer to one
Coloring nodes
--------------
-Nodes can be colored directly by providing them with a color property, upon creation.
+Nodes can be colored directly by providing them with a color field, upon creation.
This can for example be done by passing a color as a string to the ``color`` parameter of the
:doc:`Node <./api-reference/node>` object.
-Alternatively, you can color nodes based on a property (field) of the nodes after a ``VisualizationGraph`` object has been
+Alternatively, you can color nodes based on a field or property of the nodes after a ``VisualizationGraph`` object has been
created.
@@ -35,12 +35,14 @@ The ``color_nodes`` method
~~~~~~~~~~~~~~~~~~~~~~~~~~
By calling the :meth:`neo4j_viz.VisualizationGraph.color_nodes` method, you can color nodes based on a
-node property (field).
-It's possible to color the nodes based on a discrete or continuous property.
-In the discrete case, a new color from the ``colors`` provided is assigned to each unique value of the node 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 node property.
+node field or property (members of the `Node.properties` map).
-By default the Neo4j color palette that works for both light and dark mode will be used.
+It's possible to color the nodes based on a discrete or continuous color space (see :doc:`ColorSpace <./api-reference/colors>`).
+In the discrete case, a new color from the `colors` provided is assigned to each unique value of the node 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 node field/property.
+
+By default the Neo4j color palette, that works for both light and dark mode, will be used.
If you want to use a different color palette, you can pass a dictionary or iterable of colors as the ``colors``
parameter.
A color value can for example be either strings like "blue", or hexadecimal color codes like "#FF0000", or even a tuple of RGB values like (255, 0, 255).
@@ -49,20 +51,20 @@ If some nodes already have a ``color`` set, you can choose whether or not to ove
parameter.
-By discrete node property (field)
-*********************************
+By discrete color space
+***********************
-To not use the default colors, we can provide a list of custom colors based on the discrete node property (field) "caption" to the ``color_nodes`` method:
+To not use the default colors, we can provide a list of custom colors based on the discrete node field "caption" to the ``color_nodes`` method:
.. code-block:: python
- from neo4j_viz.colors import PropertyType
+ from neo4j_viz.colors import ColorSpace
# VG is a VisualizationGraph object
VG.color_nodes(
- "caption",
+ field="caption",
["red", "#7fffd4", (255, 255, 255, 0.5), "hsl(270, 60%, 70%)"],
- property_type=PropertyType.DISCRETE
+ color_space=ColorSpace.DISCRETE
)
The full set of allowed values for colors are listed `here `_.
@@ -75,18 +77,18 @@ this snippet:
from palettable.wesanderson import Moonrise1_5
# VG is a VisualizationGraph object
- VG.color_nodes("caption", Moonrise1_5.colors) # PropertyType.DISCRETE is default
+ VG.color_nodes(field="caption", Moonrise1_5.colors) # PropertyType.DISCRETE is default
-In this case, all nodes with the same caption will get the same color.
+In theses cases, all nodes with the same caption will get the same color.
-If there are fewer colors that unique values for the node ``property`` provided, the colors will be reused in a cycle.
-To avoid that, you could use another palette or extend one with additional colors. Please refer to the
+If there are fewer colors than unique values for the node ``field`` or ``property`` provided, the colors will be reused in a cycle.
+To avoid that, you could use a larger palette or extend one with additional colors. Please refer to the
:doc:`Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial <./tutorials/gds-example>` for an example on how
to do the latter.
-By continuous node property (field)
-***********************************
+By continuous color space
+*************************
To not use the default colors, we can provide a list of custom colors representing a range to the ``color_nodes`` method:
@@ -96,9 +98,9 @@ To not use the default colors, we can provide a list of custom colors representi
# VG is a VisualizationGraph object
VG.color_nodes(
- "centrality_score",
+ property="centrality_score",
[(255, 0, 0), (191, 64, 0), (128, 128, 0), (64, 191, 0), (0, 255, 0)] # From red to green
- property_type=PropertyType.CONTINUOUS
+ color_space=ColorSpace.CONTINUOUS
)
In this case, the nodes will be colored based on the value of the "centrality_score" property, with the lowest values being colored red and the highest values being colored green.
@@ -110,7 +112,7 @@ Since we only provided five colors in the range, the granularity of the gradient
Sizing nodes
------------
-Nodes can be given a size directly by providing them with a size property, upon creation.
+Nodes can be given a size directly by providing them with a size field, upon creation.
This can for example be done by passing a size as an integer to the ``size`` parameter of the
:doc:`Node <./api-reference/node>` object.
@@ -178,7 +180,7 @@ In the following example, we pin the node with ID 1337 and unpin the node with I
Direct modification of nodes and relationships
----------------------------------------------
-Nodes and relationships can also be modified directly by accessing the ``nodes`` and ``relationships`` attributes of an
+Nodes and relationships can also be modified directly by accessing the ``nodes`` and ``relationships`` fields of an
existing ``VisualizationGraph`` object.
These attributes list of all the :doc:`Nodes <./api-reference/node>` and
:doc:`Relationships <./api-reference/relationship>` in the graph, respectively.
@@ -189,6 +191,7 @@ Each node and relationship has attributes that can be accessed and modified dire
# VG is a VisualizationGraph object
VG.nodes[0].size = 10
+ VG.nodes[0].properties["height"] = 170
VG.relationships[4].caption = "BUYS"
Any changes made to the nodes and relationships will be reflected in the next rendering of the graph.
diff --git a/docs/source/integration.rst b/docs/source/integration.rst
index 1f451ec7..31687303 100644
--- a/docs/source/integration.rst
+++ b/docs/source/integration.rst
@@ -3,8 +3,9 @@ Integration with other libraries
In addition to creating graphs from scratch, with ``neo4j-viz`` as is shown in the
:doc:`Getting started section <./getting-started>`, you can also import data directly from external sources.
-In this section we will cover how to import data from `Pandas DataFrames `_ and
-`Neo4j Graph Data Science `_.
+In this section we will cover how to import data from `Pandas DataFrames `_,
+`Neo4j Graph Data Science `_ and
+`Neo4j Database `_.
.. contents:: On this page:
@@ -31,12 +32,18 @@ The ``from_dfs`` method takes two mandatory positional parameters:
* A Pandas ``DataFrame``, or iterable (eg. list) of DataFrames representing the nodes of the graph.
The rows of the DataFrame(s) should represent the individual nodes, and the columns should represent the node
- IDs and properties. The columns map directly to fields of :doc:`Node <./api-reference/node>`, and as such
- should follow the same naming conventions.
+ IDs and attributes.
+ If a column shares the name with a field of :doc:`Node <./api-reference/node>`, the values it contains will be set
+ on corresponding nodes under that field name.
+ Otherwise, the column name will be a key in each node's `properties` dictionary, that maps to the node's corresponding
+ value in the column.
* A Pandas ``DataFrame``, or iterable (eg. list) of DataFrames representing the relationships of the graph.
The rows of the DataFrame(s) should represent the individual relationships, and the columns should represent the
- relationship IDs and properties. The columns map directly to fields of
- :doc:`Relationship <./api-reference/relationship>`, and as such should follow the same naming conventions.
+ relationship IDs and attributes.
+ If a column shares the name with a field of :doc:`Relationship <./api-reference/relationship>`, the values it contains
+ will be set on corresponding relationships under that field name.
+ Otherwise, the column name will be a key in each node's `properties` dictionary, that maps to the node's corresponding
+ value in the column.
``from_dfs`` 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.
@@ -97,11 +104,12 @@ The ``from_gds`` method takes two mandatory positional parameters:
* A ``Graph`` representing the projection that one wants to import.
We can also provide an optional ``size_property`` parameter, which should refer to a node property of the projection,
-and will be used to determine the size of the nodes in the visualization.
+and will be used to determine the sizes of the nodes in the visualization.
The ``additional_node_properties`` parameter is also optional, and should be a list of additional node properties of the
projection that you want to include in the visualization.
-For example, these properties could be used to color the nodes, or give captions to them in the visualization.
+For example, these properties could be used to color the nodes, or give captions to them in the visualization, or simply
+included in the nodes' `Node.properties` maps without directly impacting the visualization.
The last optional property, ``node_radius_min_max``, can be used (and is used by default) to scale the node sizes for
the visualization.
@@ -143,7 +151,7 @@ We use the "pagerank" property to determine the size of the nodes, and the "comp
# Color the nodes by the `componentId` property, so that the nodes are
# colored by the connected component they belong to
- VG.color_nodes("componentId")
+ VG.color_nodes(property="componentId")
Please see the :doc:`Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial <./tutorials/gds-example>` for a
@@ -167,10 +175,10 @@ The ``from_neo4j`` method takes one mandatory positional parameters:
* A ``result`` representing the query result either in form of `neo4j.graph.Graph` or `neo4j.Result`.
-The ``node_caption`` parameter is also optional, and indicates the value to use for the caption of each node in the visualization.
+The ``node_caption`` parameter is also optional, and indicates the node property to use for the caption of each node in the visualization.
-We can also provide an optional ``size_property`` parameter, which should refer to a node property of the projection,
-and will be used to determine the size of the nodes in the visualization.
+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 last optional property, ``node_radius_min_max``, can be used (and is used by default) to scale the node sizes for
the visualization.
diff --git a/examples/gds-example.ipynb b/examples/gds-example.ipynb
index cb8d44ed..78970831 100644
--- a/examples/gds-example.ipynb
+++ b/examples/gds-example.ipynb
@@ -129,14 +129,14 @@
"data": {
"text/html": [
"\n",
- "
\n",
+ " \n",
"