|
| 1 | += Customizing the visualization |
| 2 | + |
| 3 | +Once created, a link:{api-docs-uri}/visualization-graph[`VisualizationGraph` object] can be modified in various ways |
| 4 | +to adjust what the visualization looks like the next time you render it. |
| 5 | +In this section we will discuss how to color, size, and pin nodes, as well as how to directly modify nodes and |
| 6 | +relationships of existing `VisualizationGraph` objects. |
| 7 | + |
| 8 | +If you have not yet created a `VisualizationGraph` object, refer to one of the following sections: |
| 9 | + |
| 10 | +* xref:getting-started.adoc[Getting started] for creating a visualization graph from scratch using `neo4j-viz` |
| 11 | + primitives like link:{api-docs-uri}/node/[Node] and link:{api-docs-uri}/relationship/[Relationship] and |
| 12 | + link:{api-docs-uri}/visualization-graph[`VisualizationGraph`] directly. |
| 13 | +* xref:integration.adoc[] for importing data from a Pandas DataFrame or Neo4j GDS projection. |
| 14 | +
|
| 15 | +== Setting node captions |
| 16 | + |
| 17 | +Node captions are the text labels displayed on nodes in the visualization. |
| 18 | + |
| 19 | +=== The `set_node_captions` method |
| 20 | + |
| 21 | +By calling the `neo4j_viz.VisualizationGraph.set_node_captions()` method, you can set node captions based on a node field (like `id`, `size`, etc.) or a node property (members of the `Node.properties` map). |
| 22 | + |
| 23 | +The method accepts an `override` parameter (default `True`) that controls whether to replace existing captions. |
| 24 | +If `override=False`, only nodes without captions will be updated. |
| 25 | + |
| 26 | +Here is an example of setting node captions from a property: |
| 27 | + |
| 28 | +[source, python] |
| 29 | +---- |
| 30 | +# VG is a VisualizationGraph object with nodes that have a "name" property |
| 31 | +VG.set_node_captions(property="name") |
| 32 | +---- |
| 33 | + |
| 34 | +You can also set captions from a node field, and choose not to override existing captions: |
| 35 | + |
| 36 | +[source, python] |
| 37 | +---- |
| 38 | +# VG is a VisualizationGraph object |
| 39 | +VG.set_node_captions(field="id", override=False) |
| 40 | +---- |
| 41 | + |
| 42 | +For more complex scenarios where you need fallback logic or want to combine multiple properties, you can iterate over nodes directly: |
| 43 | + |
| 44 | +[source, python] |
| 45 | +---- |
| 46 | +# VG is a VisualizationGraph object |
| 47 | +for node in VG.nodes: |
| 48 | + caption = node.properties.get("name") or node.properties.get("title") or node.id |
| 49 | + node.caption = str(caption) |
| 50 | +---- |
| 51 | + |
| 52 | +== Coloring nodes |
| 53 | + |
| 54 | +Nodes can be colored directly by providing them with a color field, upon creation. |
| 55 | +This can for example be done by passing a color as a string to the `color` parameter of the |
| 56 | +link:{api-docs-uri}/node[Node] object. |
| 57 | + |
| 58 | +Alternatively, you can color nodes based on a field or property of the nodes after a `VisualizationGraph` object has been |
| 59 | +created. |
| 60 | + |
| 61 | +=== The `color_nodes` method |
| 62 | + |
| 63 | +By calling the link:{api-docs-uri}/visualization-graph/#neo4j_viz.VisualizationGraph.color_nodes[`neo4j_viz.VisualizationGraph.color_nodes()`] method, you can color nodes based on a node field or property (members of the `Node.properties` map). |
| 64 | + |
| 65 | +It's possible to color the nodes based on a discrete or continuous color space (see link:{api-docs-uri}/colors[`ColorSpace`]). |
| 66 | +In the discrete case, a new color from the `colors` provided is assigned to each unique value of the node field/property. |
| 67 | +In the continuous case, the `colors` should be a list of colors representing a range that are used to |
| 68 | +create a gradient of colors based on the values of the node field/property. |
| 69 | + |
| 70 | +By default the Neo4j color palette, that works for both light and dark mode, will be used. |
| 71 | +If you want to use a different color palette, you can pass a dictionary or iterable of colors as the `colors` |
| 72 | +parameter. |
| 73 | +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). |
| 74 | + |
| 75 | +If some nodes already have a `color` set, you can choose whether or not to override it with the `override` |
| 76 | +parameter. |
| 77 | + |
| 78 | +==== By discrete color space |
| 79 | + |
| 80 | +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: |
| 81 | + |
| 82 | +[source, python] |
| 83 | +---- |
| 84 | +from neo4j_viz.colors import ColorSpace |
| 85 | +
|
| 86 | +# VG is a VisualizationGraph object |
| 87 | +VG.color_nodes( |
| 88 | + field="caption", |
| 89 | + ["red", "#7fffd4", (255, 255, 255, 0.5), "hsl(270, 60%, 70%)"], |
| 90 | + color_space=ColorSpace.DISCRETE |
| 91 | +) |
| 92 | +---- |
| 93 | + |
| 94 | +The full set of allowed values for colors are listed link:https://docs.pydantic.dev/2.0/usage/types/extra_types/color_types/[here]. |
| 95 | + |
| 96 | +Instead of defining your own colors, you could also for example use the color palettes from the link:https://jiffyclub.github.io/palettable/[`palettable` library] as in this snippet: |
| 97 | + |
| 98 | +[source, python] |
| 99 | +---- |
| 100 | +from palettable.wesanderson import Moonrise1_5 |
| 101 | +
|
| 102 | +# VG is a VisualizationGraph object |
| 103 | +VG.color_nodes(field="caption", Moonrise1_5.colors) # PropertyType.DISCRETE is default |
| 104 | +---- |
| 105 | + |
| 106 | +In theses cases, all nodes with the same caption will get the same color. |
| 107 | + |
| 108 | +If there are fewer colors than unique values for the node `field` or `property` provided, the colors will be reused in a cycle. |
| 109 | +To avoid that, you could use a larger palette or extend one with additional colors. |
| 110 | +Refer to the link:/tutorials/gds-example[Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial] for an example on how |
| 111 | +to do the latter. |
| 112 | + |
| 113 | +==== By continuous color space |
| 114 | + |
| 115 | +To not use the default colors, we can provide a list of custom colors representing a range to the `color_nodes` method: |
| 116 | + |
| 117 | +[source, python] |
| 118 | +---- |
| 119 | +from neo4j_viz.colors import PropertyType |
| 120 | +
|
| 121 | +# VG is a VisualizationGraph object |
| 122 | +VG.color_nodes( |
| 123 | + property="centrality_score", |
| 124 | + [(255, 0, 0), (191, 64, 0), (128, 128, 0), (64, 191, 0), (0, 255, 0)] # From red to green |
| 125 | + color_space=ColorSpace.CONTINUOUS |
| 126 | +) |
| 127 | +---- |
| 128 | + |
| 129 | +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. |
| 130 | +Since we only provided five colors in the range, the granularity of the gradient will be limited to five steps. |
| 131 | + |
| 132 | +`palettable` and `matplotlib` are great libraries to use to create custom color gradients. |
| 133 | + |
| 134 | +== Sizing nodes |
| 135 | + |
| 136 | +Nodes can be given a size directly by providing them with a size field, upon creation. |
| 137 | +This can for example be done by passing a size as an integer to the `size` parameter of the link:{api-docs-uri}/node[Node] object. |
| 138 | + |
| 139 | +Alternatively, you can size nodes after a `VisualizationGraph` object has been created. |
| 140 | + |
| 141 | +=== The `resize_nodes` method |
| 142 | + |
| 143 | +By calling the link:{api-docs-uri}/visualization-graph/#neo4j_viz.VisualizationGraph.resize_nodes[`neo4j_viz.VisualizationGraph.resize_nodes()`] method, you can resize nodes by: |
| 144 | + |
| 145 | +* passing new nodes sizes as a dictionary `sizes`, mapping node IDs to sizes in pixels, or |
| 146 | +* providing a tuple of two numbers `node_radius_min_max`: minimum and maximum radii (sizes) in pixels to which the |
| 147 | + nodes will be scaled. |
| 148 | + |
| 149 | +Or you could provide both `sizes` and `node_radius_min_max`, in which case the dictionary will be used to first set |
| 150 | +the sizes of the nodes, and then the minimum and maximum values of the tuple will be subsequently used to scale the |
| 151 | +sizes to the provided range. |
| 152 | + |
| 153 | +If you provide only the `node_radius_min_max` parameter, the sizes of the nodes will be scaled such that the smallest |
| 154 | +node will have the size of the first value, and the largest node will have the size of the second value. |
| 155 | +The other nodes will be scaled linearly between these two values according to their relative size. |
| 156 | +This can be useful if node sizes vary a lot, or are all very small or very big. |
| 157 | + |
| 158 | +In the following example, we resize the node with ID 42 to have a size of 88 pixels, and then scales all nodes to have |
| 159 | +sizes between 5 and 20 pixels: |
| 160 | + |
| 161 | +[source, python] |
| 162 | +---- |
| 163 | +# VG is a VisualizationGraph object |
| 164 | +VG.resize_nodes(sizes={42: 88}, node_radius_min_max=(5, 20)) |
| 165 | +---- |
| 166 | + |
| 167 | +Note that means that also the node with ID 42 will be scaled to be between 5 and 20 pixels in size. |
| 168 | + |
| 169 | +== Pinning nodes |
| 170 | + |
| 171 | +Nodes can be pinned to their current position in the visualization, so that they will not be moved by the force-directed |
| 172 | +layout algorithm. |
| 173 | +This can be useful if you want to keep a node in a specific position, for example to highlight it. |
| 174 | + |
| 175 | +Nodes can be pinned directly upon creation. |
| 176 | +This can for example be done by passing `pinned=True` to the link:{api-docs-uri}/node[Node] object. |
| 177 | + |
| 178 | +Alternatively, you can toggle node pinning after a `VisualizationGraph` object has been created. |
| 179 | + |
| 180 | +=== The `toggle_nodes_pinned` method |
| 181 | + |
| 182 | +By calling the link:{api-docs-uri}/visualization-graph/#neo4j_viz.VisualizationGraph.toggle_nodes_pinned[`neo4j_viz.VisualizationGraph.toggle_nodes_pinned()`] method, you can toggle whether nodes should be |
| 183 | +pinned or not. |
| 184 | +This method takes dictionary that maps node IDs to boolean values, where `True` means that the node is pinned, and |
| 185 | +`False` means that the node is not pinned. |
| 186 | + |
| 187 | +In the following example, we pin the node with ID 1337 and unpin the node with ID 42: |
| 188 | + |
| 189 | +[source, python] |
| 190 | +---- |
| 191 | +# VG is a VisualizationGraph object |
| 192 | +VG.toggle_nodes_pinned(1337: True, 42: False)}) |
| 193 | +---- |
| 194 | + |
| 195 | +== Direct modification of nodes and relationships |
| 196 | + |
| 197 | +Nodes and relationships can also be modified directly by accessing the `nodes` and `relationships` fields of an |
| 198 | +existing `VisualizationGraph` object. |
| 199 | +These fields list of all the link:{api-docs-uri}/node[Nodes] and link:{api-docs-uri}/relationship[Relationships] in the graph, respectively. |
| 200 | + |
| 201 | +Each node and relationship has attributes that can be accessed and modified directly, as in the following example: |
| 202 | + |
| 203 | +[source, python] |
| 204 | +---- |
| 205 | +# VG is a VisualizationGraph object |
| 206 | +
|
| 207 | +# Modify the first node and fifth relationship |
| 208 | +VG.nodes[0].size = 10 |
| 209 | +VG.nodes[0].properties["height"] = 170 |
| 210 | +VG.relationships[4].caption = "BUYS" |
| 211 | +
|
| 212 | +# Set the coordinates for all nodes from an existing property |
| 213 | +for node in VG.nodes: |
| 214 | + node.x = node.properties.get("x") |
| 215 | + node.y = node.properties.get("y") |
| 216 | +
|
| 217 | +# Change the caption size for all relationships |
| 218 | +for relationship in VG.relationships: |
| 219 | + relationship.caption_size = 15 |
| 220 | +---- |
| 221 | + |
| 222 | +Any changes made to the nodes and relationships will be reflected in the next rendering of the graph. |
0 commit comments