Dash Cytoscape

Common errors

• Dash Cytoscape callbacks not firing

  cause The callback function was defined after `app.run_server()` or `app.run()` in the script.
  fix Move all `@app.callback` definitions and their functions to appear before the `if __name__ == '__main__': app.run_server(debug=True)` block.

• TypeError: Cannot read properties of undefined (reading 'length') when elements is not specified

  cause The `elements` property of the `cyto.Cytoscape` component was not provided or was `None`.
  fix Ensure the `elements` property is always a list of nodes and edges, even if empty (`elements=[]`). This issue was fixed in `dash-cytoscape` version 0.1.1 but can still occur with incorrect usage.

• Graph showing incorrect connections or overlapping nodes after update, networks fused together based on common ID

  cause When updating the `elements` property, new nodes or edges were introduced with IDs that already existed in the previous graph state. The underlying Cytoscape.js library can conflate elements with identical IDs, leading to unexpected graph structures.
  fix Ensure all node and edge IDs are unique across all elements present in the graph at any given time, especially when dynamically modifying or replacing the graph content.

• Dash app crashes without error message or restarts frequently when using Cytoscape component.

  cause This can sometimes occur with complex or very large graphs, potentially related to memory usage or issues within the underlying JavaScript rendering. It might also be related to specific environment configurations or resource limitations.
  fix Try simplifying the graph, optimizing `stylesheet` definitions, or reducing the number of `elements`. Consider restarting the Python environment or the operating system. Check browser developer console for any JavaScript errors. For very large graphs, consider server-side rendering or pagination if applicable.

Warnings

• breaking Support for Python 3.7 and below was dropped in `dash-cytoscape` version 1.0.0. The new minimum Python version is 3.8.
  Fix: Upgrade Python environment to 3.8 or newer. Use `pip install 'dash-cytoscape<1.0.0'` for older Python versions.
• gotcha When dynamically updating the graph with new `elements` (nodes and edges), ensure that node and edge IDs are unique. Reusing IDs can lead to networks fusing or unexpected behavior due to the underlying Cytoscape.js library not properly cleaning the object.
  Fix: Generate unique IDs for all nodes and edges across different states or updates of the graph, for example, by adding a prefix or using UUIDs.
• gotcha Callbacks must be defined *before* `app.run_server()`. If a `@app.callback` decorator and its associated function are placed after `app.run_server()`, the callback will not be registered and will not fire.
  Fix: Ensure all `@app.callback` definitions and their corresponding functions are placed in the main script *before* the `if __name__ == '__main__': app.run_server(debug=True)` block.
• gotcha When modifying `elements` inside a callback, you should return a *new* list/dictionary of elements rather than mutating the original object passed as `State`. Direct mutation of objects received via `State` can lead to update cycles being broken or inconsistent behavior.
  Fix: Create a copy of the `elements` list/dictionary (`new_elements = elements[:]` or `new_elements = list(elements)`) and modify the copy before returning it from the callback.
• deprecated The `dash_html_components` and `dash_core_components` imports were removed from `install_requires` in older versions. While still usable, components like `html.Div` are now typically imported directly from `dash`.
  Fix: Update imports from `import dash_html_components as html` to `from dash import html` (and similarly for `dcc`).

Install

• pip install dash-cytoscape Base Installation
• pip install dash-cytoscape[leaflet] With CyLeaflet for maps

Imports

• Cytoscape
  wrong:

  import dash_cytoscape
  from dash import Dash, html # then use dash_cytoscape.Cytoscape

  correct:

  import dash_cytoscape as cyto
  from dash import Dash, html

  The convention is to import `dash_cytoscape` as `cyto` for brevity and consistency with examples.
• load_extra_layouts

  import dash_cytoscape as cyto
  cyto.load_extra_layouts()

  Required to enable external layouts (e.g., COSE-Bilkent, FCose) and SVG image generation.

Quickstart

This quickstart creates a simple Dash application displaying a two-node, one-edge graph. It demonstrates basic `Cytoscape` component usage with `elements`, `layout`, and `stylesheet` properties. Remember to run `pip install dash` first if not already installed.

from dash import Dash, html
import dash_cytoscape as cyto

app = Dash(__name__)

app.layout = html.Div([
    cyto.Cytoscape(
        id='cytoscape-two-nodes',
        layout={'name': 'preset'},
        style={'width': '100%', 'height': '400px'},
        elements=[
            {'data': {'id': 'one', 'label': 'Node 1'}, 'position': {'x': 75, 'y': 75}},
            {'data': {'id': 'two', 'label': 'Node 2'}, 'position': {'x': 200, 'y': 200}},
            {'data': {'source': 'one', 'target': 'two', 'label': 'Node 1 to 2'}}
        ],
        stylesheet=[
            {
                'selector': 'node',
                'style': {
                    'background-color': '#BFD7B5',
                    'label': 'data(label)'
                }
            },
            {
                'selector': 'edge',
                'style': {
                    'line-color': '#A3C4BC',
                    'label': 'data(label)'
                }
            }
        ]
    )
])

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