Skip to content

Commit 6406a2f

Browse files
adamnschadamnsch
committed
Add Adjusting docs
1 parent 84ebf95 commit 6406a2f

3 files changed

Lines changed: 152 additions & 5 deletions

File tree

‎docs/source/adjusting.rst‎

Lines changed: 142 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,145 @@
11
Adjusting the visualization
22
===========================
33

4-
In this section, we will discuss how to modify an existing ``VisualizationGraph`` object to adjust the visualization.
4+
Once created, a :doc:`VisualizationGraph object <./api-reference/visualization-graph>` can be modified in various ways
5+
to adjust what the visualization looks like the next time you render it.
6+
In this section we will discuss how to color, size, and pin nodes, as well as how to directly modify nodes and
7+
relationships of existing ``VisualizationGraph`` objects.
8+
9+
If you have not yet created a ``VisualizationGraph`` object, please refer to one of the following sections:
10+
11+
* :doc:`Getting started <./getting-started>` for creating a visualization graph from scratch using ``neo4j-viz``
12+
primitives like :doc:`Node <./api-reference/node>` and :doc:`Relationship <./api-reference/relationship>` and
13+
:doc:`VisualizationGraph <./api-reference/visualization-graph>` directly. Or
14+
* :doc:`Integration with other libraries <./integration>` for importing data from a Pandas DataFrame or Neo4j GDS
15+
projection.
16+
17+
18+
Coloring nodes
19+
--------------
20+
21+
Nodes can be colored directly by providing them with a color property, upon creation.
22+
This can for example be done by passing a color as a string to the ``color`` parameter of the
23+
:doc:`Node <./api-reference/node>` object.
24+
25+
Alternatively, you can color nodes based on a property (field) of the nodes after a ``VisualizationGraph`` object has been
26+
created.
27+
28+
29+
The ``color_nodes`` method
30+
~~~~~~~~~~~~~~~~~~~~~~~~~~
31+
32+
By calling the :meth:`neo4j_viz.VisualizationGraph.color_nodes` method, you can color nodes based on a
33+
node property (field).
34+
This method will give a distinct color (if possible) to each unique value of the node ``property`` that you provide as
35+
the first positional argument.
36+
37+
By default the Neo4j color palette that works for both light and dark mode will be used.
38+
If you want to use a different color palette, you can pass a dictionary or iterable of colors as the ``colors``
39+
parameter.
40+
You can for example use the color palettes from the `palettable library <https://jiffyclub.github.io/palettable/>`_ as in
41+
the following example:
42+
43+
.. code-block:: python
44+
45+
from palettable.wesanderson import Moonrise1_5
46+
47+
# VG is a VisualizationGraph object
48+
VG.color_nodes("caption", Moonrise1_5.colors)
49+
50+
In this case, all nodes with the same caption will get the same color.
51+
52+
If there are fewer colors that unique values for the node ``property`` provided, the colors will be reused in a cycle.
53+
To avoid that, you could use another palette or extend one with additional colors. Please refer to the
54+
:doc:`Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial <./tutorials/gds-nvl-example>` for an example on how
55+
to do the latter.
56+
57+
If some nodes already have a ``color`` set, you can choose whether or not to override it with the ``override``
58+
parameter.
59+
60+
61+
Sizing nodes
62+
--------------
63+
64+
Nodes can be given a size directly by providing them with a size property, upon creation.
65+
This can for example be done by passing a size as an integer to the ``size`` parameter of the
66+
:doc:`Node <./api-reference/node>` object.
67+
68+
Alternatively, you can size nodes after a ``VisualizationGraph`` object has been created.
69+
70+
71+
The ``resize_nodes`` method
72+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
73+
74+
By calling the :meth:`neo4j_viz.VisualizationGraph.resize_nodes` method, you can resize nodes by:
75+
76+
* passing new nodes sizes as a dictionary ``sizes``, mapping node IDs to sizes in pixels, or
77+
* providing a tuple of two numbers ``node_radius_min_max``: minimum and maximum radii (sizes) in pixels to which the
78+
nodes will be scaled.
79+
80+
Or you could provide both ``sizes`` and ``node_radius_min_max``, in which case the dictionary will be used to first set
81+
the sizes of the nodes, and then the minimum and maximum values of the tuple will be subsequently used to scale the
82+
sizes to the provided range.
83+
84+
If you provide only the ``node_radius_min_max`` parameter, the sizes of the nodes will be scaled such that the smallest
85+
node will have the size of the first value, and the largest node will have the size of the second value.
86+
The other nodes will be scaled linearly between these two values according to their relative size.
87+
This can be useful if node sizes vary a lot, or are all very small or very big.
88+
89+
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
90+
sizes between 5 and 20 pixels:
91+
92+
.. code-block:: python
93+
94+
# VG is a VisualizationGraph object
95+
VG.resize_nodes(sizes={42: 88}, node_radius_min_max=(5, 20))
96+
97+
Please note that means that also the node with ID 42 will be scaled to be between 5 and 20 pixels in size.
98+
99+
100+
Pinning nodes
101+
-------------
102+
103+
Nodes can be pinned to their current position in the visualization, so that they will not be moved by the force-directed
104+
layout algorithm.
105+
This can be useful if you want to keep a node in a specific position, for example to highlight it.
106+
107+
Nodes can be pinned directly upon creation.
108+
This can for example be done by passing ``pinned=True`` parameter of the :doc:`Node <./api-reference/node>` object.
109+
110+
Alternatively, you can toggle node pinning after a ``VisualizationGraph`` object has been created.
111+
112+
113+
The ``toggle_nodes_pinned`` method
114+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115+
116+
By calling the :meth:`neo4j_viz.VisualizationGraph.toggle_nodes_pinned` method, you can toggle whether nodes should be
117+
pinned or not.
118+
This method takes dictionary that maps node IDs to boolean values, where ``True`` means that the node is pinned, and
119+
``False`` means that the node is not pinned.
120+
121+
In the following example, we pin the node with ID 1337 and unpin the node with ID 42:
122+
123+
.. code-block:: python
124+
125+
# VG is a VisualizationGraph object
126+
VG.toggle_nodes_pinned(1337: True, 42: False)})
127+
128+
129+
Direct modification of nodes and relationships
130+
----------------------------------------------
131+
132+
Nodes and relationships can also be modified directly by accessing the ``nodes`` and ``relationships`` attributes of an
133+
existing ``VisualizationGraph`` object.
134+
These attributes list of all the :doc:`Nodes <./api-reference/node>` and
135+
:doc:`Relationships <./api-reference/relationship>` in the graph, respectively.
136+
137+
Each node and relationship has attributes that can be accessed and modified directly, as in the following example:
138+
139+
.. code-block:: python
140+
141+
# VG is a VisualizationGraph object
142+
VG.nodes[0].size = 10
143+
VG.relationships[4].caption = "BUYS"
144+
145+
Any changes made to the nodes and relationships will be reflected in the next rendering of the graph.

‎docs/source/api-reference/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@
33
You can adapt this file completely to your liking, but it should at least
44
contain the root `toctree` directive.
55
6-
API Reference
6+
API reference
77
=====================================================
88

9-
This is an API reference for the `neo4j-viz` library.
9+
This is an API reference for the ``neo4j-viz`` library.
1010

1111

1212
.. toctree::

‎docs/source/integration.rst‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,11 @@ The ``from_dfs`` method takes two mandatory positional parameters:
3333

3434
``from_dfs`` also takes an optional property, ``node_radius_min_max``, can be used (and is used by default) to scale
3535
the node sizes for the visualization.
36-
It is a tuple of two floats, representing the radii (sizes) in pixels of the smallest and largest nodes respectively in
36+
It is a tuple of two numbers, representing the radii (sizes) in pixels of the smallest and largest nodes respectively in
3737
the visualization.
38+
The node sizes will be scaled such that the smallest node will have the size of the first value, and the largest node
39+
will have the size of the second value.
40+
The other nodes will be scaled linearly between these two values according to their relative size.
3841
This can be useful if node sizes vary a lot, or are all very small or very big.
3942

4043

@@ -95,8 +98,11 @@ For example, these properties could be used to color the nodes, or give captions
9598

9699
The last optional property, ``node_radius_min_max``, can be used (and is used by default) to scale the node sizes for the
97100
visualization.
98-
It is a tuple of two floats, representing the radii (sizes) in pixels of the smallest and largest nodes respectively in
101+
It is a tuple of two numbers, representing the radii (sizes) in pixels of the smallest and largest nodes respectively in
99102
the visualization.
103+
The node sizes will be scaled such that the smallest node will have the size of the first value, and the largest node
104+
will have the size of the second value.
105+
The other nodes will be scaled linearly between these two values according to their relative size.
100106
This can be useful if node sizes vary a lot, or are all very small or very big.
101107

102108

0 commit comments

Comments
 (0)