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", "