|
Size: 2583
Comment:
|
Size: 11032
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| '''~+User Manual+~''' <<TableOfContents(5)>> |
'''~+User Manual+~''' <<TableOfContents(5)>> |
| Line 5: | Line 4: |
| The Semantic Summary Cytoscape Plugin allows you to visualize a selected set of nodes in a network as a word tag cloud. It will operate on any Cytoscape network. The tag cloud can be built based up the words in the node ID's or the words appearing in any node attribute that is comprised of Strings, or a List of Strings. The size of the words appearing in the word tag cloud is representative of the word's importance for the node selection as a function of the number of times the word appears in the selected nodes and the entire network for the selected node attribute. | The Semantic Network Summary is a Cytsocape plugin that generates a word tag cloud from a user-defined node selection, summarizing an attribute of choice. For instance, if selected nodes are proteins, and the string attribute "full protein name" is selected, every string will be broken down into words, which will be plotted on a panel with size proportional to their frequency. {{attachment:Example_Cloud1.png}} It is also possible to use the plugin to cluster words that appear together in the selected nodes. For instance, if node A has name attribute "Origin Recognition Complex 1" and node B has name attribute "Origin Recognition Complex 2", then the words "Origin", "Recognition" and "Complex" will be clustered together, following the order in which they appear. The plugin operates on any network and on any selected attributes, although it has been specifically designed for string attributes such as gene names or gene ontology annotations. {{attachment:Example_Cloud2.png}} |
| Line 8: | Line 13: |
| The Semantic Network Summary Plugin requires Cytoscape Version 2.7.x. If you don't have Cytoscape or have an older Version (2.6 or older), please download the latest Release from http://www.cytoscape.org/ and install it on your computer. * Download the Semantic Network Summary Plugin from [[GSoC2010_SoftwareDownload|here]] and manually place the file 'SemanticSummary.jar' in the 'Cytoscape/plugins' folder. |
|
| Line 12: | Line 20: |
| 1. Right click on a node in the network and select "Create Cloud". This will create a Semantic Summary Word Cloud using all of the default parameters.<<BR>> 2. Under the Plugins Menu, select Semantic Network Summary >> Create Cloud. This will create a Semantic Summary Word Cloud using all of the default parameters.<<BR>> 3. Under the Plugins Menu, select Semantic Network Summary >> Settings. This will load the Semantic Summary Input Panel on the left side of the screen. At the bottom right corner of this panel is a button labeled "Create" that will also create a Semantic Summary Word Cloud.<<BR>> |
* Right click on a node in the network and select "Create Cloud". This will create a Semantic Summary Word Cloud using all of the default parameters. * Under the Plugins Menu, select Semantic Network Summary / Create Cloud. This will create a Semantic Summary Word Cloud using all of the default parameters. * Under the Plugins Menu, select Semantic Network Summary / Settings. This will load the Semantic Summary Input Panel on the left side of the screen in the control panel. At the bottom right corner of this panel is a button labeled "Create" that will also create a Semantic Summary Word Cloud. |
| Line 19: | Line 28: |
| * The "Network" tab in the "Control Panel" on the left lists all available networks in the current session and at the bottom has an overview of the current network which allows for easy navigation in a network, even a high zoom levels by dragging the blue rectangle (the current view) over the network. * The "Semantic Summary" tab will be loaded into the "Control Panel" on the left whenever a Semantic Summary Word Cloud is first created, or the Semantic Network Summary >> Settings option is selected from the Plugins Menu. This tab contains a list of all Word Clouds created for the currently selected Network as well as all of the parameters that can be set by a user. |
* The "Network" tab in the "Control Panel" on the left lists all available networks in the current session. At the bottom it also has an overview of the current network which allows for easy navigation in a network, as well as high zoom levels which can be obtained by dragging the blue rectangle (the current view) over the network. * The "Semantic Summary" tab will be loaded into the "Control Panel" on the left whenever a Semantic Summary Word Cloud is first created, or the Semantic Network Summary / Settings option is selected from the Plugins Menu. This tab contains a list of all Word Clouds created for the currently selected Network as well as all of the parameters that can be set by a user on both the cloud and the network level. |
| Line 22: | Line 31: |
=== Advanced Tips === * With large networks and low zoom-levels Cytoscape automatically reduces the details (such as hiding the node labels and not showing the node borders). To override this mechanism click on "View / Show Graphics Details" * To see which nodes in the network contain a word in the tag cloud, click on the word in the tag cloud in the data panel. If a Network View is available for the network from which the cloud was created, all nodes in the network that contain the specified word in the chosen attribute will be highlighted. ----- == Full User Guide == <<Anchor(parameters)>> === Tips on Parameter Choice === ==== Attribute Choice ==== You can choose which Cytoscape attribute to build your word cloud from in the Semantic Analysis section of the Input panel. Your options include the node ID (the default option) and all currently available attributes of the type String or List. Notice, that for an attribute of type List, only those entries that are String will be used to build the word cloud. When changing the attribute that a cloud is built from, a user must hit the "Update" button to see the updated results for the current cloud. ==== Network Normalization ==== The Network Normalization parameter determines how much weight to give the word counts over the entire network when determining word size. Specifically, the size of any word W in a tag cloud is directly proportional to: (sel_W / sel_tot) / (net_W / net_tot)^k, where sel_W is the number of selected nodes that contain W, sel_tot is the total number of selected nodes, net_W is the number of nodes in the entire network that contain W, net_tot is the total number of nodes in the network, and k is the network normalization factor. The Network Normalization parameter determines how much the frequency in the network down-weights the size of a word. * Network Normalization = 0 --> there is no network normalization, the size of a word is simply proportional to its frequency in the node selection * Network Normalization = 1 --> maximal network normalization The default value is 1. ==== Word Aggregation Cutoff ==== Word aggregation cutoff is a parameter used only with cloud layouts that incorporate word clustering.. The Semantic Network Summary Plugin uses a greedy algorithm in combination with heirarchical clustering to create the word clusters that a user will see. The word clusters are built by aggregating pairs of words. Words are aggregated in such a way that their order in the cluster reflects which words appear next to each other in the selected nodes in the network. The algorithm used for word aggregation utilizes a probability value given to every ordered pair of words that appears next to each other in at least one selected node in the network. This probability value is the ratio of the observed joint probability of these words appearing next to each other, divided by the probability of these words appearing next to each other if their occurences were independent of each other. Only word pairs having this probability value above or equal to the Word Aggregation Cutoff can appear next to each other in a single cluster. Smaller values for this parameter will usually translate to larger clusters of words. If this parameter is sufficiently large, every word will appear in its own cluster. ==== Cloud Layout ==== The choice of cloud layout style will affect the look and feel of the word tag cloud that appears. This is also where a user will determine if they want their word tag cloud to include clustering. Below are examples of the same word cloud with the different layout style options. Clustered-Standard: {{attachment:Style-Clustered-Standard.png|Style-Clustered-Standard.jpg}} Clustered-Boxes: {{attachment:Style-Clustered-Boxes.png|Style-Clustered-Boxes.jpg}} Non-Clustered: {{attachment:Style-Non-Clustered.png}} === The Input Panel === {{attachment:Input_Panel.png|Input_Panel.jpg}} 1. '''Cloud List''' - A list of all clouds that exist for the current network. If no network is currently selected, then this section will display "No Network Loaded". A cloud can be renamed by selecting the cloud in the list, right clicking on the mouse and selecting "Edit Cloud Name". No two clouds for the same network can have the same name. By default the clouds will be named using sequential numbering. 2. '''Semantic Analysis''' - Allows the user to specify which attribute to use when building the word cloud. 3. '''Advanced Parameters''' - User can specify the maximum number of words to display in the word cloud, as well as the [[#parameters|Network Normalization]] and [[#parameters|Word Aggregation Cutoff]]. 4. '''Word Exclusion List''' - A user can add or remove words to be ignored when building the word cloud. The list of words to filter out is applicable at the network level. Hence, any words added or removed while a particular cloud is selected in the cloud list will affect all future clouds created or updated from the network associated with that cloud. * This list initially contains a set of commonly occuring English "Stop Words" that are automatically filtered out. * This list initially contains a set of commonly occuring "Flagged Words" (e.g. kegg, reactome) that are automatically filtered out. 5. '''Cloud Layout''' - The user has a choice of serveral different styles for the layout of the word tag cloud. This is where a user will select whether or not they want to see a layout that includes clustering. 6. '''Actions''' - The user has three choices: Delete (deletes the currently selected cloud, Update (takes in all parameters, the set of currently selected nodes, and all nodes in the network and builds an updated word cloud), and Create (takes in all parameters, the set of currently selected nodes, and all nodes in the network and builds a new word cloud). === The Cloud Display Panel === * Appears in the bottom (south) data panel. * Is refreshed every time a cloud is selected from the input panel, a network is brought into focus, a cloud is created, updated or deleted. * If a network view is available for the current network, clicking on a word in the currently displaying word cloud will highlight all nodes in the network that currently contain that word in the attribute that the word cloud was created using. === Default and Valid Parameter Values === '''Node ID/Attribute:''' * Defines which node value to use for semantic analysis. * Default Value: node ID '''Max Num of Words''': * Determines the maximum number of words to display in the Cloud Display Panel. If the this number is less than the total number of possible words, only the most significant words will be displayed. * Default Value: 250 * Valid Values: >=0 '''Network Normalization''': * Network Normalization weight used when calculated word size - see [[#parameters|parameter tips]] for more details. * Default Value: 1 * Valid Values: >=0.0, <=1.0 '''Word Aggregation Cutoff''': * Minimal acceptable probability value for any pair of words to appear next to each other in a cluster - see [[#parameters|parameter tips]] for more details. * Default Value: 1 * Valid Values: >=0.0, <=1.0 '''Style''': * Visual style for the cloud layout * Devault Value: Clustered-Standard - a layout style where the words are clustered into groups. All the words in a single cluster will appear in together in the cloud in a unified color. |
User Manual
Overview
The Semantic Network Summary is a Cytsocape plugin that generates a word tag cloud from a user-defined node selection, summarizing an attribute of choice. For instance, if selected nodes are proteins, and the string attribute "full protein name" is selected, every string will be broken down into words, which will be plotted on a panel with size proportional to their frequency.
It is also possible to use the plugin to cluster words that appear together in the selected nodes. For instance, if node A has name attribute "Origin Recognition Complex 1" and node B has name attribute "Origin Recognition Complex 2", then the words "Origin", "Recognition" and "Complex" will be clustered together, following the order in which they appear. The plugin operates on any network and on any selected attributes, although it has been specifically designed for string attributes such as gene names or gene ontology annotations.
Installation
The Semantic Network Summary Plugin requires Cytoscape Version 2.7.x. If you don't have Cytoscape or have an older Version (2.6 or older), please download the latest Release from http://www.cytoscape.org/ and install it on your computer.
Download the Semantic Network Summary Plugin from here and manually place the file 'SemanticSummary.jar' in the 'Cytoscape/plugins' folder.
Quick Start Guide
Creating a Semantic Summary Word Cloud
After loading a Cytoscape network, and selecting the nodes of interest, there are 3 locations from which you can create a Semantic Summary Word Cloud.
- Right click on a node in the network and select "Create Cloud". This will create a Semantic Summary Word Cloud using all of the default parameters.
- Under the Plugins Menu, select Semantic Network Summary / Create Cloud. This will create a Semantic Summary Word Cloud using all of the default parameters.
- Under the Plugins Menu, select Semantic Network Summary / Settings. This will load the Semantic Summary Input Panel on the left side of the screen in the control panel. At the bottom right corner of this panel is a button labeled "Create" that will also create a Semantic Summary Word Cloud.
You can use the parameter defaults for all of these methods for creating a Semantic Summary Word Cloud. For a more careful choice of the parameter settings, please go to the Full User Guide.
Exploring the Semantic Summary Word Cloud
- The "Network" tab in the "Control Panel" on the left lists all available networks in the current session. At the bottom it also has an overview of the current network which allows for easy navigation in a network, as well as high zoom levels which can be obtained by dragging the blue rectangle (the current view) over the network.
- The "Semantic Summary" tab will be loaded into the "Control Panel" on the left whenever a Semantic Summary Word Cloud is first created, or the Semantic Network Summary / Settings option is selected from the Plugins Menu. This tab contains a list of all Word Clouds created for the currently selected Network as well as all of the parameters that can be set by a user on both the cloud and the network level.
- The "Semantic Summary Cloud" tab in the "Data Panel" on the bottom side of the window is where a Semantic Summary Word Cloud will be displayed.
Advanced Tips
- With large networks and low zoom-levels Cytoscape automatically reduces the details (such as hiding the node labels and not showing the node borders). To override this mechanism click on "View / Show Graphics Details"
- To see which nodes in the network contain a word in the tag cloud, click on the word in the tag cloud in the data panel. If a Network View is available for the network from which the cloud was created, all nodes in the network that contain the specified word in the chosen attribute will be highlighted.
Full User Guide
Tips on Parameter Choice
Attribute Choice
You can choose which Cytoscape attribute to build your word cloud from in the Semantic Analysis section of the Input panel. Your options include the node ID (the default option) and all currently available attributes of the type String or List. Notice, that for an attribute of type List, only those entries that are String will be used to build the word cloud. When changing the attribute that a cloud is built from, a user must hit the "Update" button to see the updated results for the current cloud.
Network Normalization
The Network Normalization parameter determines how much weight to give the word counts over the entire network when determining word size. Specifically, the size of any word W in a tag cloud is directly proportional to: (sel_W / sel_tot) / (net_W / net_tot)^k, where sel_W is the number of selected nodes that contain W, sel_tot is the total number of selected nodes, net_W is the number of nodes in the entire network that contain W, net_tot is the total number of nodes in the network, and k is the network normalization factor.
The Network Normalization parameter determines how much the frequency in the network down-weights the size of a word.
Network Normalization = 0 --> there is no network normalization, the size of a word is simply proportional to its frequency in the node selection
Network Normalization = 1 --> maximal network normalization
The default value is 1.
Word Aggregation Cutoff
Word aggregation cutoff is a parameter used only with cloud layouts that incorporate word clustering.. The Semantic Network Summary Plugin uses a greedy algorithm in combination with heirarchical clustering to create the word clusters that a user will see. The word clusters are built by aggregating pairs of words. Words are aggregated in such a way that their order in the cluster reflects which words appear next to each other in the selected nodes in the network.
The algorithm used for word aggregation utilizes a probability value given to every ordered pair of words that appears next to each other in at least one selected node in the network. This probability value is the ratio of the observed joint probability of these words appearing next to each other, divided by the probability of these words appearing next to each other if their occurences were independent of each other. Only word pairs having this probability value above or equal to the Word Aggregation Cutoff can appear next to each other in a single cluster.
Smaller values for this parameter will usually translate to larger clusters of words. If this parameter is sufficiently large, every word will appear in its own cluster.
Cloud Layout
The choice of cloud layout style will affect the look and feel of the word tag cloud that appears. This is also where a user will determine if they want their word tag cloud to include clustering. Below are examples of the same word cloud with the different layout style options.
Clustered-Standard:
Clustered-Boxes:
Non-Clustered:
The Input Panel
![[ATTACH]](/Software/WordCloudPlugin/UserManual?action=AttachFile&do=upload_form&ticket=00673448e4.09c48928cb0db5f315c64437a1034a7cb73f617e&target=Input_Panel.png "[ATTACH]"){kind=small}
1. Cloud List - A list of all clouds that exist for the current network. If no network is currently selected, then this section will display "No Network Loaded". A cloud can be renamed by selecting the cloud in the list, right clicking on the mouse and selecting "Edit Cloud Name". No two clouds for the same network can have the same name. By default the clouds will be named using sequential numbering.
2. Semantic Analysis - Allows the user to specify which attribute to use when building the word cloud.
3. Advanced Parameters - User can specify the maximum number of words to display in the word cloud, as well as the Network Normalization and Word Aggregation Cutoff.
4. Word Exclusion List - A user can add or remove words to be ignored when building the word cloud. The list of words to filter out is applicable at the network level. Hence, any words added or removed while a particular cloud is selected in the cloud list will affect all future clouds created or updated from the network associated with that cloud.
- This list initially contains a set of commonly occuring English "Stop Words" that are automatically filtered out.
- This list initially contains a set of commonly occuring "Flagged Words" (e.g. kegg, reactome) that are automatically filtered out.
5. Cloud Layout - The user has a choice of serveral different styles for the layout of the word tag cloud. This is where a user will select whether or not they want to see a layout that includes clustering.
6. Actions - The user has three choices: Delete (deletes the currently selected cloud, Update (takes in all parameters, the set of currently selected nodes, and all nodes in the network and builds an updated word cloud), and Create (takes in all parameters, the set of currently selected nodes, and all nodes in the network and builds a new word cloud).
The Cloud Display Panel
- Appears in the bottom (south) data panel.
- Is refreshed every time a cloud is selected from the input panel, a network is brought into focus, a cloud is created, updated or deleted.
- If a network view is available for the current network, clicking on a word in the currently displaying word cloud will highlight all nodes in the network that currently contain that word in the attribute that the word cloud was created using.
Default and Valid Parameter Values
Node ID/Attribute:
- Defines which node value to use for semantic analysis.
- Default Value: node ID
Max Num of Words:
- Determines the maximum number of words to display in the Cloud Display Panel. If the this number is less than the total number of possible words, only the most significant words will be displayed.
- Default Value: 250
Valid Values: >=0
Network Normalization:
Network Normalization weight used when calculated word size - see parameter tips for more details.
- Default Value: 1
Valid Values: >=0.0, <=1.0
Word Aggregation Cutoff:
Minimal acceptable probability value for any pair of words to appear next to each other in a cluster - see parameter tips for more details.
- Default Value: 1
Valid Values: >=0.0, <=1.0
Style:
- Visual style for the cloud layout
- Devault Value: Clustered-Standard - a layout style where the words are clustered into groups. All the words in a single cluster will appear in together in the cloud in a unified color.