Keywords
Network, import, export, format conversion, attribute conversion, data visualization, Cytoscape, GraphViz, DOT
This article is included in the Cytoscape gateway.
This article is included in the Bioinformatics gateway.
Network, import, export, format conversion, attribute conversion, data visualization, Cytoscape, GraphViz, DOT
Cytoscape1 is a popular tool for visualizing and analyzing networks used in scientific and commercial analysis, most commonly in bioinformatics. It enables users to discover and load curated and uncurated networks representing molecular and genomic interactions, load ad-hoc or custom networks, and share networks that others have created. Once networks are loaded, users can manually annotate a network or automatically integrate annotations using a number of algorithms and databases. Users can perform a number of graph-oriented and semantic-aware analyses ranging from graph statistics to motif and cluster discovery to upstream and downstream structural and functional inferences. Users can also perform a number of complex graph filtering and layout operations to drive and focus the semantic understanding of network interactions and structure.
Even beyond analysis and layout, users commonly derive and demonstrate network meaning by using visual cues to distinguish relationships and attributes. For this, Cytoscape provides a visual style system that enables users to paint nodes and edges using color, border thickness, size, fonts, arrows, and other devices.
Much of the power and functionality of Cytoscape is delivered as apps available in the Cytoscape App Store (http://apps.cytoscape.org). The store contains nearly 300 apps that provide a range of functionality from file import/export to analysis to visualization and publishing. Based on the success of the combination of Cytoscape core and downloadable apps, Cytoscape is downloaded approximately 14,000 times per month worldwide and is started approximately 3,000 times each working day. As of 2015, Cytoscape has been cited in 700 academic peer-reviewed papers per year.
While Cytoscape is the dominant network analysis and visualization platform in bioinformatics, it is not the only platform. To support interoperability with a number of network-oriented workflows and applications, Cytoscape offers a number of natively supported file import/export modules, and leverages a number of them that are available as apps in the App Store. Some of these file formats2 do not include visual information, such as SIF (.sif) and NNF (.nnf), whereas others do (e.g., GraphML’s .graphml and XGMML’s .xgmml formats).
Graphviz is a popular, well-established graph visualization application that produces a DOT (.dot, .gv) file containing graph structure, layout, and styling information, but for which there is no input/export module for Cytoscape. DOT files adhere to the DOT language syntax (http://www.graphviz.org/doc/info/lang.html). In comparison to XGMML and GraphML, Graphviz and its DOT language syntax define more visual attributes and support more visual features, such as edges composed of colored segments and single edges that are represented as multiple edges of different colors. Some of the DOT attributes can be used only by the Graphviz software because they specify parameters for the layout algorithms that the software uses.
DOT files contain a number of visual attributes that map well to Cytoscape visualization functionality, and vice versa. However, incompatibilities do exist where some Cytoscape features cannot be represented in DOT, or where DOT represents some features that cannot be realized in Cytoscape. These incompatibilities are described in "Conversion details" section.
Note that GraphViz is one of several applications that produces or consumes DOT files, but it is by far the most commonly used. In this paper, we use “DOT file/network” and “GraphViz file/network” interchangeably.
We present dot-app as a Cytoscape app that implements both the import and export of graphs encoded in DOT files. We describe the operation of dot-app; how dot-app maps Cytoscape networks to DOT networks and vice versa; issues that arise because of incompatibilities between the Cytoscape and DOT network models; representative use cases; and prospects for future work.
A Graphviz network can be imported in two ways: from the welcome screen (via the From Network File… button), from the menu (“File->Import->Network->File…”), or from the toolbar (by clicking the “Import Network from File” button).
Users are presented with a file browser dialog titled “Network file to load” (as in Figure 1). The user is able to filter the dialog to display only Graphviz files by selecting Graphviz files (*.gv, *.dot) from the drop-down menu for “Files of Type.” Note that no difference exists between a Graphviz file with an extension of .dot and a Graphviz file with an extension of .gv. However, the .gv extension is preferred because versions of Microsoft Word also use the .dot extension (https://marc.info/?l=graphviz-devel&m=129418103126092). From this point, importing a Graphviz network is the same as importing a network from any of Cytoscape's accepted file formats. Those steps are detailed in the Cytoscape User Manual (http://manual.cytoscape.org/en/stable/).
To export a Cytoscape network as a GraphViz network, use the “Export -> Network and View” menu. (Using "Export -> Network" is also possible, but this will result in a Graphviz file that contains no visual information and a notification to use "Export -> Network and View" instead.)
Selecting “GraphViz files (*.dot,*.gv)” in the Export dialog launches dot-app and prompts the user to choose from three options, as shown in Figure 2 below. The purposes of these options are explained in the following section.
Pick edge style. Cytoscape provides edge-routing capabilities that cannot be conserved during the export process, so dot-app provides three edge routing options: “Straight segments,” “Curved segments” and “Curved segments routed around nodes.” These options change the value of the “splines” attribute that appears in the exported Graphviz file. The Graphviz file for a network exported from Cytoscape is shown below, and the attribute modified by the “Pick Edge Style” option is underlined and in bold. Figure 3, Figure 4, and Figure 5 depict pictures of the network with each edge style chosen.
graph example {
bgcolor = "#FFFFFFFF"
splines = "false"
outputorder = "edgesfirst"
esep = "0"
pad = "2"
node [label = "",penwidth = "0.000000",height = "0.486111",width = "1.041667",tooltip = "",color = "#CCCCCCFF",fillcolor = "#89D0F5FF",shape = "rectangle",style = "solid,rounded,filled",fontname = "SansSerif.plain",fontsize = "12",fontcolor = "#000000FF",fixedsize = "true",labelloc = "c"]
edge [label = "",penwidth = "2.000000",tooltip = "",arrowhead = "none",arrowtail = "none",color = "#848484FF",fontname = "Dialog.plain",fontsize = "10",fontcolor = "#000000FF",style = "solid",dir = "both"]
"Node 1§64" [label = "Node 1",pos = "-243.000000,42.000000"]
"Node 2§66" [label = "Node 2",pos = "-70.975037,42.014648"]
"Node 3§68" [label = "Node 3",pos = "-159.020569,-41.005199"]
"Node 4§70" [label = "Node 4",pos = "-243.001038,-123.001381"]
"Node 1§64" -- "Node 2§66"
"Node 2§66" -- "Node 4§70"
"Node 1§64" -- "Node 3§68"
}
Pick node label location. Graphviz does not offer the flexible label placement that Cytoscape offers. As such, dot-app gives the options of “Center,” “Top,” “Bottom,” and “External” to allow the user to specify the label location applied to every node. In the output Graphviz file, the “Center,” “Top,” and “Bottom” options change the value of the “labelloc” that appears in the node default attribute list. The options respectively change the value to “c,” “t,” and “b”. In contrast, the “External” option causes the node labels to set the “xlabel” attribute instead of the “label” attribute in the output Graphviz file. The “xlabel” attribute causes the label to be placed in a location near its node that does not cause it to overlap with any other nodes or labels. Figure 6 shows a network exported with the “External” option.
Pick network label location. dot-app provides the options “No network label,” “Top,” and “Bottom” to allow the user to specify whether the network itself should be labeled and, if so, where the label is placed. The options “Top” and “Bottom” cause the “labelloc” attribute and “label” attribute for the graph to be written to the output Graphviz file. Furthermore, the “label” attribute will be set to the network’s name in Cytoscape. In contrast, the “No network label” option omits both the “labelloc” attribute and the “label” attribute.
For the import function of dot-app, we used Java-based Parser for Graphviz Documents (JPGD), a Graphviz document parser made by Alexander Merz(5). A Graphviz file typically contains information about the nodes, edges, and subgraphs (including annotations) for the layout. JPGD is a parser that transforms such a description into a data structure. We used it to create Java objects modeling the graph, its nodes, and its edges. Each model object contains related DOT attributes represented as key-value pairs. Figure 7 provides a high-level picture of the conversion of a DOT node declaration to the Node object that JPGD created. Detailed information about the JPGD objects can be found on JPGD’s website (http://www.alexander-merz.com/graphviz/doc.html).
After JPGD creates the model objects, dot-app creates a corresponding Cytoscape model, including a CyNetwork object, CyNode objects, and CyEdge objects. These associations are stored in maps: one map for each type of graph component. When the network view is being built in Cytoscape, our Reader objects use these associations to create the Cytoscape View objects. Three Reader classes exist: NetworkReader, NodeReader, and EdgeReader. At the start of the network view creation, a VisualStyle object is created for the network. Each Reader object uses the VisualStyle to set the default attributes for its class of graph components. In addition, Reader iterates through the corresponding association map to create the View objects for the graph components and to set their VisualProperties. Figure 8 shows the high-level relationships among the JPGD Graph objects, the Cytoscape Graph objects, and the Cytoscape View objects.
After the View objects are created, the DOT attributes and their assigned values are converted into their Cytoscape equivalents, and the resulting VisualProperty and VisualPropertyValue are assigned to the View. If the DOT attribute’s assigned value does not have an equivalent Cytoscape VisualPropertyValue, the VisualProperty is set to a default VisualPropertyValue.
We created three classes—NodePropertyMapper class, EdgePropertyMapper class and NetworkPropertyMapper class—to accomplish the export function of dot-app. Each Mapper class contains an ArrayList into which the Mapper classes insert the DOT attribute strings for easily convertible Cytoscape VisualProperties. In addition, each Mapper class has unique helper methods that create the DOT attribute strings for the DOT attributes that have values determined by multiple Cytoscape VisualProperties. One such attribute is the “style” DOT attribute, the value of which is determined by NODE_SHAPE, NODE_BORDER_LINE_TYPE, and NODE_VISIBLE. The NodePropertyMapper class handles the conversion of the CyNodes and their VisualProperties into their DOT string equivalents. The EdgePropertyMapper class handles the conversion of the CyEdges and their VisualProperties into their DOT string equivalents. Finally, the NetworkPropertyMapper class handles the conversion of the CyNodes' and CyEdges' default VisualProperties and the CyNetwork’s VisualProperties into their DOT string equivalents.
Supported DOT attributes. The following DOT attributes contribute to the Cytoscape network during the import process. Most of the DOT attributes listed below correspond to a single Cytoscape visual property, but a few affect multiple visual properties (e.g., the “style” DOT attribute, as described below) at once due to the fact that the information is stored differently between the DOT model and the Cytoscape model. The “weight” DOT attribute is imported as an Edge table attribute (i.e., data) because no corresponding Cytoscape visual property exists. All other DOT attributes are ignored during the import process and have no effect on the visualization in Cytoscape.
Node DOT attributes. Table 1 lists the DOT attributes that can apply to nodes and the specific Cytoscape visual properties to which they map. The “pos” attribute maps to both NODE_X_POSITION and NODE_Y_POSITION because the value of the “pos” attribute is a coordinate pair of the form “x, y”.
Edge DOT attributes. Table 2 lists the DOT attributes that apply to edges and the specific Cytoscape visual properties to which they map.
The “style” DOT attribute. The “style” DOT attribute applies to both nodes and edges. The attribute takes a comma-separated list of keywords as its value. These keywords directly affect which Cytoscape visual properties are modified. Table 3 lists the keywords that dot-app supports, the graph components they affect and the Cytoscape visual properties to which the keywords map.
The “weight” DOT attribute. During the importing of a network using dot-app, a weight column is added to the Cytoscape network’s edge table. If the “weight” attribute is supplied for an edge, its value is assigned to the weight column entry for the edge.
Unsupported DOT features. The following features of Graphviz are not supported in the import:
1. Any HTML
2. Subgraphs
3. Clusters
4. Edges that are rendered as colored parallel lines: These are made by assigning a color list without weights to the “color” attribute. Figure 9 depicts an example edge rendered in this manner.
5. Edges that are rendered as colored segments in series. These are made by assigning a color list with weights to the “color” attribute. Figure 10 depicts an example edge rendered in this manner.
Unsupported Cytoscape features. When exporting the network as a GraphViz file, some Cytoscape information is lost because it cannot be represented in DOT format. dot-app does not keep a log of the information that is not transferred to the Graphviz file. The following information is lost:
Visual information
1. Custom graphics
2. Edge bends
3. Nested network images contained in nodes
4. Arrowhead colors (they will appear the same color as the edge itself)
5. Certain line types
6. Label positioning
7. The V node shape
8. Target arrow shape
9. All annotations
Non-visual information
Detailed below are two cases for dot-app. The first use case describes how a DOT file can be imported into Cytoscape. The second use case describes how a Cytoscape network can be exported as a DOT file.
Our first use case details how we would use dot-app to view a Graphviz-created network in Cytoscape. We used Graphviz’s neato utility to create a DOT file with layout information and a PNG of the resulting network. The DOT file is shown below, and Figure 11 is the created PNG.
graph toy_example {
graph [bb="-85.648,-58.068,63.891,73.497",outputorder=edgesfirst, overlap=false];
node [fillcolor="#888888",label="\N",style=filled];
1 [height=0.5,pos="-58.648,-8.4777",width=0.75];
2 [height=0.5,pos="36.891,3.383",width=0.75];
2 -- 1 [pos="10.278,0.079128 -2.8626,-1.5522 -18.68,-3.5159 -31.846,-5.1504"];
3 [height=0.5,pos="12.665,-40.068",width=0.75];
3 -- 1 [pos="-9.8989,-30.072 -18.223,-26.385 -27.653,-22.208 -35.986,-18.516"];
3 -- 2 [pos="22.24,-22.895 23.933,-19.858 25.695,-16.698 27.386,-13.665"];
4 [height=0.5,pos="8.8474,55.497",width=0.75];
4 -- 2 [pos="18.03,38.433 21.097,32.734 24.516,26.38 27.592,20.664"];
4 -- 3 [pos="9.5835,37.071 10.264,20.041 11.269,-5.1139 11.944,-22.022"];
}
Figure 12 shows the result of the import into Cytoscape version 3.4. The differences that arise between the Graphviz network and the Cytoscape network stem from how the two programs handle implicit default values. If a DOT attribute is omitted from the DOT file when using a Graphviz utility, an implicit default value for that attribute is used. The list of DOT attributes and their default values can be found on the Graphviz website (http://www.graphviz.org/content/attrs.html). Moreover, if a Cytoscape-compatible DOT attribute is not specified in the DOT file during import, Cytoscape supplies default values for the Cytoscape VisualProperties to which the missing DOT attribute maps. These default values come from Cytoscape’s default visual style. This is why the nodes appear as ellipses in the PNG created using neato and as rounded rectangles in Cytoscape. These implicit defaults cause three apparent differences between the two results. The first difference is the node shapes, the second difference is the border colors for the nodes, and the third difference is the font used for the labels.
In this second use case, we export the network in Figure 12 from Cytoscape. The output file is shown below. Figure 13 shows the PNG created by using Graphviz’s neato utility on the output file. With this DOT file, we are able to use Graphviz and other programs that accept DOT files, such as NetworkX and PyGraphviz.
graph toy_example {
bgcolor = "#FFFFFFFF"
splines = "false"
outputorder = "edgesfirst"
esep = "0"
pad = "2"
node [label = "\N",penwidth = "0.000000",height = "0.486111",width = "1.041667",tooltip = "",color = "#CCCCCCFF",fillcolor = "#888888FF",shape = "rectangle",style = "solid,rounded,filled",fontname = "SansSerif.plain",fontsize = "12",fontcolor = "#000000FF",fixedsize = "true",labelloc = "c"]
edge [label = "",penwidth = "2.000000",tooltip = "",arrowhead = "none",arrowtail = "none",color = "#848484FF",fontname = "Dialog.plain",fontsize = "10",fontcolor = "#000000FF",style = "solid",dir = "both"]
"4§62" [label = "4",height = "0.500000",width = "0.750000",pos = "8.847400,55.497000"]
"3§63" [label = "3",height = "0.500000",width = "0.750000",pos = "12.665000,-40.068000"]
"2§64" [label = "2",height = "0.500000",width = "0.750000",pos = "36.891000,3.383000"]
"1§65" [label = "1",height = "0.500000",width = "0.750000",pos = "-58.648000,-8.477700"]
"4§62" -- "3§63" [color = "#404040FF"]
"4§62" -- "2§64" [color = "#404040FF"]
"3§63" -- "2§64" [color = "#404040FF"]
"3§63" -- "1§65" [color = "#404040FF"]
"2§64" -- "1§65" [color = "#404040FF"]
}
Again, slight differences exist in the network’s appearance: the node shape and the labels’ font. The variation in the node shape is due to how Graphviz and Cytoscape render rounded rectangles different. The difference in the labels’ font is due to the font chosen in Cytoscape. In the output file shown above, we can see that the fontname attribute for the node default list is set to “SansSerif.plain”. This font is not an actual font family; rather, it is one of Java’s logical fonts (https://docs.oracle.com/javase/tutorial/2d/text/fonts.html#logical-fonts). It is a font name that the Java Runtime Environment used and that maps to a physical font. When neato encounters the font name, it attempts to find an actual font named “SansSerif.plain”; if it cannot find one, it uses a default font.
We verified the dot-app import and export functions separately.
For import, we downloaded DOT files from Graphviz’s gallery page (http://graphviz.org/Gallery.php) and wrote our own DOT files. We then ran Graphviz’s neato utility on these files to generate DOT files that contained layout information and PNG files to use as references. We then imported the DOT files to Cytoscape and visually compared the Graphviz-created PNG files to the Cytoscape display to validate the import process of dot-app.
For export, we loaded each of the Cytoscape test session files (https://github.com/cytoscape/cytoscape-tests/blob/master/docs/Session-Files/Session%20Files.md) into Cytoscape and exported them to DOT files, which were then loaded into GraphViz. We visually compared the GraphViz display to the Cytoscape display to determine the correctness and completeness of the Cytoscape-to-DOT translation.
This article describes the dot-app Cytoscape app, which enables a user to import a DOT-formatted into Cytoscape and to export a Cytoscape network to a DOT-formatted file. We demonstrated the operation of dot-app and explained its implementation and the limitations of DOT-to-Cytoscape and Cytoscape-to-DOT translation. Finally, we explained typical use cases and how dot-app delivers value in each situation.
Whereas the dot-app conversions are diligent and true to Cytoscape 3.3 (with limitations), we recognize that future versions of Cytoscape may introduce new visual effects (e.g., new arrow heads) that present opportunities for rendering DOT files more truly or for the loss of formatting information if the DOT format cannot represent them. These issues will be dealt with in future versions of dot-app.
Software available from:
http://apps.cytoscape.org/apps/dotapp
Latest source code:
https://github.com/idekerlab/dot-app
Archived source code as at the time of publication:
http://doi.org/10.5281/zenodo.1596373
License:
GNU General Public License
BF, ZZ, and MM were involved in writing the article. BF, ZZ, and BD were involved in revising the draft manuscript and have agreed on the final content. BF, ZZ, and MM were involved in designing and implementing dot-app. BD is the principal investigator for this dot-app project.
This material is based upon work supported by the National Institutes of Health under Grant P41 GM103504. The grant is assigned to Dr. Trey Ideker at the University of California, San Diego (UCSD). All work was performed at UCSD.
The funders had no role in study design, data collection and analysis, decision to publish, or preparation of the manuscript.
Keiichiro Ono and Christian Zmasek helped with identifying the Cytoscape VisualProperties during the dot-app development.
Views | Downloads | |
---|---|---|
F1000Research | - | - |
PubMed Central
Data from PMC are received and updated monthly.
|
- | - |
Competing Interests: No competing interests were disclosed.
Competing Interests: No competing interests were disclosed.
Competing Interests: No competing interests were disclosed.
Competing Interests: No competing interests were disclosed.
Alongside their report, reviewers assign a status to the article:
Invited Reviewers | ||||
---|---|---|---|---|
1 | 2 | 3 | 4 | |
Version 2 (revision) 10 Jul 17 |
read | read | ||
Version 1 20 Oct 16 |
read | read | read | read |
Provide sufficient details of any financial or non-financial competing interests to enable users to assess whether your comments might lead a reasonable person to question your impartiality. Consider the following examples, but note that this is not an exhaustive list:
Sign up for content alerts and receive a weekly or monthly email with all newly published articles
Already registered? Sign in
The email address should be the one you originally registered with F1000.
You registered with F1000 via Google, so we cannot reset your password.
To sign in, please click here.
If you still need help with your Google account password, please click here.
You registered with F1000 via Facebook, so we cannot reset your password.
To sign in, please click here.
If you still need help with your Facebook account password, please click here.
If your email address is registered with us, we will email you instructions to reset your password.
If you think you should have received this email but it has not arrived, please check your spam filters and/or contact for further assistance.
Comments on this article Comments (0)