Size: 5961
Comment:
|
Size: 21951
Comment: converted to 1.6 markup
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
#acl BaderLabGroup:read,write,revert,delete All: = MCODE User's Manual = [[TableOfContents()]] ---- |
#acl All:read = MCODE Documentation = <<TableOfContents>> |
Line 10: | Line 7: |
To use the MCODE !PlugIn, you must first obtain a copy of Cytoscape. The compatible MCODE and Cytoscape versions are outlined in the downloads section on the [:Software/MCODE: MCODE website]. The lastest MCODE, version 1.2, requires Cytoscape 2.3.2 or later. | To use the MCODE plugin, you must first obtain and install Cytoscape. The compatible MCODE and Cytoscape versions are outlined in the downloads section on the [[Software/MCODE| MCODE website]]. The latest MCODE, version 1.2, requires Cytoscape 2.3.2 or later. |
Line 12: | Line 9: |
Once you have downloaded Cytoscape and verified that it works, proceed with the next steps: | Once you have downloaded and installed Cytoscape and verified that it works: |
Line 14: | Line 11: |
1. Start Cytoscape. For example | 1. Start Cytoscape. This can be done by double-clicking the newly created Cytoscape icon or via commandline: |
Line 18: | Line 15: |
* If it does not, then you likely placed the MCODE.jar file in the wrong directory. Repeat step one. You will have to restart Cytoscape to reload the plugin. | * If it does not, then you likely placed the MCODE.jar file in the wrong directory. Verify that you have completed step one. You will have to restart Cytoscape to reload the plugin. |
Line 23: | Line 20: |
Line 25: | Line 23: |
1. Go to the Plugins Menu 1. Move the mouse over MCODE 1. Click Start MCODE * The main MCODE interface will appear as a tab in the left-hand panel of Cytoscape Note: If MCODE does not appear in the Plugins Menu, then the installation of MCODE was not successfull. Please refer to the previous section of the User's Manual. This menu provides two additional options: * About MCODE * A quick reference to MCODE acknowledgements, citation information, and a link to the MCODE paper. * Help * A link that will open the MCODE website at [:Home: www.baderlab.org] in your default browser for quick access to downloads, contact information, and the User's Manual with help and tutorials. New to Version 1.2: MCODE can now be seen as a console for the underlying algorithm. It can be started independent of network loading. This provides for a more easily accessible, repeatable and modifyable analysis. ---- == Getting Results == This section will cover some of the basic steps of running MCODE on a network. 1. LOAD YOUR NETWORK. To begin, make sure the network to be analyzed is loaded into Cytoscape. You can load as many networks as your computer system can handle, large or small. MCODE will recognize which network you wish to analyze either by noting which network view is on top or by your selection of the network in the Network Tab on the left-hand panel. 1. CHOOSE THE SCOPE. Cluster results can be reported in two fundamental ways with MCODE. This is referred to as the '''Scope''' of the process. |
1. Go to the Plugins Menu and select the MCODE sub-menu 1. Click '''Start MCODE''' * The main MCODE interface will appear as a tab in the left-hand panel of Cytoscape (Note: If MCODE does not appear in the Plugins Menu, then revisit the installation section above.) The MCODE sub-menu provides two additional options: * '''About MCODE''' * Shows the MCODE credits, citation information, and a link to the MCODE paper. * '''Help''' * Links to the MCODE website at [[Home| www.baderlab.org]] in your default web browser for quick access to downloads, contact information, and the User's Manual with help and tutorials. ''New to Version 1.2: MCODE now allows easier access and more control over the underlying algorithm via the Cytopanel based consoles. Parameters are always viewable and modifiable, multiple results can be generated and compared, and clusters can be explored individually with interactive tools.'' ---- == Getting and Interpreting Results == The '''MCODE Main Panel''' is the starting point for analysis. It contains two main sections: '''Find Cluster(s)''' and '''Advanced Options'''. The latter option is intended for fine-tuning of results by experienced users who are familiar with the MCODE paper (discussed in the next section). This section covers some of the basic steps of running MCODE on a network. Please see the the Screenshots section for a visual reference. 1. '''LOAD YOUR NETWORK.''' To begin, load the network to be analyzed into Cytoscape. You can load as many networks as your computer system can handle, large or small. MCODE will analyze either the network view that is on top or one selected in the Network Tab on the left-hand panel. 1. '''CHOOSE THE SCOPE.''' Clusters can be found in the entire network or from a selection of nodes. Chose an option in the '''Find Cluster(s)''' section of the main MCODE panel. |
Line 51: | Line 47: |
* Only those clusters including the selected node(s) as one of their members will be reported. * Selections can be made either in the view directly or in the node browser. . The choice of scope is dependent on the your familiarity with the network in question and the desired outcome. Having a particular protein of interest within a network, for example, it may be appropriate to search for only those clusters involving such a protein. On the other hand, uniformed, exploratory work will most benefit from a whole network scope. 1. ANALYZE YOUR NETWORK. Next, press '''Analyze'''. This will display a task monitor reporing the progress of the scoring, finding, and drawing steps, provided that the task is not too quick. |
* Only those clusters which include the selected node(s) within them will be reported. * Selections can be made either in the view, the Node Attribute Browser or Cytoscape's handy search tools. . The choice of scope is dependent on your familiarity with the network in question and the desired outcome. If you have a particular protein of interest within a network, for example, it may be appropriate to search for only those clusters involving such a protein. On the other hand, exploratory work will benefit most from analyzing the whole network. 1. '''ANALYZE YOUR NETWORK.''' Next, press '''Analyze'''. This will display a progress meter of the scoring, finding, and drawing steps, provided that the task is not too quick. |
Line 58: | Line 54: |
* This means that MCODE failed to detect a loaded network for analysis. You must load a network, and make sure it is selected, before you can anaylze it. | * This means that MCODE failed to detect a loaded network for analysis. You must load a network, and make sure it is selected, before you can analyze it. |
Line 60: | Line 56: |
* This message appears when the Selection Scope is used without an actual selection. You must select the desired node(s) before you MCODE can attempt to find clusters. | * This message appears when the Selection scope is used without an actual selection. You must select the desired node(s) before MCODE can attempt to find clusters. |
Line 62: | Line 58: |
* Parameters are discussed in detail in the following section. For now, you should know that if you attempt to analyze a network twice without changing any of the settings, such as scope, MCODE will let you know that this analysis was previously conducted and will consequently display the previously attained results. 1. BROWSE YOUR RESULTS. If everything goes to plan, a new tab will appear in the right-hand panel displaying the results as "Results 1" |
* Parameters are discussed in detail in the following section. For now, you should know that if you attempt to analyze a network twice without changing any of the settings, such as the scope of the analysis, MCODE will let you know that this analysis was previously conducted and will just display the previously obtained results. 1. '''BROWSE YOUR RESULTS.''' If analysis finds clusters, a new tab will appear in the right-hand panel displaying the result as "Result 1" |
Line 66: | Line 62: |
* On the left side is a graphical representation of the cluster. | * On the left side, in the '''Network''' column, is a graphical representation of the cluster. |
Line 68: | Line 64: |
* The highest scoring node in the cluster is called the '''Seed'''. It is the node from which the cluster was derived and is represented by a square shape. * Other cluster members are circular. |
* The highest scoring node in the cluster is called the '''Seed'''. It is the node from which the cluster was derived and is represented as a square. * Other cluster members are circles. |
Line 72: | Line 68: |
* On the right side is a statisical summary of the cluster. * '''Rank''' is based on the cluster's computed '''Score''' and is used to ID the clusters within each result set. * For example, Cluster 1 is the highest ranked cluster in a given result set, and thus, at the top of the list. * '''Nodes''' and '''Edges''' is a simple enumeration of the clusters members and their interconnections. * These results can be discarded at any time by pressing the '''Close''' button at the bottom of the results panel. This is a screeen shot of the MCODE Main Panel and Cluster Browser attachment:main_panel.gif attachment:cluster_browser.gif ---- == Fine-Tuning Results == |
* On the right side, in the '''Details''' column, is a statistical summary of the cluster. * '''Rank''' is based on the cluster's computed '''Score''' and is used to identify the clusters within each result. * For example, Cluster 1 is the highest ranked cluster in a given result, and thus, at the top of the list. * '''Nodes''' and '''Edges''' is a simple enumeration of the cluster's members and their interconnections. * Results can be discarded at any time by pressing the '''Discard Result''' button at the bottom of the panel. * '''Network View:''' * If the network being analyzed has a view, MCODE will apply a custom visual style utilizing two MCODE generated node attributes as soon as the network is analyzed. * '''MCODE_Node_Status:''' Node shapes indicate the cluster status of the nodes. * Square: seed (highest scoring node in the cluster) * Circle: clustered * Diamond: unclustered * '''MCODE_Score:''' Node colors represent the node score. * A range from black to red indicates the MCODE computed node score (lowest to highest, respectively). * White indicates a score of zero. * '''MCODE_Cluster:''' This is an additional list type attribute that indicates which cluster the node belongs to. The MCODE visual style does not use this attribute, but it exists should you need it. Note that if the '''Fluff''' parameter (discussed in the following section) is turned on, some nodes may belong to more than one cluster. * '''Cluster Selection:''' * The clusters in the cluster browser table are selectable and will automatically select the corresponding nodes in the network view (if it exists). If no network view is available, the selected nodes can be reviewed in the Cytoscape Node Attribute Browser. * Secondly, a new '''Cluster Exploration Panel''' will appear below the Cluster Browser titled "'''Explore: Cluster [Rank]'''". This panel can be collapsed for now -- its use will be discussed in the '''Exploring Results''' section of this Manual. ---- == Fine-Tuning Your Analysis == By default, MCODE analyzes networks using scoring and finding parameters that have been optimized to produce the best results for the average user and network. However, you may achieve better results for your network by familiarizing yourself with these parameters and changing them appropriately. Sometimes even slight customizations can produce considerable differences, reduce unwanted or false results, and increase relevance of results. This is only an overview -- for detailed parameter information, consult the MCODE paper. |
Line 85: | Line 94: |
1. '''Include Loops''' * When turned on, MCODE will include loops (self-edges) in the neighbourhood density calculation. This is expected to make a small difference in the results. 1. '''Degree Cutoff''' * This value controls the minimum degree (number of connections) necessary in order for a node to be scored. For example, nodes that share only one connection with one other node have a degree of 1. Valid values are 2 or higher to prevent singly connected nodes from getting an artificially high node score. |
|
Line 86: | Line 102: |
---- == Exploring Results == ---- |
1. '''Node Score Cutoff''' * This is the most influential parameter for cluster size and is the basis for the '''Size Threshold Slider''' in the '''Exploring Results''' section. During cluster expansion, new members are added only if their node score deviates from the cluster's seed node's score by less than the set cutoff. This is a percentage, where a value of 0.2 allows for new members' node scores to be no more than 20% less than that of the seed node. Thus, smaller values create smaller clusters and vice versa. 1. '''Haircut''' * Once a cluster has been found, some nodes which may have satisfied the Degree Cutoff parameter during scoring may only be connected to the cluster by one edge. When haircut is turned on, MCODE removes all such singly-connected nodes from clusters. In some cases, though rare, the cluster's seed node may be only singly connected to the cluster and removed by the Haircut. For example, Cluster 2 of the galFiltered.gml network with default settings is one such case. 1. '''Fluff''' * When turned on, MCODE expands cluster cores by one neighbour shell outwards, according to the fluff Node Density Cutoff parameter and after the optional haircut step. * '''Node Density Cutoff''' * Node density is calculated by dividing the node's connections by the maximum number of connections possible for that node. If Fluff is turned on, this parameter controls the neighbour inclusion criteria during 'fluffing'. Fluff expansion occurs after the cluster has already been defined by the algorithm and thus allows clusters to overlap at their edges. A higher value will expand clusters more. 1. '''K-Core''' * This parameter filters out clusters that do not contain a maximally inter-connected sub-cluster of at least k degrees. For example, a triangle (3 nodes, 3 edges) is a 2-core (2 connections per node). Two nodes with 2 edges between them satisfy the 2-core rule as well. Since the default value is 2, this ensures that clusters must in the very least contain one of these two sub-clusters. Increasing this value will exclude smaller clusters. 1. '''Max. Depth''' * Maximum depth limits the distance from the seed node within which MCODE can search for cluster members. By default this is set to an arbitrarily large number so that clusters are virtually unlimited. To limit cluster size, set this parameter to a small number. ''New to Version 1.2: The user can now analyze a network as many times as desired by modifying the parameters. Each result is stored sequentially for reference and comparison. Viewing different results will automatically rewrite the MCODE node attributes and re-visualize the network appropriately. Note that MCODE automatically determines which portion of the algorithm needs to be run based on the user's parameter modifications. For instance, if the scoring parameters are altered, the network will be re-scored, but if only the cluster finding parameters are altered, only the cluster finding portion will be run.'' ---- == Exploring Results Interactively == In addition to fine-tuning a multitude of parameters to enhance the analysis process, MCODE provides a real-time cluster exploration feature. This can be divided into two components: exploring cluster boundaries and exploring cluster content. The first exploration allows you to expand or reduce the cluster based on the node score using the '''Size Threshold Slider'''. The second is the '''Node Attribute Enumerator''' which provides a summary of the cluster's node attributes and their frequency in the cluster. Together they can inform the user about the cluster's "natural" boundaries in the context of the network and ensure functional consistency. These are both explained in greater detail below. Figure 3 in the Screenshots section is a good reference for this text. === Size Threshold Slider === The slider scale ranges from '''Min''' to '''Max''' and has an 'origin' marker ('''^''') for its starting position. '''Node Score Cutoff''', which is the most influential cluster size determinant is controlled by the slider. As such, the initial position marker indicates the Node Score Cutoff value originally set in the Finding Parameters section. When moving the slider, the Node Score Cutoff is set to 0 at Min and 100 at Max, however there are several notable differences between the functions of the Size Threshold Slider and the Node Score Cutoff Finding Parameter. 1. During exploration, the cluster is reevaluated without the requirements of satisfying the K-Core parameter. Thus, moving the slider leftwards of the initial position allows the cluster to be reduced to only the seed node. 1. During exploration in the Max direction, the cluster is 'unaware' of other clusters. Unlike in the analysis where every subsequent attempt at finding a cluster is only allowed to expand around previously found clusters, the slider expands the cluster despite adjacent cluster borders. Thus, moving the slider rightwards of the initial position allows the cluster to be expanded to as much as the whole network. * However, the 'awareness' of other clusters is intact in the range between the 'origin' marker and Min to allow the cluster to return to its original size. Haircut and Fluff are applied after slider movement if they were turned on in the original production of the result that is being explored. In response to the slider, the Cluster Browser is updated with the new cluster's network graphic and details (number of nodes and edges and new cluster score). The node selection in the main network view will also be updated. Since clusters can expand to large and sometimes unreasonable sizes, the layouter may need extra time to complete its task. When this occurs, a loader and progress bar will appear in the Cluster Browser. There is no need to wait for the cluster to be drawn, the details and node selections will remain responsive to the slider's movements. If the new cluster exceeds 300 nodes, a place holder ("'''Too big to show'''") will be drawn instead since the graphic representation will take too long to compute and will likely be too crowded to be of any real value. Several peculiarities may arise during size exploration: 1. '''Cluster Size Explosion''' * When exploring a lower ranked cluster (further down the list) the cluster's size may depend heavily on nearby higher ranked clusters. This may not always occur since the finding process starts at the highest scoring nodes while clusters are ranked afterwards based on their size and connectivity -- higher scoring seed nodes may not produce higher scoring clusters. Given that, when expanding a cluster, there may be an unexpected initial discontinuity in size since the Size Threshold Slider will ignore the presence of other clusters. If the cluster was produced around a low-scoring seed node then more nodes are likely to satisfy the Node Score Cutoff parameter. Such situations can indicate that the cluster in question may be part of a larger cluster. 1. '''Slider Dead-Zone''' * Sometimes, on the other hand, moving the Size Threshold Slider a long distance may produce no changes in cluster size. In such cases, the seed node's score is so high compared to its immediate neighbourhood that the Node Score Cutoff must be increased greatly to include much lower scoring members. This indicates that the cluster is more or less well separated from the surrounding network by a local peak in node scores and as such, it is likely a well defined cluster. 1. '''No Change''' * Lastly, if no changes occur during size exploration, the cluster in question is likely not connected to the larger network and as such cannot expand. === Node Attribute Enumerator === The Enumerator provides a numerical summary of node attribute values possessed by the currently explored cluster's members. It is meant to inform the user of the cluster's contents and aid in determining the cluster's functional relevance. All node attributes that are available for the loaded network are listed in the select box. When an attribute selection is made in one exploration, it persists for all cluster explorations within the given result. The table below the select box has two columns: 1. '''Value''' * This column lists all node attribute values that are possessed by the cluster being explored. With a simple string type attribute, such as MCODE_Node_Status, this list will never exceed the number of cluster members since every member can have only one value and some values may be shared by several members. However, list type attributes such as Gene Ontology (GO) terms may outnumber the cluster members since each member can have numerous values. 1. '''Occurrence''' * This column simply displays the number of nodes possessing the particular attribute value listed in each row. The Enumerator table orders the list by the frequency in descending order where the most commonly occurring attribute value is listed on top. * The Occurrence numbers are best interpreted when compared with the number of nodes in the cluster. For example, when enumerating Biological Process GO Terms, it may be a good indicator that the given cluster is biologically relevant if 9 of the 10 cluster members share some specific value. In combination with the Size Threshold Slider, the Enumerator can be used to optimize clusters based on functional relevance. As the slider is being manipulated the Enumerator will automatically report changes in cluster content for the selected attribute. As such one can hone in on a size that, for example, reduces nodes with attribute values that are unrelated to some particular value of interest which is simultaneously maximized. ''Note: At this stage of MCODE development, the Node Attribute Enumerator is a precursor to more automated methods of accomplishing similar attribute-enhanced clustering and statistical reporting.'' ---- |
Line 90: | Line 167: |
---- == Tutorials == |
=== Create Sub-Network === Clusters can be output as sub or child-networks of the original network by clicking the '''Create Sub-Network''' button located on the cluster exploration panel which is opened when a cluster is selected in the Cluster Browser. ''New to Version 1.2: Since exploration allows for a cluster size to change, the user can now create as many sub-networks of the same cluster as desired. New networks are named by their result set, cluster rank and score, for example: '''Result 1: Cluster 1 (Score 4.3)'''.'' === Export as Text === Clusters can be summarized in a time-stamped tab-delimited text file consisting of: * Cluster rank * Cluster score (density multiplied by the number of members) * Number of nodes * Number of edges * Cluster member IDs (comma-delimited) The parameters used in scoring and finding the exported result are included in the file as well for future reference. The default parameter settings appear as: * Network Scoring: Include Loops: false Degree Cutoff: 2 K-Core: 2 * Cluster Finding: Node Score Cutoff: 0.2 Haircut: true Fluff: false Max. Depth from Seed: 100 ---- == Screenshots == '''Figure 1: The MCODE Main Panel and MCODE Result Panel containing the Cluster Browser''' ||<style="border-style:none;"^> {{attachment:screenshot_main_panel.png}} ||<style="border-style:none;"99%(^|2> {{attachment:screenshot_cluster_browser.png}} || ||<style="border-style:none;"> Here the Advanced Options panels have been expanded while the Exploration panel has been collapsed. ''New to Version 1.2: The results have been streamlined to fit in Cytopanel 3 - Node IDs are still available through Export and the Node Attribute Browser.''|| '''Figure 2: Sample Analyzed Network (Yeast, galFiltered.gml), before and after''' ||<style="border-style:none;"|2^> {{attachment:screenshot_graph_1.png}} ||<style="border-style:none;"(^> {{attachment:screenshot_graph_2.png}} ||<style="border-style:none;"99%> || ||<style="border-style:none;"> On the left is a close up of the network before analysis, visualized with a sample visual style. Above, once clustered, the MCODE visual style differentiates seeds and clustered and unclustered nodes by shape (square, circle, diamond respectively). The red intensity in the node colour is correlated with the MCODE node score. White nodes are unscored and therefore unclustered. The yellow selection corresponds to a found cluster.|| '''Figure 3: The whole picture, MCODE in context''' ||<style="border-style:none;"> {{attachment:screenshot_general.png}} ||<style="border-style:none;"99%|2> || ||<style="border-style:none;"> The Main and Result Panels appear as before, this time in their docked form and the Result Panel's exploration section has been expanded. The Cluster Browser selection is reflected in the network view and in the node attribute browser.|| ---- == Tutorials (Coming Soon) == |
Line 93: | Line 210: |
---- == Troubleshooting == === General === * MCODE Does Not Appear in the Plugins Menu === Error Messages === ---- |
=== Cytoscape Tutorial === The makers of Cytoscape have compiled a network clustering example using MCODE and several other plugins. Though it is written for the previous version of MCODE, it should be easily transferable. * Cytoscape Tutorial: [[http://www.cytoscape.org/tut/modules.complexes.php|Section 7: Modules and Complexes]] ---- [[Software/MCODE]] |
MCODE Documentation
Contents
Installation
To use the MCODE plugin, you must first obtain and install Cytoscape. The compatible MCODE and Cytoscape versions are outlined in the downloads section on the MCODE website. The latest MCODE, version 1.2, requires Cytoscape 2.3.2 or later.
You can download a copy of Cytoscape from: http://www.cytsoscape.org.
Once you have downloaded and installed Cytoscape and verified that it works:
- Copy the MCODE.jar file to your [Cytoscape_Home]/plugins directory.
- Start Cytoscape. This can be done by double-clicking the newly created Cytoscape icon or via commandline:
- On Unix/Linux or MacOS X, run: cytoscape.sh
- On Windows, run: cytoscape.bat
- Check that MCODE appears in the Plugins menu of Cytoscape
- If it does not, then you likely placed the MCODE.jar file in the wrong directory. Verify that you have completed step one. You will have to restart Cytoscape to reload the plugin.
Running MCODE
MCODE is an extension for Cytoscape and can only be accessed through Cytoscape.
- Start Cytoscape
- Go to the Plugins Menu and select the MCODE sub-menu
Click Start MCODE
- The main MCODE interface will appear as a tab in the left-hand panel of Cytoscape (Note: If MCODE does not appear in the Plugins Menu, then revisit the installation section above.)
The MCODE sub-menu provides two additional options:
About MCODE
- Shows the MCODE credits, citation information, and a link to the MCODE paper.
Help
Links to the MCODE website at www.baderlab.org in your default web browser for quick access to downloads, contact information, and the User's Manual with help and tutorials.
New to Version 1.2: MCODE now allows easier access and more control over the underlying algorithm via the Cytopanel based consoles. Parameters are always viewable and modifiable, multiple results can be generated and compared, and clusters can be explored individually with interactive tools.
Getting and Interpreting Results
The MCODE Main Panel is the starting point for analysis. It contains two main sections: Find Cluster(s) and Advanced Options. The latter option is intended for fine-tuning of results by experienced users who are familiar with the MCODE paper (discussed in the next section). This section covers some of the basic steps of running MCODE on a network. Please see the the Screenshots section for a visual reference.
LOAD YOUR NETWORK. To begin, load the network to be analyzed into Cytoscape. You can load as many networks as your computer system can handle, large or small. MCODE will analyze either the network view that is on top or one selected in the Network Tab on the left-hand panel.
CHOOSE THE SCOPE. Clusters can be found in the entire network or from a selection of nodes. Chose an option in the Find Cluster(s) section of the main MCODE panel.
- Find Clusters in Whole Network
- MCODE will find and report all clusters in the entire network.
- Find Clusters from Selection
- Only those clusters which include the selected node(s) within them will be reported.
- Selections can be made either in the view, the Node Attribute Browser or Cytoscape's handy search tools.
- The choice of scope is dependent on your familiarity with the network in question and the desired outcome. If you have a particular protein of interest within a network, for example, it may be appropriate to search for only those clusters involving such a protein. On the other hand, exploratory work will benefit most from analyzing the whole network.
- Find Clusters in Whole Network
ANALYZE YOUR NETWORK. Next, press Analyze. This will display a progress meter of the scoring, finding, and drawing steps, provided that the task is not too quick.
- You may see several different messages at this step:
- The "No network" message
- This means that MCODE failed to detect a loaded network for analysis. You must load a network, and make sure it is selected, before you can analyze it.
- The "No selection" message
- This message appears when the Selection scope is used without an actual selection. You must select the desired node(s) before MCODE can attempt to find clusters.
- The "Parameters unchanged" message
- Parameters are discussed in detail in the following section. For now, you should know that if you attempt to analyze a network twice without changing any of the settings, such as the scope of the analysis, MCODE will let you know that this analysis was previously conducted and will just display the previously obtained results.
- The "No network" message
- You may see several different messages at this step:
BROWSE YOUR RESULTS. If analysis finds clusters, a new tab will appear in the right-hand panel displaying the result as "Result 1"
Cluster Browser:
On the left side, in the Network column, is a graphical representation of the cluster.
- Cluster members are coloured red.
The highest scoring node in the cluster is called the Seed. It is the node from which the cluster was derived and is represented as a square.
- Other cluster members are circles.
- Edges, representing interactions for example, are blue.
- Edge directionality is represented by cyan arrows.
On the right side, in the Details column, is a statistical summary of the cluster.
Rank is based on the cluster's computed Score and is used to identify the clusters within each result.
- For example, Cluster 1 is the highest ranked cluster in a given result, and thus, at the top of the list.
Nodes and Edges is a simple enumeration of the cluster's members and their interconnections.
Results can be discarded at any time by pressing the Discard Result button at the bottom of the panel.
Network View:
- If the network being analyzed has a view, MCODE will apply a custom visual style utilizing two MCODE generated node attributes as soon as the network is analyzed.
MCODE_Node_Status: Node shapes indicate the cluster status of the nodes.
- Square: seed (highest scoring node in the cluster)
- Circle: clustered
- Diamond: unclustered
MCODE_Score: Node colors represent the node score.
- A range from black to red indicates the MCODE computed node score (lowest to highest, respectively).
- White indicates a score of zero.
MCODE_Cluster: This is an additional list type attribute that indicates which cluster the node belongs to. The MCODE visual style does not use this attribute, but it exists should you need it. Note that if the Fluff parameter (discussed in the following section) is turned on, some nodes may belong to more than one cluster.
- If the network being analyzed has a view, MCODE will apply a custom visual style utilizing two MCODE generated node attributes as soon as the network is analyzed.
Cluster Selection:
- The clusters in the cluster browser table are selectable and will automatically select the corresponding nodes in the network view (if it exists). If no network view is available, the selected nodes can be reviewed in the Cytoscape Node Attribute Browser.
Secondly, a new Cluster Exploration Panel will appear below the Cluster Browser titled "Explore: Cluster [Rank]". This panel can be collapsed for now -- its use will be discussed in the Exploring Results section of this Manual.
Fine-Tuning Your Analysis
By default, MCODE analyzes networks using scoring and finding parameters that have been optimized to produce the best results for the average user and network. However, you may achieve better results for your network by familiarizing yourself with these parameters and changing them appropriately. Sometimes even slight customizations can produce considerable differences, reduce unwanted or false results, and increase relevance of results. This is only an overview -- for detailed parameter information, consult the MCODE paper.
Scoring Parameters
Include Loops
- When turned on, MCODE will include loops (self-edges) in the neighbourhood density calculation. This is expected to make a small difference in the results.
Degree Cutoff
- This value controls the minimum degree (number of connections) necessary in order for a node to be scored. For example, nodes that share only one connection with one other node have a degree of 1. Valid values are 2 or higher to prevent singly connected nodes from getting an artificially high node score.
Finding Parameters
Node Score Cutoff
This is the most influential parameter for cluster size and is the basis for the Size Threshold Slider in the Exploring Results section. During cluster expansion, new members are added only if their node score deviates from the cluster's seed node's score by less than the set cutoff. This is a percentage, where a value of 0.2 allows for new members' node scores to be no more than 20% less than that of the seed node. Thus, smaller values create smaller clusters and vice versa.
Haircut
- Once a cluster has been found, some nodes which may have satisfied the Degree Cutoff parameter during scoring may only be connected to the cluster by one edge. When haircut is turned on, MCODE removes all such singly-connected nodes from clusters. In some cases, though rare, the cluster's seed node may be only singly connected to the cluster and removed by the Haircut. For example, Cluster 2 of the galFiltered.gml network with default settings is one such case.
Fluff
- When turned on, MCODE expands cluster cores by one neighbour shell outwards, according to the fluff Node Density Cutoff parameter and after the optional haircut step.
Node Density Cutoff
- Node density is calculated by dividing the node's connections by the maximum number of connections possible for that node. If Fluff is turned on, this parameter controls the neighbour inclusion criteria during 'fluffing'. Fluff expansion occurs after the cluster has already been defined by the algorithm and thus allows clusters to overlap at their edges. A higher value will expand clusters more.
K-Core
- This parameter filters out clusters that do not contain a maximally inter-connected sub-cluster of at least k degrees. For example, a triangle (3 nodes, 3 edges) is a 2-core (2 connections per node). Two nodes with 2 edges between them satisfy the 2-core rule as well. Since the default value is 2, this ensures that clusters must in the very least contain one of these two sub-clusters. Increasing this value will exclude smaller clusters.
Max. Depth
- Maximum depth limits the distance from the seed node within which MCODE can search for cluster members. By default this is set to an arbitrarily large number so that clusters are virtually unlimited. To limit cluster size, set this parameter to a small number.
New to Version 1.2: The user can now analyze a network as many times as desired by modifying the parameters. Each result is stored sequentially for reference and comparison. Viewing different results will automatically rewrite the MCODE node attributes and re-visualize the network appropriately. Note that MCODE automatically determines which portion of the algorithm needs to be run based on the user's parameter modifications. For instance, if the scoring parameters are altered, the network will be re-scored, but if only the cluster finding parameters are altered, only the cluster finding portion will be run.
Exploring Results Interactively
In addition to fine-tuning a multitude of parameters to enhance the analysis process, MCODE provides a real-time cluster exploration feature. This can be divided into two components: exploring cluster boundaries and exploring cluster content. The first exploration allows you to expand or reduce the cluster based on the node score using the Size Threshold Slider. The second is the Node Attribute Enumerator which provides a summary of the cluster's node attributes and their frequency in the cluster. Together they can inform the user about the cluster's "natural" boundaries in the context of the network and ensure functional consistency. These are both explained in greater detail below. Figure 3 in the Screenshots section is a good reference for this text.
Size Threshold Slider
The slider scale ranges from Min to Max and has an 'origin' marker (^) for its starting position. Node Score Cutoff, which is the most influential cluster size determinant is controlled by the slider. As such, the initial position marker indicates the Node Score Cutoff value originally set in the Finding Parameters section. When moving the slider, the Node Score Cutoff is set to 0 at Min and 100 at Max, however there are several notable differences between the functions of the Size Threshold Slider and the Node Score Cutoff Finding Parameter.
- During exploration, the cluster is reevaluated without the requirements of satisfying the K-Core parameter. Thus, moving the slider leftwards of the initial position allows the cluster to be reduced to only the seed node.
- During exploration in the Max direction, the cluster is 'unaware' of other clusters. Unlike in the analysis where every subsequent attempt at finding a cluster is only allowed to expand around previously found clusters, the slider expands the cluster despite adjacent cluster borders. Thus, moving the slider rightwards of the initial position allows the cluster to be expanded to as much as the whole network.
- However, the 'awareness' of other clusters is intact in the range between the 'origin' marker and Min to allow the cluster to return to its original size.
Haircut and Fluff are applied after slider movement if they were turned on in the original production of the result that is being explored.
In response to the slider, the Cluster Browser is updated with the new cluster's network graphic and details (number of nodes and edges and new cluster score). The node selection in the main network view will also be updated. Since clusters can expand to large and sometimes unreasonable sizes, the layouter may need extra time to complete its task. When this occurs, a loader and progress bar will appear in the Cluster Browser. There is no need to wait for the cluster to be drawn, the details and node selections will remain responsive to the slider's movements. If the new cluster exceeds 300 nodes, a place holder ("Too big to show") will be drawn instead since the graphic representation will take too long to compute and will likely be too crowded to be of any real value.
Several peculiarities may arise during size exploration:
Cluster Size Explosion
- When exploring a lower ranked cluster (further down the list) the cluster's size may depend heavily on nearby higher ranked clusters. This may not always occur since the finding process starts at the highest scoring nodes while clusters are ranked afterwards based on their size and connectivity -- higher scoring seed nodes may not produce higher scoring clusters. Given that, when expanding a cluster, there may be an unexpected initial discontinuity in size since the Size Threshold Slider will ignore the presence of other clusters. If the cluster was produced around a low-scoring seed node then more nodes are likely to satisfy the Node Score Cutoff parameter. Such situations can indicate that the cluster in question may be part of a larger cluster.
Slider Dead-Zone
- Sometimes, on the other hand, moving the Size Threshold Slider a long distance may produce no changes in cluster size. In such cases, the seed node's score is so high compared to its immediate neighbourhood that the Node Score Cutoff must be increased greatly to include much lower scoring members. This indicates that the cluster is more or less well separated from the surrounding network by a local peak in node scores and as such, it is likely a well defined cluster.
No Change
- Lastly, if no changes occur during size exploration, the cluster in question is likely not connected to the larger network and as such cannot expand.
Node Attribute Enumerator
The Enumerator provides a numerical summary of node attribute values possessed by the currently explored cluster's members. It is meant to inform the user of the cluster's contents and aid in determining the cluster's functional relevance. All node attributes that are available for the loaded network are listed in the select box. When an attribute selection is made in one exploration, it persists for all cluster explorations within the given result.
The table below the select box has two columns:
Value
- This column lists all node attribute values that are possessed by the cluster being explored. With a simple string type attribute, such as MCODE_Node_Status, this list will never exceed the number of cluster members since every member can have only one value and some values may be shared by several members. However, list type attributes such as Gene Ontology (GO) terms may outnumber the cluster members since each member can have numerous values.
Occurrence
- This column simply displays the number of nodes possessing the particular attribute value listed in each row. The Enumerator table orders the list by the frequency in descending order where the most commonly occurring attribute value is listed on top.
- The Occurrence numbers are best interpreted when compared with the number of nodes in the cluster. For example, when enumerating Biological Process GO Terms, it may be a good indicator that the given cluster is biologically relevant if 9 of the 10 cluster members share some specific value.
In combination with the Size Threshold Slider, the Enumerator can be used to optimize clusters based on functional relevance. As the slider is being manipulated the Enumerator will automatically report changes in cluster content for the selected attribute. As such one can hone in on a size that, for example, reduces nodes with attribute values that are unrelated to some particular value of interest which is simultaneously maximized.
Note: At this stage of MCODE development, the Node Attribute Enumerator is a precursor to more automated methods of accomplishing similar attribute-enhanced clustering and statistical reporting.
Outputting Results
Create Sub-Network
Clusters can be output as sub or child-networks of the original network by clicking the Create Sub-Network button located on the cluster exploration panel which is opened when a cluster is selected in the Cluster Browser.
New to Version 1.2: Since exploration allows for a cluster size to change, the user can now create as many sub-networks of the same cluster as desired. New networks are named by their result set, cluster rank and score, for example: Result 1: Cluster 1 (Score 4.3).
Export as Text
Clusters can be summarized in a time-stamped tab-delimited text file consisting of:
- Cluster rank
- Cluster score (density multiplied by the number of members)
- Number of nodes
- Number of edges
- Cluster member IDs (comma-delimited)
The parameters used in scoring and finding the exported result are included in the file as well for future reference. The default parameter settings appear as:
- Network Scoring: Include Loops: false Degree Cutoff: 2 K-Core: 2
- Cluster Finding: Node Score Cutoff: 0.2 Haircut: true Fluff: false Max. Depth from Seed: 100
Screenshots
Figure 1: The MCODE Main Panel and MCODE Result Panel containing the Cluster Browser
|
|
Here the Advanced Options panels have been expanded while the Exploration panel has been collapsed. New to Version 1.2: The results have been streamlined to fit in Cytopanel 3 - Node IDs are still available through Export and the Node Attribute Browser. |
Figure 2: Sample Analyzed Network (Yeast, galFiltered.gml), before and after
|
|
|
On the left is a close up of the network before analysis, visualized with a sample visual style. Above, once clustered, the MCODE visual style differentiates seeds and clustered and unclustered nodes by shape (square, circle, diamond respectively). The red intensity in the node colour is correlated with the MCODE node score. White nodes are unscored and therefore unclustered. The yellow selection corresponds to a found cluster. |
Figure 3: The whole picture, MCODE in context
|
|
The Main and Result Panels appear as before, this time in their docked form and the Result Panel's exploration section has been expanded. The Cluster Browser selection is reflected in the network view and in the node attribute browser. |
Tutorials (Coming Soon)
BiNGO Validation
Cytoscape Tutorial
The makers of Cytoscape have compiled a network clustering example using MCODE and several other plugins. Though it is written for the previous version of MCODE, it should be easily transferable.
Cytoscape Tutorial: Section 7: Modules and Complexes