Now you can create beautiful and powerful network mapping applications entirely in Python, no JavaScript required! Dash Cytoscape introduces the latest additions to our ever-growing family of Dash components. Built on top of Cytoscape.js, the Dash Cytoscape library brings Cytoscape’s capabilities into the Python ecosystem. Best of all, it’s open-sourced under an MIT license and available today on PyPI. Simply run pip install dash-cytoscape
to get started! You can also find the complete source code in the Github repository, and view the documentation in the Dash Cytoscape User Guide.
In this post, we will:
- Provide some background on the Cytoscape project.
- Show you how Dash’s declarative layout, elements and styling help you build an intuitive and intelligent application.
- Explain how Dash callbacks power your application’s interactivity.
- Introduce you to the customizable styling available with Dash Cytoscape, including an online style editor that you can use as an interactive playground for your style and layout ideas.
- Illustrate how to visualize large social networks using Dash Cytoscape.
- Share our vision of integrating with other Python bioinformatics and computational biology tools.
Standing on the shoulders of giants
This project would not be possible without the amazing work done by the Cytoscape Consortium, an alliance of universities and industry experts working to make network visualization accessible for everyone. The Cytoscape project has been available for some time both as Java software and as a JavaScript API; they are maintained in their Github organization. The library can also be used in React through the recently released react-cytoscapejs library, which allows the creation of Cytoscape components that can be easily integrated in your React projects. Dash Cytoscape extends the latter by offering a Pythonic, callbacks-ready, declarative interface that is ready to be integrated in your existing Dash projects, or used as a standalone component to interactively display your graphs.
A familiar and declarative interface
Powerful built-in layouts
Picking the right layout for your graph is essential to helping viewers understand your data. This highly customizable feature is now fully available in Dash, and can be easily specified using a dictionary.
The original Cytoscape.js includes many great layouts for displaying your graph in the way it should be viewed. You can choose to display your nodes in a grid, in a circle, as a tree, or using physics simulations. In fact, you can even choose the exact number of rows or columns for your grid, the radius of your circle, or the temperature and cooling factor of your simulation. For example, to display your graph with a fixed grid of 25 rows, you can simply declare:
dash_cytoscape.Cytoscape(
id='cytoscape',
elements=[...],
layout={
'name': 'grid',
'rows': 25
}
)
Intuitive and clear element declaration
Creating nodes with Dash Cytoscape is straightforward: You make a dictionary in which you specify the data associated with the node (i.e., the ID and the display label of your node), and, optionally, the default position. To add an edge between two nodes, you give the ID of the source node and the target node, and specify how you want to label the nodes. Group all elements (nodes and edges) inside a list, and you are ready to go! In a nutshell, here’s how you would create a basic graph with two nodes:
dash_cytoscape.Cytoscape(
id='cytoscape',
layout={'name': 'preset'},
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'}}
]
)
If you already have an adjacency list, you can easily format the data to be accepted by Cytoscape, and display in your browser with about 70 lines of code:
Beautiful and customizable styling
Cytoscape provides a range of styling options through a familiar CSS-like interface. You get to specify the exact color, pixel size and opacity of your elements. You can choose the shape of your nodes from over 20 options, including circular, triangular, and rectangular, as well as non-traditional content for your nodes (e.g. displaying an image by adding a URL, or adding a pie chart inside a circular node). The edges can be curved or straight, and it is even possible to add arrows at the middle or end-point. To add a style to your stylesheet, you simply need to specify which group of elements you want to modify with a selector, and input the properties you want to modify as keys. For example, if you want nodes 15 pixels wide by 15 pixels high, styled opaque with a custom gray color, you add the following dictionary to your stylesheet:
{
'selector': 'node',
'style': {
'opacity': 0.9,
'height': 15,
'width': 15,
'background-color': '#222222'
}
}
The selector can be a type of element (i.e., a node or edge) or be a certain class (which you can specify). It can also have a certain ID or match certain conditions (e.g., node height is over a certain threshold).
Using the online style editor
In order to help the community get acquainted with the library, we created an online style editor application that lets you interactively modify the stylesheet and layout of sample graphs. This tool will help you learn how to use the style properties and quickly prototype new designs. Best of all, it displays the stylesheet in a JSON format so that you can simply copy and paste it into your Cytoscape app! Try it out here.
Familiar Dash callbacks
Dash Callbacks are used to make your Dash apps interactive. They are fired whenever the input you define is modified, such as when the user clicks a button or drags a slider inside your UI. The callback functions are computed on the server side, which enables the use of optimized and heavy-duty libraries such as Scipy and Numpy.
Use Dash callbacks with dash-cytoscape
to update the underlying elements
, the layout
, or the stylesheet
of the graph. For more, see our documentation chapter on callbacks.
Additionally, you can use a collection of user-interaction events as an input to your callbacks. They are triggered whenever the user interacts with the graph itself; in other words, when they hover, tap, or select an element or a group of elements. You can choose to input the entire JSON description of the element object (including its connected edges, its parents, its children, and the complete stylesheet), or only the data contained withing the object. To see what is being output, you can assign the following simple callback to your graph:
@app.callback(Output('html-div-output', 'children'),
[Input('cytoscape', 'tapNodeData')])
def displayTapNodeData(data):
return json.dumps(data, indent=2)
This will output the formatted JSON sent by your Cytoscape
component into an html.Div
field. To read more about event callbacks and how to use them for user interaction, check out our user guide chapter on Cytoscape events.
Try out the demo here. You can find the source code in usage-events.py.
Visualizing large social networks
One way you might want to use Dash Cytoscape is to visualize large social networks. Visualizing large network graphs with thousands or millions of nodes can quickly become overwhelming. In this example, we use Dash Cytoscape with Dash callbacks to interactively explore a network by clicking on nodes of interest.
This graph displays the Google+ social social network from the Stanford Large Network Dataset collection.
Dynamically expand your graphs
Start with a single node (representing a Google+ user) and explore all of its outgoing (i.e. all of the users they are following) or incoming edges (i.e. all of their followers).
Try out the demo here. You can find the source code in usage-elements.py.
Fast and reactive styling
When mapping large networks, strategic styling can help enhance understanding of the data. Leveraging the rendering speed and scalability of Cytoscape.js, we can easily create callbacks that update the stylesheet of large graphs using Dash components such as dropdown menus and input fields, or that update upon clicking a certain node.
In this example, we display 750 edges of Google+ users and focus on a particular user by clicking on a specific node. The callback updates the stylesheet by appending a selector that colors the selected ID in purple, and the parents and children in different colors that you specify. Our user guide chapter on styling covers the basics to get you started.
Try out the demo here. You can find the source code in usage-stylesheet.py.
Integrating with other libraries
The release of Dash Cytoscape brings the capabilities of Cytoscape.js into the Python world, opening up the possibility of integrating with a wide range of excellent graph and network libraries in Python.
For example, Biopython is a collection of open-source bioinformatics Python tools. In around 100 lines of code, we wrote a parser capable of generating cytoscape elements from Biopython’s Phylo objects. The parser is generic enough that it can be directly integrated in your bioinformatics workflow, and enables you to quickly create interactive phylogeny apps, all in a familiar and pythonic environment. View the phylogeny demo in the docs.
Dash Cytoscape is the first step to provide deeper Dash integration with Biopython and well known graph libraries such as NetworkX and Neo4j.
To wrap up
Today, Plotly.py is widely used for exploratory analysis and Dash is a powerful analytics solution in the scientific community. Recently, researchers published a paper on CRISPR in Nature and built their machine learning platform using Dash. There is an obvious need for powerful and user-friendly visualizations tools in Python, and network visualization is not an exception. We are planning to fully leverage the resources available in Python to make Cytoscape useful for more network scientists and computational biologists, as well as the broader scientific community.
Dash Cytoscape is a work in progress, and we encourage you to help us improve it and make it accessible to more people. Contribute to documentation, improve its compatibility with other libraries, or add functionalities that make it easier to use. Head over to our GitHub repository to get started!
We are currently working on multiple improvements, including support for NetworkX, integration with Biopython, and object-oriented declaration for elements, styles and layouts. Check out those issues to keep track of the progress, or to support us through your contributions!
If you wish to use this library in a commercial setting, please see our on-premise offerings, which not only guarantee technical support, but also support our open-source initiatives, including Dash Cytoscape itself.