three

three(data, graph_height=450, details_height=100, show_details=False, show_details_toggle_button=True, show_menu=False, show_menu_toggle_button=True, show_node=True, node_size_factor=1.0, node_size_data_source='size', use_node_size_normalization=False, node_size_normalization_min=5.0, node_size_normalization_max=75.0, node_drag_fix=False, node_hover_neighborhood=False, node_hover_tooltip=True, show_node_image=True, node_image_size_factor=1.0, show_node_label=True, show_node_label_border=True, node_label_data_source='id', node_label_size_factor=1.0, node_label_rotation=0.0, node_label_font='Arial', show_edge=True, edge_size_factor=1.0, edge_size_data_source='size', use_edge_size_normalization=False, edge_size_normalization_min=0.2, edge_size_normalization_max=5.0, edge_curvature=0.0, edge_hover_tooltip=True, show_edge_label=False, show_edge_label_border=True, edge_label_data_source='id', edge_label_size_factor=1.0, edge_label_rotation=0.0, edge_label_font='Arial', zoom_factor=0.75, large_graph_threshold=200, layout_algorithm_active=True, use_many_body_force=True, many_body_force_strength=- 70.0, many_body_force_theta=0.9, use_many_body_force_min_distance=False, many_body_force_min_distance=10.0, use_many_body_force_max_distance=False, many_body_force_max_distance=1000.0, use_links_force=True, links_force_distance=50.0, links_force_strength=0.5, use_x_positioning_force=False, x_positioning_force_strength=0.2, use_y_positioning_force=False, y_positioning_force_strength=0.2, use_z_positioning_force=False, z_positioning_force_strength=0.2, use_centering_force=True)[source]

Create an interactive graph visualization with HTML/CSS/JS based on 3d-force-graph.js.

The library 3d-force-graph.js uses three.js to create a 3d visualization in WebGL, hence the name for this function.

Note

This function has some known limitations in comparison to d3():

  • Nodes do not have a border. Edges do not come with labels. Accordingly, this function ignores following properties in the given data:

    • Graph metadata: node_border_color, node_border_size, edge_label_color, edge_label_size

    • Node metadata: border_color, border_size

    • Edge metadata: label_color, label_size

  • Node labels can not be rotated.

  • Edge labels are not available yet.

  • Hovering over a node does not support neighborhood highlighting yet.

  • The initial zoom factor can not be controlled yet.

  • If nodes are hidden, then node labels and node images are hidden too.

  • If an image is shown inside a node, no shape is drawn and therefore any value provided for node shape and color is ignored.

  • Static image export only works in raster image formats JPG and PNG, not in vector image format SVG.

Parameters

  • data (str, dict, graph object, list) – The input data needs to be in a custom format called gravis JSON Graph Format (gJGF).

    It can be provided in following ways:

    • str: A string in gJGF, or a filepath to a text file in gJGF.

    • dict: A dict adhering to gJGF.

    • graph object: An object from a supported graph library, which internally gets converted to gJGF.

    • list: Instead of a single graph, it is possible to provide a list of graphs. They can be all be of the same type, but a mix of different types is also accepted. The first graph in the list is shown after the visualization has loaded. The other graphs can be chosen in the data selection menu of the interactive visualization.

  • graph_height (int, float) – Height of the graph container in pixels (px).

  • details_height (int, float) – Height of the details container in pixels (px).

  • show_details (bool) – If True, the details container is shown on load, otherwise hidden.

  • show_details_toggle_button (bool) – If True, a button is shown that allows to toggle the visibility of the details container.

  • show_menu (bool) – If True, the menu container is shown on load, otherwise hidden.

  • show_menu_toggle_button (bool) – If True, a button is shown that allows to toggle the visibility of the menu container.

  • show_node (bool) – If True, nodes are shown on load, otherwise hidden.

  • node_size_factor (int, float) – A scaling factor that modifies node size.

  • node_size_data_source (str) – Name of the numerical node property that is used as source for node size on load.

  • use_node_size_normalization (bool) – If True, node sizes are normalized to lie in an interval between a chosen min and max value.

  • node_size_normalization_min (int, float) – Minimum value for node size if node size normalization is active.

  • node_size_normalization_max (int, float) – Maximum value for node size if node size normalization is active.

  • node_drag_fix (bool) – If True, the position of a node becomes fixed after dragging it, i.e. the layout algorithm does not change its position but the user can drag it again.

  • node_hover_neighborhood (bool) – If True, hovering a node leads to highlighting its neighborhood which consists of all incident edges and adjacent nodes. Caution: This feature is currently ignored in this plot and only here for API consistency.

  • node_hover_tooltip (bool) – If True, hovering a node leads to popping up a tooltip if the hover property in the metadata of this node contains a non-empty string or HTML text.

  • show_node_image (bool) – If True, node images are shown on load for all nodes whose image property in the metadata contains a valid image URL from which an image can be fetched.

  • node_image_size_factor (int, float) – A scaling factor that modifies node image size.

  • show_node_label (bool) – If True, node labels are shown on load, otherwise hidden.

  • show_node_label_border (bool) – If True, node labels have a small border in the color of the background to better separate the text from other visual elements like edges or nodes.

  • node_label_data_source (str) – Name of the node property that is used as source for node label text on load.

  • node_label_size_factor (int, float) – A scaling factor that modifies node label size.

  • node_label_rotation (int, float) – An angle that modifies node label orientation. Caution: This feature is currently ignored in this plot and only here for API consistency.

  • node_label_font (str) – Name of the font that is used for node labels.

  • show_edge (bool) – If True, edges are shown on load, otherwise hidden.

  • edge_size_factor (int, float) – A scaling factor that modifies edge size (=edge width).

  • edge_size_data_source (str) – Name of the edge property that is used as source for edge size on load.

  • use_edge_size_normalization (bool) – If True, edge sizes are normalized to lie in an interval between a chosen min and max value.

  • edge_size_normalization_min (int, float) – Minimum value for edge size if node size normalization is active.

  • edge_size_normalization_max (int, float) – Maximum value for edge size if node size normalization is active.

  • edge_curvature (int, float) – A factor that modifies edge curvature, where 0.0 means straight lines.

  • edge_hover_tooltip (bool) – If True, hovering an edge leads to popping up a tooltip if the hover property in the metadata of this edge contains a non-empty string or HTML text.

  • show_edge_label (bool) – If True, edge labels are shown on load, otherwise hidden. Caution: This feature is currently ignored in this plot and only here for API consistency.

  • show_edge_label_border (bool) – If True, edge labels have a small border in the color of the background to better separate the text from other visual elements like edges or nodes. Caution: This feature is currently ignored in this plot and only here for API consistency.

  • edge_label_data_source (str) – Name of the edge property that is used as source for edge label text on load. Caution: This feature is currently ignored in this plot and only here for API consistency.

  • edge_label_size_factor (int, float) – A scaling factor that modifies edge label size. Caution: This feature is currently ignored in this plot and only here for API consistency.

  • edge_label_rotation (int, float) – An angle that modifies edge label orientation. Caution: This feature is currently ignored in this plot and only here for API consistency.

  • edge_label_font (str) – Name of the font that is used for edge labels.

  • zoom_factor (int, float) – Factor that modifies how close the camera is to the drawing area on load. Caution: This feature is currently ignored in this plot and only here for API consistency.

  • large_graph_threshold (int, float) – Number that determines from when on a network is considered to be large, which means that before visualizing it an initial layout is calculated without moving anything.

  • layout_algorithm_active (bool) – If True, the layout algorithm is active on load and leads to movement, otherwise inactive.

  • use_many_body_force (bool) – If True, many body force is active in the layout algorithm. This force acts between any pair of nodes but can be restricted to only act on nodes within a certain distance.

  • many_body_force_strength (int, float) – Number that determines the strength of the force. It can be positive to cause attraction or negative (usual case) to cause repulsion between nodes.

  • many_body_force_theta (int, float) – Number that determines the accuracy of the Barnes–Hut approximation of the many-body simulation where nodes are grouped instead of treated individually to improve performance.

  • use_many_body_force_min_distance (bool) – If True, a minimum distance between nodes is used in the many-body force calculation. This effectively leads to an upper bound on the strength of the force between any two nodes and avoids instability.

  • many_body_force_min_distance (int, float) – Number that determines the minimum distance between nodes over which the many-body force is active.

  • use_many_body_force_max_distance (bool) – If True, a maximum distance between nodes is used in the many-body force calculation. This can improve performance but results in a more localized layout.

  • many_body_force_max_distance (int, float) – Number that determines the maximum distance between nodes over which the many-body force is active.

  • use_links_force (bool) – If True, link force is active in the layout algorithm. This force acts between pairs of nodes that are connected by an edge. It pushes them together or apart in order to come close to a certain distance between connected nodes.

  • links_force_distance (int, float) – Number that determines the preferred distance between connected nodes.

  • links_force_strength (int, float) – Number that determines the strength of the links force.

  • use_collision_force (bool) – If True, collision force is active in the layout algorithm. This force treats nodes as circles instead of points and acts on pairs of nodes that overlap in order to push them apart.

  • collision_force_radius (int, float) – Number that determines the radius of the circle around each node.

  • collision_force_strength (int, float) – Number that determines the strength of the force.

  • use_x_positioning_force (bool) – If True, x-positioning force is active in the layout algorithm. This force modifies the x position of each node towards 0.0, effectively pushing them towards the yz-plane.

  • x_positioning_force_strength (int, float) – Number that indicates the strength of the force.

  • use_y_positioning_force (bool) – This force modifies the y position of each node towards 0.0, effectively pushing them towards the xz-plane.

  • y_positioning_force_strength (int, float) – Number that indicates the strength of the force.

  • use_z_positioning_force (bool) – If True, z-positioning force is active in the layout algorithm. This force modifies the z position of each node towards 0.0, effectively pushing them towards the xy-plane.

  • z_positioning_force_strength (int, float) – Number that indicates the strength of the force.

  • use_centering_force (bool) – This force attracts each node towards the center of the coordinate system at (0, 0, 0) to keep the graph in the display area. It may lead to unexpected repulsion effects if all nodes are fixed and then a single one is released by dragging it.

Returns

A Figure object that can be used for displaying or exporting the plot.

References