Dash Cytoscape

CyLeaflet is a Dash component included with Dash Cytoscape that adds a geospatial mapping layer to Cytoscape graphs. It allows you to render nodes at specific geographic locations by specifying latitude and longitude in the node data.

How it works

CyLeaflet uses the Dash All-in-One Component pattern. It is a composite component that wraps several underlying components to synchronize a Cytoscape canvas with a Leaflet map canvas:

1. Dash Cytoscape: Handles the graph rendering.
2. Dash Leaflet: Handles the geospatial map layer.
3. dcc.Store: Holds the element data used for coordinate transformation.
4. html.Divs: Provide styling to align the Cytoscape canvas exactly on top of the Leaflet canvas.
5. Clientside Callbacks: Link the components together to ensure synchronization.

Important: Updating Graph Elements

You cannot update Cytoscape nodes directly by modifying the elements property of the component. Doing so skips a critical transformation step where lat and lon coordinates are converted into the (x, y) canvas positions required to align with the map.

To update the graph, you must update the data property of the internal dcc.Store instance. The component uses a callback to transform these coordinates and then update the Cytoscape elements property automatically.

When a user interacts with elements, Dash Cytoscape provides read-only data via tapNode, tapNodeData, tapEdge, and tapEdgeData.

tapNode / tapEdge (Full Objects): Contains complete element dictionaries including data, position, style, classes, and relationship data (like ancestorsData or childrenData for nodes).

tapNodeData / tapEdgeData (Data Dictionaries): Contains only the data dictionary associated with the tapped element.

Other Selection/Hover Data:

• selectedNodeData (array): Data dictionaries of all currently selected nodes.
• selectedEdgeData (array): Data dictionaries of all currently selected edges.
• mouseoverNodeData (object): Data dictionary of the currently hovered node.
• mouseoverEdgeData (object): Data dictionary of the currently hovered edge.
• clearOnUnhover (bool): If true, mouseover data is cleared when the user stops hovering.

To create a basic network visualization, use the dash_cytoscape.Cytoscape component. You define the network using an elements list containing dictionaries for nodes and edges. Nodes typically include data (with id and label) and an optional position. Edges include data with source and target IDs. The layout property determines how elements are positioned (e.g., 'preset').

import dash
import dash_cytoscape as cyto
from dash import html

app = dash.Dash(__name__)
app.layout = html.Div([
    cyto.Cytoscape(
        id='cytoscape',
        elements=[
            {'data': {'id': 'one', 'label': 'Node 1'}, 'position': {'x': 50, 'y': 50}},
            {'data': {'id': 'two', 'label': 'Node 2'}, 'position': {'x': 200, 'y': 200}},
            {'data': {'source': 'one', 'target': 'two','label': 'Node 1 to 2'}}
        ],
        layout={'name': 'preset'}
    )
])

if __name__ == '__main__':
    app.run(debug=True)

The layout property is a dictionary specifying how to position elements in your graph. The name key is required.

Available Default Layouts:

• random: Randomly assigns positions.
• preset: Uses the position key in element dictionaries.
• circle: Single-level circle.
• concentric: Multi-level circle.
• grid: Square grid (can be configured with rows and cols).
• breadthfirst: Tree structure using BFS (can be configured with roots).
• cose: Force-directed physics simulation.

External Layouts: To use external layouts, you must call dash_cytoscape.load_extra_layouts() in your Python code before initializing the Dash app. Available external layouts include:

• cose-bilkent, fcose, cola, euler, spread, dagre, klay.

Common Layout Options (accepted by all):

• fit (bool): Whether to render nodes to fit the canvas.
• padding (number): Padding around the sides of the canvas.
• animate (bool): Whether to animate position changes.
• animationDuration (number): Duration of animation in milliseconds.
• boundingBox (object): Constrains layout to an area using {x1, y1, x2, y2} or {x1, y1, w, h}.

The contextMenu prop allows you to define a custom right-click menu. Each item in the list should be a dictionary with:

• id: A unique identifier for the menu item.
• label: The text displayed in the menu.
• tooltipText: Optional text for a tooltip.
• availableOn: An array specifying where the item appears. Valid values are 'node', 'edge', or 'canvas'.
• onClick: (Optional) A predefined string for default actions: 'remove', 'add_node', or 'add_edge'.
• onClickCustom: (Optional) A string referring to a custom JavaScript function defined in the window.dashCytoscapeFunctions namespace.

context_menu = [
    {
        'id': 'remove_item',
        'label': 'Remove Element',
        'onClick': 'remove',
        'availableOn': ['node', 'edge']
    },
    {
        'id': 'custom_action',
        'label': 'My Custom Action',
        'onClickCustom': 'myCustomJsFunction',
        'availableOn': ['canvas']
    }
]