Cytoscape WikiThis page summarizes the changes done on supporting undirected edges in the svn+ssh://grenache.ucsd.edu/cellar/common/svn/cytoscape3/branches/abeld-gsoc/dev/edge-directionality branch. These changes were merged into cytoscape3 trunk in svn revision 14560. This page is basically a detailed analysis of what changed with that commit, and how it will affect users and developers.
These changes are merged into cytoscape3 svn trunk and thus appear in 3.0 cytoscape. Cytoscape 2.6 is not affected (and this functionality most likely won't be back-ported to cytoscape 2.6).
The gist of the changes is that now undirected edges can also be created and handled with cytoscape. All core cytoscape (i.e. core and core plugins) functionality should work and properly honor edge directionality. (I.e. if it doesn't, notify me and I will fix it. -- DanielAbel)
Undirected and directed edges can be used in the same network (i.e. mixed networks can be handled).
Internally, undirected edges still have a target and a source node, however the order of these don't matter, and they are treated everywhere identically.
It is strongly suggested that the interaction of undirected and directed edges are not mixed. (I.e. don't have edges that have the same interaction but different directionality, even if the end-nodes of these edges differ.)
UI changes / things affecting users
I/O changes
Because not all network formats can handle undirected edges or mixed networks, most of them are not changed: when importing from such a file, directed edges will be created (to preserve pre-3.0 behaviour). When exporting to such formats, directed edges will be written as usual, and undirected edges will be given an arbitrary direction. (Currently this is the same as they were created with, but this shouldn't be depended on.)
The TableImport has been given an extra edge-directionality radiobutton (under "Text File Import Options"), which makes reading edgelists of undirected edges possible. All edges read at once will be created with the same directionality.
Only the gml, xgmml and cytoscape session formats can fully preserve edge directionality, but the following caveats apply:
- round-tripping works (i.e. exporting into xgmml and then importing the same files)
- old cytoscape-generated files are read the same way as they were before, as containing directed edges
the xgmml format as used by cytoscape differs a bit from the "official" xgmml format as described on http://www.cs.rpi.edu/~puninj/XGMML/ :
- The default edge directionality is undirected in the XGMML definition, but directed for cytoscape. This default has been preserved (from pre-3.0 cytoscape). This means that some networks created by third-party tools which contain undirected edges might be read as containing directed edges by cytoscape.
- XGMML cannot handle mixed networks: a given network can only
contain undirected or directed edges, but not both at the same time. Thus, to store edge directionality, a cytoscape-specific flag is used. Third-party programs that adhere to the XGMML definition will thus read xgmml files produced by cytoscape as containing directed networks (i.e. change all edges to directed ones silently). Even networks that contain only undirected edges will suffer the same fate when exported from cytoscape and imported into such third-party apps.
- The GML format is very similar to XGMML in this regard: it, too can only store undirected or directed networks, and it too uses undirected as default. Thus, the same caveats apply as with the XGMML format, with one addition: as the GML standard
(http://www.infosun.fmi.uni-passau.de/Graphlet/download/misc/GML.ps.gz) explicitly states that unknown keys should be preserved, those non-cytoscape programs that conform to this standard will presumably preserve edge-directionality even if they are going to handle undirected edges wrong (since they will internally represent them as directed edges but should save the information when re-exporting). The cytoscape-specific extension for the GML format is simply adding a 'directed' key to Edge items, with the same semantics as the 'directed' key of the Graph items. (i.e. 0 means undirected and 1 means directed).
If you think the above possibility of data corruption is a big problem, you are most likely wrong: cytoscape has been broken in this respect since at least 2.6 (and most likely since xgmml-support has been introduced) and full XGMML-compatibility was deemed not important to break pre-3.0 backwards compatibility for. (I.e. being compatible with pre-3.0 cytoscape is more important than being fully compatible with the XGMML standard.)
vizmapper changes
To avoid the possibility of the two end-points of the edge to appear differently, but to avoid complicating the Visual Mapping UI, the vizmapper has been changed to force undirected edges to always appear with simple edge-ends (i.e. no arrows, or other end-parts).
Editor
The default editor can be used to create directed and undirected edges: there are separate DirectedEdge and UndirectedEdge items on the palette.
Filters
For EdgeInteraction and NodeInteraction filters, where target and source are used for specifying what to filter for, both of these mean 'edge end' for undirected edges.
For example, the NodeInteraction filter which is defined by "select all nodes which are the target of at least one edge which pass filter Foo" will, for undirected edges, select both end-nodes of all edges which pass filter Foo.
TopologyFilter, on the other hand will work the same way as it did before, as it treated all edges as undirected. (This behaviour is not changed to keep TopologyFilter working the same way as it did in pre-3.0 cytoscape for directed edges.)
Things affecting developers
(don't forget to read the "things affecting users" part, too)
Summary:
- if your code created directed edges, and that is appropriate for your usecase, you don't have to modify anything.
- if your code should have been creating undirected edges, you can trivially do so now, without any workaround, or other ugliness.
- if your code handled edges created by other parts of cytoscape, you might have to make some changes. (detailed below)
API changes
Note: the following describe the current state (as of 2008.jul.17.), with Cytoscape_3.0, the API will change, and will more naturally support edge directionality. See the proposed network model API at that page.
The Cytoscape.getCyEdge() methods used for retrieving / creating edges honor the boolean directed flag (if they have one), which defaults to true (i.e. directed edges).
When retrieving an already existing edge without specifying directionality, directed edges will be returned before undirected ones. When creating a new edge without specifying directionality, directed edges will be created.
The .getSource() and .getTarget() of undirected edges should be assumed to return the end-nodes of the edge in arbitrary order.
Semantic changes
Even if your code never called Cytoscape.getCyEdge(), you might still be affected: this is the case if your code handles edges created by other code.
Because edge directionality is an identifying feature of an edge (i.e. not an extra attribute like weight or color), if your code used only the source_node, interaction, target_node tuple for identifying edges, it might break if your users use the same interaction for directed and undirected edges. If you can assume that this won't happen (and for almost all usecases it is not needed), you have no changes to make. If, however, you don't want to make this assumption, you will have to change your code to add the boolean directionality to the above list.
Note that this will change in cytoscape 3.0 when instead of a string identifier of the form "source_node (interaction) target_node", a numeric SUID will be used as the unique identifier of the edge, and thus code won't have to (or be able to) care about how this identifier is generated.
Editor changes
An optional boolean directed arg (defaulting to true) has been added to ShapePalette.addShape to be able to declare the directionality of the given type of edge.
As noted above, a given interaction should always mean the same directionality, thus the fact that the editor's API helps to enforce this is considered a feature.
Code style issues
All code added / modified by this change should be tested to the same extent as already existing code is. (So if there were unittests before, I extended them to cover the new functionality, but didn't write new tests for code that was not unittested before.) If it isn't, notify me and I will fix it.