← Revision 1 as of 2005-07-23 00:25:39 →
Size: 12102
Comment: Copied from page initially made by Rowan Christmas
|
Size: 12116
Comment:
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
[[TableOfContents]] |
|
Line 9: | Line 11: |
[http://cytoscape.org/images/image001.gif] | attachment:Cytoscape_classes.png |
Line 85: | Line 87: |
While {{{CyNetworks}}} represent the unification of the graph and data, the {{{CyNetworkView}}} is the Visualization of the {{{CyNetwork}}}. Working with {{{CyNetworkViews}}} is very similar to working with {{{CyNetworks}}}. As with the {{{CyNetwork}}}, a {{{CyNetworkView}} is created using the static Cytoscape class, and destroyed in the same way. | While {{{CyNetworks}}} represent the unification of the graph and data, the {{{CyNetworkView}}} is the Visualization of the {{{CyNetwork}}}. Working with {{{CyNetworkViews}}} is very similar to working with {{{CyNetworks}}}. As with the {{{CyNetwork}}}, a {{{CyNetworkView}}} is created using the static Cytoscape class, and destroyed in the same way. |
Concept 1: Networks
Cytoscape is written using the Java programming language, and therefore uses the Object-Oriented paradigm. The central object in Cytoscape is a CyNetwork. The CyNetwork is a combination of a graph, consisting of Nodes and Edges, and the data that is associated with individual graph elements, or the graph itself.
CyNetworks inherit from the GraphPerspective which is part of the underlying GINY graph library. All CyNetworks operate on the same set of Nodes and Edges, although not all Nodes and Edges will be in every CyNetwork. This means that if you create a Node in one CyNetwork, it can be added to another CyNetwork, and will have all of its data and connections associated with it.
The following diagram shows the classes and their relationships that will be used most.
attachment:Cytoscape_classes.png
Concept 2: Creating and Modifying and Destroying Networks
The creation of CyNetworks is handled by factory methods found in the cytoscape.Cytoscape class. Cytoscape is an abstract static class and cannot be instantiated. It does however handle all of the creation methods and fires the appropriate events to its listeners. CyNetworks can be created in a variety of ways, but they all work in a similar fashion. What they will do is, given a set of nodes and edges, will create the nodes and edges if necessary in the shared set of nodes and edges that all CyNetworks use, and then return a CyNetwork that only has the requested nodes and edges. The following are the methods for creating a CyNetwork:
1 // return an empty network
2 CyNetwork network = Cytoscape.createNetwork("My Network");
3
4 // return a new Network from a SIF file
5 CyNetwork network = Cytoscape.createNetwork( file_name,
6 Cytoscape.FILE_SIF, canonicalize, biodataserver, species );
7
8 // return a new Network from a GML file
9 CyNetwork network = Cytoscape.createNetwork( file_name,
10 Cytoscape.FILE_GML, canonicalize, biodataserver, species );
11
12 // return a new Network from a file, with a standard
13 // suffix, using the default values
14 CyNetwork network = Cytoscape.createNetwork( file_name );
15
16 // return a new Network with a subset of Nodes and Edges
17 // from an existing Network, and make the new Network a
18 // a child of the old Network in the Network Panel
19 CyNetwork new_network = Cytoscape.createNetwork( nodes,
20 edges, child_title, parent_network );
21
When modifying a CyNetwork, it is necessary to operate directly on that CyNetwork, rather than using the Cytoscape class. There are two types of removal that can be done. Using the "removeNode/Edge" method Cytoscape will attempt to completely remove the Node/Edge from both the CyNetwork and the shared set of Nodes and Edges that all CyNetworks have access to. A Node/Edge will not be removed completely if another CyNetwork has a reference to it. The removal can be forced by passing a Boolean "true" to force the removal.
1 // remove the node, unless used by another CyNetwork
2 network.removeNode( nodeIndex, false );
3
4 // remove the node, even if used by another CyNetwork
5 network.removeNode( nodeIndex, true );
6
If you want the Node/Edge only removed the current CyNetwork, but still available for other CyNetworks ( or even the one it was removed from ) at a later time. The "hide" methods are used. These methods are part of the GINY API, but are linked in the [http://www.cbio.mskcc.org/cytoscape/javadoc/ JavaDoc].
1 // remove the node from this CyNetwork, but allow it to
2 // be re-used later.
3 network.hideNode( node );
4
Creating Nodes/Edges can happen in several ways. Since there is a set of Nodes/Edges that are available to all CyNetworks, there is nothing wrong with creating Nodes/Edges that are not a part of any CyNetwork. This is done using the static Cytoscape class, just like CyNetwork creation.
1 // create a CyNode, Boolean passed so the "create" flag
2 // is enabled
3 CyNode node = Cytoscape.getCyNode( identifier, true );
4
The same function can also be used to query if a CyNode exists for a particular alias. This is the default behavior, or can be explicitly used by passing a "false" value for the create flag.
1 // Return a CyNode if one exists, or null if not.
2 CyNode node = Cytoscape.getCyNode( identifier );
3 if ( node == null )
4 // there is no node for this identifier
5
Destroying a CyNetwork is also done via the static Cytoscape class using the "destroyNetwork" methods. When a CyNetwork is destroyed all of the Nodes/Edges are hidden, so they are still available for other CyNetworks. Destroying a CyNetwork will also destroy any CyNetworkView that is was created to view this CyNetwork.
1 // Destroy a CyNetwork
2 Cytoscape.destroyNetwork( network );
3
4 // Destroy a CyNetwork using its "getIdentifier" method
5 Cytoscape.destroyNetwork( network.getIdentifier() );
6
Concept 3: NetworkView Creation, Modifying and Destruction
While CyNetworks represent the unification of the graph and data, the CyNetworkView is the Visualization of the CyNetwork. Working with CyNetworkViews is very similar to working with CyNetworks. As with the CyNetwork, a CyNetworkView is created using the static Cytoscape class, and destroyed in the same way.
1 // create a CyNetworkView from a CyNetwork
2 CyNetworkView view = Cytoscape.createNetworkView( network );
3
4 // ways to destroy a CyNetworkView, given:
5 CyNetwork network;
6 CyNetworkView view;
7
8 Cytoscape.destroyNetworkView( view );
9 Cytoscape.destroyNetworkView( view.getIdentifier() );
10 Cytoscape.destroyNetworkView( network );
11
12 // implicit destruction by destroying the network
13 // it is based on
14 Cytoscape.destroyNetwork( network );
15 Cytoscape.destroyNetwork( network.getIdentifier() );
16
Modification of a CyNetworkView is not directly possible. It is a WYSIWYG view on a CyNetwork, so hiding a NodeView in a CyNetworkView only makes that NodeView temporarily invisible. To actually remove a NodeView from a CyNetworkView, the Node that it is a view on must be hidden/removed from the CyNetwork. This behavior can be changed, but is beyond the scope of this document.
Concept 4: CyNetwork(View) Client Data
CyNetworks and CyNetworkViews will be used by a variety of plugins, and plugins will use a variety of CyNetworks and CyNetworkViews. Therefore, the concept of client data allows a plugin to store information that it needs about a particular CyNetwork(View), with that Object.
An example of this is a plugin that calculates an APSP matrix, and runs an analysis on it. Obviously each CyNetwork has a different APSP matrix, so if a new CyNetwork is being used, then a new matrix needs to be calculated.
1 // Sample method for a plugin performing an action
2 CyNetwork network = Cytoscape.getCurrentNetwork();
3 APSP matrix;
4 Object apsp = network.getClientData( "APSP" );
5 if ( apsp == null ) {
6 // there is no apsp matrix available, create one
7 matrix = new APSP( network );
8 // store it for later use
9 network.putClientData( "APSP", matrix );
10 }
11 // use the matrix we already had, or the one we just made
12 doSomething( matrix );
13
Concept 5: Loading, and Using Data
Data can be thought of in many different ways. Usually we refer to data as specific attributes loaded by the user, that refer to one specific Node or Edge. Common attributes are Expression data from Microarray experiments, other laboratory measurements, and ontology information.
Data can be loaded in a variety of ways, from a variety of sources. We will only discuss loading from files, and from a calculation. Database conections and other things are handled via other methods such as the Data Servives Plugin from MSKCC. The most common way to load Node and Edge attributes is from Node and Edge attributes files, and from expression "matrix" files. Both are possible using the static Cytoscape class.
1 // load Node and Edge Attributes from a set of files.
2 String[] node_atts = { "file1", "file2" };
3 String[] edge_atts = { "file3", "file4" };
4 Cytoscape.loadAttributes( node_atts, edge_atts );
5
6 // load Expression Data
7 Cytoscape.loadExpressionData( file_name, true );
8
9 // right now setting individual attributes is a little
10 // hacky, since we just use the old GraphObjAttributes
11 //class.
12 // @deprecated DO NOT USE!!!! ( unless you have to )
13 Cytoscape.getNodeNetworkData().set( attribute, node, value
14 );
15
The more supported way for adding attributes for individual Nodes and Edges (e.g. a calculated value from a Plugin ), is to use the method provided by CyNetwork.
1 // set a value for a node, for a given attribute
2 String attribute;
3 Object value;
4 CyNode node;
5 // note that the method name is the argument order
6 network.setNodeAttributeValue( node, attribute, value );
7
CyNetwork also provides methods for getting attributes for nodes. The methods are structured the same as for setting.
1 // get a value for a node, for a given attribute
2 String attribute;
3 CyNode node;
4 // note that the method name is the argument order
5 Object value = network.getNodeAttributeValue( node,
6 attribute );
7
Several convience methods are also available, look at the API. What methods are here are open for debate. Please let us know what you want/need/like/use.
Concept 6: Focus
Since many CyNetworks can exist in one Cytoscape instance it is necessary to know which CyNetwork and CyNetworkView you are working with. For a plugin that operates when a button/menu is selected, and wants to use whichever CyNetwork and CyNetworkView the user chose, then the following methods should be used:
1 //action method
2 public void actionPerformed ( ActionEvent e ) {
3 CyNetwork network = Cytoscape.getCurrentNetwork();
4 CyNetworkView view = Cytoscape.getCurrentNetworkView();
5 }
6
Note that if a CyNetworkView was last focused then the current CyNetwork will always be the CyNetwork of that CyNetworkView. However if a CyNetwork was last focused with no view, then the current CyNetworkView will return Cytoscape.nullNetworkView.
Concept 7: CytoscapeDesktop
The CytoscapeDesktop is responsible for managing all of the CyNetworkViews and for updating the focus. There is only one instance of CytoscapeDesktop and it is available via:
// get the CytoscapeDesktop Cytoscape.getDesktop();
The CytoscapeDesktop will not normally be used, but is useful for being the parent for Dialogs, since it is a JFrame.
Concept 8: Events
Events are a useful way to update an Object when a property changes. Any event listener needs to implements java.beans.PropertyChangeListener. Here are the available events:
Event |
Firing Class |
CYTOSCAPE_EXIT |
Cytoscape |
NETWORK_CREATED |
Cytoscape |
NETWORK_DESTROYED |
Cytoscape |
ATTRIBUTES_CHANGED |
Cytoscape |
NETWORK_VIEW_CREATED |
CytoscapeDesktop |
NETWORK_VIEW_DESTROYED |
CytoscapeDesktop |
NETWORK_VIEW_FOCUS |
CytoscapeDesktop |
NETWORK_VIEW_FOCUSED |
CytoscapeDesktop |
This is an example implementation of a class that is a listener to both Cytoscape and CytoscapeDesktop.
1 public class MyClass implements
2 java.beans.PropertyChangeListener {
3
4 public MyClass () {
5 // add as listener to Cytoscape
6 Cytoscape.getSwingPropertyChangeSupport().
7 addPropertyChangeListener(this);
8 // add as listener to CytoscapeDesktop
9 Cytoscape.getDesktop().getSwingPropertyChangeSupport().
10 addPropertyChangeListener(this);
11 }
12
13 public void propertyChange ( PropertyChangeEvent e ) {
14 //respond
15 }
16 }
17