dot-app: a Graphviz-Cytoscape conversion plug-in

dot-app is a Cytoscape 3 app that allows Cytoscape to import and export Graphviz (.dot, .gv) files, also known as DOT files due to the .dot extension and their conformance to the DOT language syntax. The DOT format was originally created in the early 2000s to represent graph topologies, layouts and formatting. DOT-encoded files are produced and consumed by a number of open-source graph applications, including Graphviz, Gephi, Tulip, and others. While DOT-based graph applications are popular, they emphasize general graph layout and styling over the topological and semantic analysis functions available in domain-focused applications such as Cytoscape. While domain-focused applications have easy access to large networks (10,000 to 100,000 nodes) and advanced analysis and formatting, they do not have as many styling options as the Graphviz software suite. dot-app enables the interchange of networks between Cytoscape and DOT-compatible applications so that users can benefit from the features of both. dot-app was first deployed to the Cytoscape App Store in August 2015, has since registered more than 1,200 downloads, and has been highly rated by more than 20 users.


Introduction
Cytoscape 1 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 319 apps (June 2017) 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 formats 2 do not include visual information, such as SIF (.sif) and NNF (.nnf).Other file formats, such as GEXF (.gexf) and XGMML(.xgmml),include varying amounts of visual information.Our primary motivation for creating dot-app was to extend Cytoscape's interoperability to users that primarily use Graphviz software.Prior to dot-app, a user would either have to convert the network to a file format compatible with Cytoscape or attempt to manually reconstruct the network.Converting a DOT file into a Cytoscape network by use of an intermediary file format is an inherently bad process because each conversion results in a loss of some data.Furthermore, reconstructing a graph manually in Cytoscape might not be too difficult for a simple graph with few nodes and edges, but reconstruction would become more time consuming for larger networks which have nodes of distinct visual properties since each node would have to be created one at a time and these visual properties have to be set separately for each node if there is no underlying data to which the visual properties can be mapped.With dot-app, we minimize information loss by providing a direct conversion from DOT to a Cytoscape network and we reduce the time needed to reconstruct the DOT network in Cytoscape.
Graphviz 3 is a popular, well-established graph visualization software suite that produces DOT (.dot, .gv)files containing graph structure, layout, and styling information; and uses these files to output these networks in a variety of file formats.These files adhere to the DOT language syntax (http://www.graphviz.org/doc/info/lang.html).In this paper, we use "DOT file/network" and "Graphviz file/network" interchangeably.Due to Graphviz's continued usage, many graph visualization and analysis applications support the import and export of DOT files.Table 1 lists some of these applications and whether they can import or export DOT files.

Amendments from Version 1
With this version, we update several sections of the paper in order to clarify points and add further detail.
When we introduce Graphviz we include Table 1 that shows some graph software and their support for DOT files.We elaborate on our discussion of the visual features that the DOT file format support in comparison to other file formats which Cytoscape supports.Instead of comparing DOT to XGMML and GraphML, in a new Table 2 we compare DOT to XGMML and GEXF because GEXF includes visual features in its specification similar to DOT and XGMML.
An Installation subsection is added to the Operation section.To clarify how we used JPGD, we reworded the Import subsection of the Implementation.We state the unit conversion made when converting a node's height and weight values between Cytoscape and DOT.
In our Supplementary Material we include a document listing the DOT attributes ignored during import (Supplementary File 1), a ZIP file containing files from our Use Cases (Supplementary File 2), and a ZIP file containing all of our DOT files and Cytoscape session files that we used for testing (Supplementary File 3).
We also updated our software to use DOT default values when importing a network, and updated all of our images in the Use Cases section to reflect that change.Figure 1 is new, and Figure 12, Figure 13 and Figure 14  node shapes and line types.In comparison to GEXF and XGMML, the DOT format defines more node shapes, arrow shapes, and has unique features such as gradients for node colors and edges painted with multiple colors.Table 2 shows some options for edge line types and which file formats support them.GEXF's entry for multiple lines is marked with an asterisk because its support for the line type is limited.Unlike DOT which supports any number of lines for an edge, GEXF only supports up to two lines for an edge with its "double" line type.Figure 1 is a graph of all the node shapes  between the three formats and shows which formats support which node shapes.Names for the same node shape share a node in the graph, such as the "disc" shape name found in GEXF and the "circle" shape name found in both DOT and XGMML.
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.
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.

Operation
Minimum system requirement Dot-app requires Java 7 or above and Cytoscape v3.2 or above.

Installation
Open Cytoscape and navigate to the App Manager from the menu ("Apps->App Manager").While in the "Install Apps" tab, type dotapp in the search bar.Make sure the download site is http://apps.cytoscape.org,as our app is in the Cytoscape App Store.Click on dot-app to select it and then click the install button to download and install the app.

Import
A Graphviz network can be imported in three 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 2).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 .dotand a Graphviz file with an extension of .gv.However, the .gvextension is preferred because versions of Microsoft Word also use the .dotextension (https://marc.info/?l=graphviz-devel&m=1294 18103126092).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/).

Export
To export a Cytoscape network as a Graphviz network, use "Export -> Network and View" from the 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 3 below.The purposes of these options are explained in the following section.

Set Parameters prompt
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 4, Figure 5, and Figure 6 depict pictures of the network with each edge style chosen.
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.

Import
For the import function of dot-app, we used Java-based Parser for Graphviz Documents (JPGD), a Graphviz document parser made by Alexander Merz (http://www.alexander-merz.com/graphviz/).We use JPGD to read the DOT file and create a JPGD data model of the graph or collection of graphs in the file.A JPGD Graph object is created for each graph in the file, a JPGD Node object for each node, and a JPGD Edge object for each edge.Each JPGD object contains the DOT attributes for the graph element they represent.
Figure 8 provides a high-level picture of the conversion of a DOT node declaration to the JPGD Node object.Detailed information about the JPGD objects can be found on JPGD's website (http:// www.alexander-merz.com/graphviz/doc.html).Once the JPGD data model is built, we begin creation of the network in Cytoscape by using the JPGD data model to create a Cytoscape data model.A CyNetwork object is created for each JPGD Graph object, a CyNode object for each JPGD Node object, and a CyEdge object for each JPGD Edge object.At this point in the importation, the graph elements themselves have been imported, but not their visual attributes.
A Cytoscape View data model has to be created in order for the DOT graphs to be visually recreated in Cytoscape.In order to facilitate this, we associate each JPGD object to their corresponding Cytoscape object and store these associations in maps.These maps are necessary because the Cytoscape View data objects are created from the Cytoscape objects, yet the visual attributes for each element is stored in the JPGD objects.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.This VisualStyle is constructed so that if the DOT file does not specify default attributes then the default attributes are already set to DOT implicit values.Each Reader object uses the VisualStyle to set the default attributes for its class of graph components.In addition, each Reader iterates through their association map to retrieve the View objects for the graph components.
After the View objects are retrieved, the DOT attributes and their assigned values are converted into their Cytoscape equivalents, and the resulting VisualProperty and VisualPropertyValue are set to the View.If a DOT attribute does not have an equivalent Vis-ualProperty or its assigned value does not have an equivalent VisualPropertyValue then it is ignored.Figure 9 shows the highlevel relationships among the JPGD objects, the Cytoscape objects, and the Cytoscape View objects.

Export
We created three classes-NodePropertyMapper, EdgeProperty-Mapper and NetworkPropertyMapper-to accomplish the export function of dot-app.Each Mapper class contains an ArrayList into

Conversion details
Import Supported DOT attributes.The DOT attributes in the following subsections contribute to the Cytoscape network during the import process.Most of the DOT attributes listed below correspond to a single Cytoscape visual property and their values are able to copied over easily (such as the label attribute), but a few of the attributes either affect multiple visual properties at once (e.g., the "style" DOT attribute, as described below) or a conversion needs to performed on their values (e.g., the "height" and "width" attributes) due to the fact that the information is stored differently between the DOT model and the Cytoscape model.If a DOT attribute is assigned a value that does not have an equivalent value for the corresponding Cytoscape visual property, then the DOT attribute is ignored.The "weight" DOT attribute is imported as an Edge table attribute (i.e., data) because no corresponding Cytoscape visual property exists.
The DOT attributes listed in File 1 of the Supplementary Material are ignored and have no effect on the visualization in Cytoscape.
Node DOT attributes.Table 3 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".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 5 lists the keywords that dot-app supports, the graph components they affect and the Cytoscape visual properties to which the keywords map.

Edge DOT attributes.
The "weight" DOT attribute.During the import 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.
The "height" and "width" DOT attributes.In the DOT language, the height and width of nodes are specified in inches.However, the height and width of nodes are specified in points in Cytoscape.During both import and export we handle the necessary unit conversion (1 in = 72 pts) in order to maintain the correctness of the graph.

Unsupported DOT features.
The following features of Graphviz are not supported in the import: 1. HTML-like Labels 2. All node shapes are not supported except the following: triangle, diamond, ellipse, hexagon, octagon, parallelogram, rectangle, rect, box, and square.Msquare, Mcircle, and Mdiamond will be rendered the same as square, circle, and diamond respectively.
3. All arrow shapes are not supported except the following: vee, lvee, rvee, dot, normal, diamond, none, and tee.The arrow shapes odot, onormal, and odiamond will be rendered the same as dot, normal, and diamond respectively.
4. Edge curves.The value of the "pos" attribute is ignored when it is used as an attribute for edges, so dot-app will render edges only as straight lines between nodes.
6.The "tapered" and the "bold" edge style keywords 7. The "bold", "diagonals", "striped", and "wedged" node style keywords 12. Edges that are rendered as colored segments in series.These are made by assigning a color list with weights to the "color" attribute.Figure 11 depicts an example edge rendered in this manner.

Gradients applied to the network background
Export Unsupported Cytoscape features.When exporting the network as a GraphViz file, some Cytoscape information is lost because it

Use cases
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.The DOT file used for import, the Cytoscape session file of the network, and the DOT file generated by dot-app during export are contained in ZIP 1 of the Supplementary Material.

Import
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 12 is the created PNG.

Testing
We verified the dot-app import and export functions separately.All of the files we used in testing are found in ZIP 2 of the Supplementary Material.
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 Cytoscape test session files (https://github.com/cytoscape/cytoscape-tests/blob/master/docs/Session-Files/ Session%20Files.md)into Cytoscape and exported individual networks from these sessions to DOT files, and then used Graphviz's neato utility to create PNG files from these.We visually compared neato's PNG output to the Cytoscape display to determine the correctness and completeness of the Cytoscape-to-DOT translation.

Conclusion
This article describes the dot-app Cytoscape app, which enables a user to import a DOT file into Cytoscape and to export a Cytoscape network as a DOT 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.
We recognize that as long as Cytoscape and Graphviz continue to add visual shapes and features, we will need to determine if these features are found in both applications and if they are we will need to update dot-app in order to provide support for these features.Dot-app's primary goal was to allow Cytoscape to accept DOT files that represented common graph structures.We believe that dot-app as it is now can handle most of the more common DOT syntax people happen to use.However there are some, such as subgraphs, which people use that we were not able to support.We support anyone who finds dot-app lacking in some form and wishes to modify it.

License: GNU General Public License v3
Author contributions 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.

Competing interests
No competing interests were disclosed.

Grant information
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.

Research Institute, Adelaide, SA, Australia
European Molecular Biology Laboratory (EMBL) Australia Group, South Australian Health and Medical Research Institute, Adelaide, SA, Australia We are satisfied that the authors have adequately addressed our comments in this new version.
No competing interests were disclosed.

Competing Interests:
We have read this submission.We believe that we have an appropriate level of expertise to confirm that it is of an acceptable scientific standard.

Giovanni Scardoni
Center for Biomedical Computing (CBMC), University of Verona, Verona, Italy The article introduces an app to import/export Graphviz (.gv-.dot) files to/from Cytoscape.Since the Graphviz format is of wide usage, the app is very useful to the community.
The article is well-written and the user-guide is complete and easy to read.
As minor comments I ask more details about which characteristics can be lost passing from a format to another.I tried some network choosing them randomly from internet, and sometimes I lost features that I didn't expect to lose.
A table explaining which features are preserved and which not will be very useful in the paper.If there are problem of space maybe the implementation details can be described in supplementary materials and not in the main paper.
The table should contains also short comments about the missing features that can be added in the future, and the problem that can be encountered implementing those characteristics that are not of immediate conversion.I think that with these updates the paper is suitable for indexing.
No competing interests were disclosed.

Competing Interests:
I have read this submission.I believe that I have an appropriate level of expertise to confirm that it is of an acceptable scientific standard.
Author Response 22 Dec 2016 , University of California, San Diego, USA Ziran Zhang Thank you Dr. Scardoni for your comment.We will take your valuable suggestions into 2 Thank you Dr. Scardoni for your comment.We will take your valuable suggestions into consideration while we are refining the article.We appreciate your effort in examining the dot-app and the article for us in detail.
No competing interests were disclosed.

Competing Interests:
We found no problems with the usage of the app; it integrates well into Cytoscape, and can convert back and forth between formats without issue aside from the loss of information which is documented in the article.The code is readable and very well commented.
We did have an issue when compiling from source, however.The DOT parsing jar from Alex Merz isn't being included properly when Maven builds the project.
The major concern we had was that the concept for the application is really very straight-forward and following on from this, its functionality is therefore pretty limited.We wondered initially whether there was really a need for such an application, however, dot-app has been downloaded >1200 times so there is obviously a market for the tool.A remaining question, however, is whether the app justifies a 10-page paper?The paper itself reads a bit more like documentation and we would have preferred to have seen a more concise paper introducing the concepts together with more detailed documentation.
We think that the paper could also benefit from a better discussion in the introduction of the motivation behind the development of dot-app.Can you give examples where one would want to create a network in one format and then convert it to another?How hard would it be to manually re-create the visualisation in Graphviz/Cytoscape?
The application also appears very reliant on the parser developed by Alex Merz (this is not referenced properly).It would be good to clarify how much of the functionality is provided by this parser and how much is extended by dot-app.
A key limitation of the app is that many of features of either format are lost when converting between them.This is because there isn't an equivalent feature in the other format.It is good that the authors are clear about which ones cannot be converted but this problem still means that manual intervention would likely be needed to customise the desired style.
One thing that could be improved is how the implicit default values are handled by dot-app.Couldn't you One thing that could be improved is how the implicit default values are handled by dot-app.Couldn't you set reasonable values for these if they are not specified in a particular visualisation to enable more faithful conversion of the visualisation style?
One final concern is that it is very likely that the visual styles in both Graphviz and Cytoscape will continue to evolve over time.How will dot-app keep pace with these changes?Have the authors considered trying to get the Graphviz and Cytoscape communities to adopt at least the equivalent visual style features in both applications?Or at least to indicate in the Cytoscape and Graphviz documentation what is the equivalent feature (when there is one).
Minor comment: Under Operation it would be good to start by explaining how to install the App (for novice Cytoscape users).
No competing interests were disclosed.

Competing Interests:
We have read this submission.We believe that we have an appropriate level of expertise to confirm that it is of an acceptable scientific standard, however we have significant reservations, as outlined above.
Users of the dot language rely on the default values and expect rendering tools to use them.
-> Especially, in combination with dot-app writing the Cytoscape default values in the exported dot this results in unnecessary changes of the graph rendering in the round trip (dot -> cytoscape -> dot).This round trip should introduce minimal changes to the rendering.Dot default values should be used and the respective text passage and figure be updated.## minor comments >>> In the implementation all visual styles are hard coded in the visual mapping via bipasses.It would be better to create node attributes for the dot attributes and subsequently use them in visual styles.In this way users have access to the dot attributes, can use them in other visual mappings, create derived node attributes from them, or use them in analyses.
>>> It is unclear how dot height and width are transformed to Cytoscape node height and width.There is some scaling factor, but how this is actually handled should be described in the manuscript.What information is lost in the roundtrip due to scaling.For instance height = "0.486111",width= "1.041667"result in height > 40 in Cytoscape.

Competing Interests:
I have read this submission.I believe that I have an appropriate level of expertise to confirm that it is of an acceptable scientific standard, however I have significant reservations, as outlined above. 1.

2.
for bringing the problems you found to our attention.While waiting for another referee's upcoming peer review report, we will take a close look into the issues and address them for our next version.The DOT language support visual features and attributes that are not currently included by Cytoscape network formats.There is currently no Cytoscape plugin for the import and export of networks to the DOT language.Therefore the dot-app plugin may be useful to convert and import biological networks, and might be very interesting for the large community of Cytoscape users.
The article is globally clear, well-organized and logically structured.I particularly appreciated the efforts of the authors to explain the details of the conversion process and exactly what kind of visual properties are imported and exported, including the properties that are not supported.
I would suggest minor improvements to the article that could make it more precise and valuable for the readers.
Add a table for at least some of the main visual features and attributes supported by the DOT format and indicate which ones are supported by XGMML/GraphML.The sentence mentioning the differences in the introduction section is too vague.
Compile also in a small table some examples of applications (related to biology or not) that produces or consumes DOT files.Here also the paragraph discussing this in the introduction section is quite vague.

Minor comments:
The reference to the JPGD parser do not appear in the bibliography.
A few sentences on how to install the app in Cytoscape might be helpful.
No competing interests were disclosed.

Competing Interests:
I have read this submission.I believe that I have an appropriate level of expertise to confirm that it is of an acceptable scientific standard.

Figure 1 .
Figure 1.Graph showing which node shapes are supported by which file format.

Figure 3 .
Figure 3. Set Parameter pop-up prompts users with three options.

Figure 4 .
Figure 4.The network exported with the "Straight segments" option, as "splines = 'false'" in the output Graphviz file.

Figure 7 .
Figure 7.A network exported with the "External" option for node label location.

Figure 10 .Figure 11 .network images contained in nodes 4 . 1 .
Figure 10.Example of an edge rendered as colored parallel lines.
Figure 12.The PNG generated using Graphviz's neato utility.

Figure 13 .
Figure 13.The DOT network as it looks in Cytoscape.

Figure 14 .
Figure 14.The PNG of the exported DOT file created with Graphviz's neato utility.

Table 1 . Some graph visualization and analysis software and their compatibility with DOT files. Graph Software Import DOT files Export DOT files
are revised form Version 1's Figures 11, 12 and 13, respectively.

Table 2 . Edge line types available with DOT, XGMML, or GEXF. X's are supported types.
Figure 2. Network file to load dialog with Graphviz files selected.

Table 4
lists the DOT attributes that apply to edges and the specific Cytoscape visual properties to which they map.

Table 3 . DOT node attributes and their corresponding Cytoscape visual properties. DOT attribute Cytoscape visual property
Compiling 16 source files to /home/mkoenig/git/dot-app/target/classes [INFO] -