Differences between revisions 2 and 17 (spanning 15 versions)

AutoAnnotate Logo

AutoAnnotate: User Guide

Contents

AutoAnnotate: User Guide

Getting Started (Installing)

Requirements

Cytoscape minimum version 3.3
WordCloud minimum version 3.1.0
clusterMaker2 minimum version 0.9.5

Installation

Install Cytoscape
- If you don’t have Cytoscape please download and install the latest release from http://www.cytoscape.org/download.php.
Install AutoAnnotate
- Open Cytoscape
- In the main menu select Apps > App Manager
- In the App Manager select AutoAnnotate in the list of All Apps and click the Install button.
- The WordCloud app will also be installed automatically along with AutoAnnotate
Install clusterMaker2 (optional, but highly recommended)
- In the App Manager select clusterMaker2 in the list of All Apps and click the Install button.

Alternatively AutoAnnotate and clusterMaker2 can be installed from the App Store website.

AutoAnnotate on the App Store: http://apps.cytoscape.org/apps/autoannotate
clusterMaker2 on the App Store: http://apps.cytoscape.org/apps/clustermaker2

Creating an Annotation Set

Start by selecting a network view.
In the main menu select Apps > AutoAnnotate > New Annotation Set…
The Create Annotation Set dialog will open.

Create Annotation Set Dialog

This dialog is used to select the options for creating an Annotation Set.
- Note: AutoAnnotate can detect if the network was created by EnrichmentMap, and if so sensible defaults for EnrichmentMap networks will be pre-selected.
- Note: You may manually edit the contents and labels of the clusters after the Annotation Set is created, and you may create as many Annotation Sets as you like, so its not critical to get everything perfect at this step.

Cluster Options
- Use clusterMaker App
  - If this is selected then clusterMaker will be used to calculate the clusters.
- Cluster algorithm:
  - Used to select the clustering algorithm provided by clusterMaker that will be used to calculate the clusters.
  - See the table below for a list of clusterMaker algorithms currently available for use in AutoAnnotate.
- Edge weight column:
  - Some clusterMaker algorithms use edge weights. This box is used to select the Edge Column to use for the edge weights. If the selected algorithm does not use edge weights then this box will be disabled (greyed out).
- User-defined clusters
  - You may provide your own clusters or use another clustering app to calculate the clusters. In this case the clusters must already be calculated and cluster identifiers must be stored in a Node Column.
  - Any Node Column of discrete type may be used to identify the clusters. (String, Integer, Long Integer, Boolean, or Lists of any of those types.)
  - If you select a column of List type then the clusters may overlap.
Label Options
- Label Column
  - Select a Node Column of type String that will be used to calculate the cluster labels.
- Label Algorithm
  - Select an algorithm that is used to calculuate the label for each cluster.
  - Two label algorithms are currently available:
    1. WordCloud: Adjacent Words
      - Uses the WordCloud app to calculate the labels.
      - Basically the same algorithm that is used by the "Cloud Style: Clustered Standard" option in WordCloud.
      - Words in the label are chosen from the most frequent words in the cluster, and words that are adjacent to the most frequent words.
      - The higher the "adjacent word bonus" is, the more likely adjacent words will be in the label.
    2. WordCloud: Largest Words
      - Uses the WordCloud app to calculate the labels.
      - Basically the same algorithm that is used by the "Cloud Style: No Clustering" option in WordCloud.
      - Words in the label are chosen from the most frequent words in the cluster.
Click Create Annotations to create the new Annotation Set.

WARNING: AutoAnnotate will manage all groups (compound nodes) for the current network view. It is not recommended to manually create groups on a network view that has Annotation Sets. If you would like to manually create groups at any time please duplicate the network view.

ClusterMaker2 Algorithms

The following clusterMaker2 algorithms are made available in AutoAnnotate:

Algorithm	Weighted?
Affinity Propagation Cluster	Yes
Cluster Fuzzifier	Yes
Community cluster (GLay)	No
ConnectedComponents Cluster	Yes
Fuzzy C-Means Cluster	Yes
MCL Cluster	Yes
SCPS Cluster	Yes

Weighted algorithms require an edge attribute to be used as the edge weight.

Panels

When an Annotation Set is created the AutoAnnotate panels will be shown.
Note: To show or hide the AutoAnnotate panels at any time go to the main menu and select Apps > AutoAnnotate > (Show/Hide) AutoAnnotate.

In the Control Panel on the left side is the main AutoAnnotate panel.
- This panel is used to manage Annotation Sets and Clusters.
In the Results Panel on the right side is the AutoAnnotate Display panel.
- This panel is used to modify the look of the annotations.

Changing Display Options

This AutoAnnotate Display panel shows display options for the currently selected Annotation Set.

Border width
- Slider that adjusts the width of the cluster annotation borders.
Opacity
- Slider that adjusts the opacity of the cluster annotation fill color.
- Slide to the left for completely transparent. Slide to the right for completely opaque.
Font Size
- Scale font by cluster size
  - When selected the size of the label will be relative to the number of nodes in the cluster. Larger clusters will have larger labels.
  - When deselected all the clusters will have the same size labels.
- Slider is used to adjust the font size or font scale.
Shape
- There are two available shapes: Ellipse or Rectangle
Hide Clusters
- Select to hide all cluster shape annotations.
Hide Labels
- Select to hide all cluster labels.

Managing Annotation Sets

The main AutoAnnotate panel is used to manage Annotation Sets.

At the top of the panel is a dropdown box that allows you to switch between all of the Annotation Sets that have been created for the current network view.
- Select the (none) option to clear all annotations from the view.
- Select an Annotation Set to show all the annotations and labels in that set.
- When switching between Annotation Sets all the annotations in the view will be erased and redrawn.
  - Similarly when switching Annotation Sets any collapsed groups will be expanded.

Next to the dropdown box is the menu button. Click this button to show the Annotation Set Menu.
- New Annotation Set…
  - Shows the Create Annotation Set dialog.
- Rename
  - Renames the current annotation set
- Delete...
  - Deletes the current annotation set
- Collapse All
  - Collapses all the clusters
- Expand all
  - Expands all the clusters
- Layout Clusters
  - Runs a layout algorithm that will layout each cluster separately using the perfuse layout (evenly spaced in a grid). Note: this operation cannot be undone.
- Redraw annotations
  - Sometimes the annotations may need to be redrawn.
- Recalculate Labels
  - Recalculates the labels for the selected clusters. Typically used when the WordCloud options or label algorithm changes. More on this later in this guide.
- Label Options
  - Opens a dialog where you can select the label algorithm that is used when recalculating labels.
- Settings...
  - Opens the AutoAnnotate settings dialog.

Managing Clusters in the AutoAnnotate Panel

On the main AutoAnnotate panel you will find the Cluster Table.

This table shows each cluster, along with its label, the number of nodes in the cluster and a checkbox icon that indicates if the cluster has been collapsed.
- Click on a table header to sort the table by that column.

Most of the cluster options are available using the context menu of the cluster table.

Start by selecting one or more clusters in the cluster table.
To select multiple clusters hold the Shift key to select a range or hold the Ctrl/Command key to select individual clusters.

Right click with he mouse to show the cluster table context menu.
- Rename…
  - Enabled when 1 cluster is selected.
  - Manually set the label for the cluster.
- Delete
  - Delete the cluster annotations
    - Note: This does not delete the nodes or edges in the cluster, just the annotations.
- Merge
  - Enabled when 2 or more clusters are selected.
  - Merges the clusters into a single cluster.
  - A new label for the merged cluster is automatically calculated.
- Extract Clusters…
  - Creates a new Annotation Set consisting of the selected clusters.
- Collapse
  - Collapses the selected clusters
- Expand
  - Expands the selected clusters
- Recalculate Labels
  - Recalculates the labels for the selected clusters.

Managing Clusters in the Network View

Manually create a cluster
- Select some nodes in the network view, right click to show the context menu, and select Apps > AutoAnnotate > Create Cluster.
  - A new cluster is created.
  - A label for the cluster is automatically calculated.
  - The cluster is selected in the cluster table.
Deleting a node in an existing cluster will remove the node from the cluster.
- A new label is calculated.

Collapsing and Expanding Clusters

Clusters can be collapsed or expanded from the Annotation Set Menu or the Cluster Table Context Menu.

Before collapsing clusters make sure that node aggregation is enabled. If not enabled then collapsed clusters may not have a label.
- In the main menu select Edit > Preferences > Group Preferences.
- In the Group Preferences dialog select the option for Enable Attribute Aggregation.

When a cluster is collapsed a group node is created that contains the cluster and it is collapsed. The annotation for the cluster is not shown when the cluster is collapsed.
When a cluster is expanded the group node is expanded and then deleted. The annotation is show again.
It is not recommend to manually collapse or expand clusters using the Groups menu as this may confuse AutoAnnotate.
When switching between Annotation Sets all collapsed clusters are automatically expanded.

Working with WordCloud

Labels for clusters are generated by the WordCloud app.

You may change the label generation options from the WordCloud panel.
In the main menu select Apps > WordCloud > Show WordCloud.
In the WordCloud panel you can change the label options, for example using the Normalize slider.
Back in the AutoAnnotate panel select Recalculate Labels to regenerate labels using the updated WordCloud options.

Saving and Restoring a Session with Annotation Sets

There are currently some limitations in Cytoscape with regards to saving and restoring annotations and groups in a session file.
For this reason when you save your session all the clusters must be expanded first. This is planned to be fixed in future versions of Cytoscape and AutoAnnotate.
When you restore a session it defaults back to (none) for each Network View. Simply select the annotation set again to redraw the annotations.

Additional Options

AutoAnnotate has various warning dialogs that can be dismissed permanently by selecting "don’t show this again". If you would like to see these warnings again they can be re-enabled. In the main menu select Edit > Preferences > Properties, then select org.baderlab.autoannotate in the Properties Dialog.

Filing Bug Reports and Requesting Enhancements

Thank you for using AutoAnnotate. Your feedback is important and helps us to improve the App for everyone. If you have any comments, requests for new features or enhancements, or bugs to report, please enter them on the AutoAnnotate github issue tracker.

https://github.com/BaderLab/AutoAnnotateApp/issues

-  ⇤ ← Revision 2 as of 2016-01-27 22:39:09 → 
  Size: 1434
  Editor: MikeKucera
  Comment:
+   ← Revision 17 as of 2016-03-07 16:03:28 → ⇥
  Size: 13171
  Editor: MikeKucera
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
+{{attachment:auto_annotate_logo_128by128_v5.png|AutoAnnotate Logo|align="right"}}<<BR>>
-Line 2:
+Line 3:
-== Overview ==

AutoAnnotate is a Cytoscape App that finds clusters and visually annotates them with labels and groups. These visualizations provide a concise visual summary which is helpful for network analysis and interpretation.

AutoAnnotate started as a feature of the EnrichmentMap App but has since been extracted into its own standalone App.

== Getting Started ==
+<<TableOfContents(5)>>

== Getting Started (Installing)  ==
-Line 12:
+Line 8:
- * Java 8
-Line 19:
+Line 14:
-   * If you don’t have Cytoscape please download the latest release from http://www.cytoscape.org/download.php and install it on your computer.
+  * If you don’t have Cytoscape please download and install the latest release from http://www.cytoscape.org/download.php.
-Line 21:
+Line 16:
-   * Open Cytoscape
   * In the main menu select Apps > App Manager
   * In the App Manager select AutoAnnotate in the list of All Apps and click the Install button.
   * The WordCloud app will also be installed automatically along with AutoAnnotate
+  * Open Cytoscape
  * In the main menu select '''Apps > App Manager'''
  * In the '''App Manager''' select '''AutoAnnotate''' in the list of '''All Apps''' and click the '''Install''' button.
  * The '''WordCloud''' app will also be installed automatically along with AutoAnnotate
-Line 26:
+Line 21:
-   * In the App Manager select clusterMaker2 in the list of All Apps and click the Install button.
+  * In the '''App Manager''' select '''clusterMaker2''' in the list of '''All Apps''' and click the '''Install''' button.
-Line 29:
+Line 24:
- * AutoAnnotate on the App Store:
+ * AutoAnnotate on the App Store: http://apps.cytoscape.org/apps/autoannotate
-Line 33:
+Line 28:
+== Creating an Annotation Set ==

 * Start by selecting a network view.
 * In the main menu select '''Apps > AutoAnnotate > New Annotation Set…'''
 * The '''Create Annotation Set''' dialog will open.
-Line 34:
+Line 35:
+=== Create Annotation Set Dialog ===

 * This dialog is used to select the options for creating an Annotation Set.
  * Note: AutoAnnotate can detect if the network was created by EnrichmentMap, and if so sensible defaults for EnrichmentMap networks will be pre-selected.
  * Note: You may manually edit the contents and labels of the clusters after the Annotation Set is created, and you may create as many Annotation Sets as you like, so its not critical to get everything perfect at this step.

{{attachment:aa_user_guide_2.png||width=300}}

 * Cluster Options
   * Use clusterMaker App
     * If this is selected then clusterMaker will be used to calculate the clusters.
   * Cluster algorithm:
     * Used to select the clustering algorithm provided by clusterMaker that will be used to calculate the clusters.
     * See the table below for a list of clusterMaker algorithms currently available for use in AutoAnnotate.
   * Edge weight column:
     * Some clusterMaker algorithms use edge weights. This box is used to select the Edge Column to use for the edge weights. If the selected algorithm does not use edge weights then this box will be disabled (greyed out). 
   * User-defined clusters
     * You may provide your own clusters or use another clustering app to calculate the clusters. In this case the clusters must already be calculated and cluster identifiers must be stored in a Node Column.
     * Any Node Column of discrete type may be used to identify the clusters. (String, Integer, Long Integer, Boolean, or Lists of any of those types.)
     * If you select a column of List type then the clusters may overlap.
 
 * Label Options
   * Label Column
     * Select a Node Column of type ''String'' that will be used to calculate the cluster labels.
   * Label Algorithm
     * Select an algorithm that is used to calculuate the label for each cluster.
     * Two label algorithms are currently available:
       1. WordCloud: Adjacent Words
          * Uses the WordCloud app to calculate the labels.
          * Basically the same algorithm that is used by the "Cloud Style: Clustered Standard" option in WordCloud.
          * Words in the label are chosen from the most frequent words in the cluster, and words that are adjacent to the most frequent words.
   * The higher the "adjacent word bonus" is, the more likely adjacent words will be in the label.
       2. WordCloud: Largest Words
          * Uses the WordCloud app to calculate the labels.
          * Basically the same algorithm that is used by the "Cloud Style: No Clustering" option in WordCloud.
          * Words in the label are chosen from the most frequent words in the cluster.

 * Click '''Create Annotations''' to create the new Annotation Set.

'''WARNING:''' AutoAnnotate will manage all groups (compound nodes) for the current network view. It is not recommended to manually create groups on a network view that has Annotation Sets.  If you would like to manually create groups at any time please duplicate the network view.

== ClusterMaker2 Algorithms ==

The following clusterMaker2 algorithms are made available in AutoAnnotate:
|| '''Algorithm''' || '''Weighted?''' ||
|| Affinity Propagation Cluster || Yes ||
|| Cluster Fuzzifier || Yes ||
|| Community cluster (GLay) || No ||
|| ConnectedComponents Cluster || Yes ||
|| Fuzzy C-Means Cluster || Yes ||
|| MCL Cluster || Yes ||
|| SCPS Cluster || Yes ||

Weighted algorithms require an edge attribute to be used as the edge weight.

== Panels ==

 * When an Annotation Set is created the AutoAnnotate panels will be shown.
 *  Note: To show or hide the AutoAnnotate panels at any time go to the main menu and select '''Apps > AutoAnnotate > (Show/Hide) AutoAnnotate'''.

{{attachment:aa_user_guide_3.png||width=500}}

 * In the '''Control Panel''' on the left side is the main '''AutoAnnotate''' panel.
   * This panel is used to manage Annotation Sets and Clusters.
 * In the '''Results Panel''' on the right side is the '''AutoAnnotate Display''' panel.
   * This panel is used to modify the look of the annotations.

== Changing Display Options ==

This '''AutoAnnotate Display''' panel shows display options for the currently selected Annotation Set. 

{{attachment:aa_user_guide_4.png||width=180}}

 * Border width
   * Slider that adjusts the width of the cluster annotation borders.
 * Opacity
   * Slider that adjusts the opacity of the cluster annotation fill color.
   * Slide to the left for completely transparent. Slide to the right for completely opaque.
 * Font Size
   * Scale font by cluster size
     * When selected the size of the label will be relative to the number of nodes in the cluster. Larger clusters will have larger labels.
     * When deselected all the clusters will have the same size labels.
   * Slider is used to adjust the font size or font scale.
 * Shape
   * There are two available shapes: Ellipse or Rectangle
 * Hide Clusters
   * Select to hide all cluster shape annotations.
 * Hide Labels
   * Select to hide all cluster labels.


== Managing Annotation Sets ==

The main AutoAnnotate panel is used to manage Annotation Sets.

{{attachment:aa_user_guide_5.png||width=300}}

 * At the top of the panel is a '''dropdown box''' that allows you to switch between all of the Annotation Sets that have been created for the current network view.
   * Select the (none) option to clear all annotations from the view.
   * Select an Annotation Set to show all the annotations and labels in that set.
   * When switching between Annotation Sets all the annotations in the view will be erased and redrawn.
     * Similarly when switching Annotation Sets any collapsed groups will be expanded.

{{attachment:aa_user_guide_6.png||width=300}}

 * Next to the dropdown box is the menu button. Click this button to show the Annotation Set Menu.
  * New Annotation Set…
   * Shows the Create Annotation Set dialog.
  * Rename
   * Renames the current annotation set
  * Delete...
   * Deletes the current annotation set
  * Collapse All
   * Collapses all the clusters
  * Expand all
   * Expands all the clusters
  * Layout Clusters
   * Runs a layout algorithm that will layout each cluster separately using the perfuse layout (evenly spaced in a grid). Note: this operation cannot be undone.
  * Redraw annotations
   * Sometimes the annotations may need to be redrawn.
  * Recalculate Labels
   * Recalculates the labels for the selected clusters. Typically used when the WordCloud options or label algorithm changes. More on this later in this guide.
  * Label Options
   * Opens a dialog where you can select the label algorithm that is used when recalculating labels.
  * Settings...
   * Opens the AutoAnnotate settings dialog.

== Managing Clusters in the AutoAnnotate Panel ==

On the main AutoAnnotate panel you will find the '''Cluster Table'''.

 * This table shows each cluster, along with its label, the number of nodes in the cluster and a checkbox icon that indicates if the cluster has been collapsed.
  * Click on a table header to sort the table by that column.

Most of the cluster options are available using the context menu of the cluster table.
 * Start by selecting one or more clusters in the cluster table. 
 * To select multiple clusters hold the Shift key to select a range or hold the Ctrl/Command key to select individual clusters.

{{attachment:aa_user_guide_7.png||width=250}}

 * Right click with he mouse to show the '''cluster table context menu'''.
  * Rename…
   * Enabled when 1 cluster is selected.
   * Manually set the label for the cluster.
  * Delete
   * Delete the cluster annotations
    * Note: This does not delete the nodes or edges in the cluster, just the annotations.
  * Merge
   * Enabled when 2 or more clusters are selected.
   * Merges the clusters into a single cluster.
   * A new label for the merged cluster is automatically calculated.
  * Extract Clusters…
   * Creates a new Annotation Set consisting of the selected clusters.
  * Collapse
   * Collapses the selected clusters
  * Expand
   * Expands the selected clusters
  * Recalculate Labels
   * Recalculates the labels for the selected clusters.

== Managing Clusters in the Network View ==

{{attachment:aa_user_guide_11.png||width=500}}

 * Manually create a cluster 
  * Select some nodes in the network view, right click to show the context menu, and select '''Apps > AutoAnnotate > Create Cluster'''.
   * A new cluster is created.
   * A label for the cluster is automatically calculated.
   * The cluster is selected in the cluster table.
 * Deleting a node in an existing cluster will remove the node from the cluster.
  * A new label is calculated.

== Collapsing and Expanding Clusters ==

Clusters can be collapsed or expanded from the '''Annotation Set Menu''' or the '''Cluster Table Context Menu'''.

{{attachment:aa_user_guide_9.png||width=400}}

 * Before collapsing clusters make sure that node aggregation is enabled. If not enabled then collapsed clusters may not have a label.
  * In the main menu select '''Edit > Preferences > Group Preferences'''.
  * In the '''Group Preferences''' dialog select the option for '''Enable Attribute Aggregation'''.

{{attachment:aa_user_guide_8.png||width=400}}

 * When a cluster is collapsed a group node is created that contains the cluster and it is collapsed. The annotation for the cluster is not shown when the cluster is collapsed.
 * When a cluster is expanded the group node is expanded and then deleted. The annotation is show again.
 * It is not recommend to manually collapse or expand clusters using the Groups menu as this may confuse AutoAnnotate.
 * When switching between Annotation Sets all collapsed clusters are automatically expanded.

== Working with WordCloud ==

Labels for clusters are generated by the WordCloud app.
 * You may change the label generation options from the WordCloud panel.
 * In the main menu select '''Apps > WordCloud > Show WordCloud'''.
 * In the WordCloud panel you can change the label options, for example using the '''Normalize''' slider.
 * Back in the AutoAnnotate panel select '''Recalculate Labels''' to regenerate labels using the updated WordCloud options.


== Saving and Restoring a Session with Annotation Sets ==

 * There are currently some limitations in Cytoscape with regards to saving and restoring annotations and groups in a session file.
 * For this reason when you save your session all the clusters must be expanded first. This is planned to be fixed in future versions of Cytoscape and AutoAnnotate.
 * When you restore a session it defaults back to (none) for each Network View. Simply select the annotation set again to redraw the annotations.


== Additional Options ==

AutoAnnotate has various warning dialogs that can be dismissed permanently by selecting '''"don’t show this again"'''. If you would like to see these warnings again they can be re-enabled. In the main menu select '''Edit > Preferences > Properties''', then select '''org.baderlab.autoannotate''' in the Properties Dialog.

{{attachment:aa_user_guide_10.png||width=300}}


== Filing Bug Reports and Requesting Enhancements ==

Thank you for using AutoAnnotate. Your feedback is important and helps us to improve the App for everyone. If you have any comments, requests for new features or enhancements, or bugs to report, please enter them on the AutoAnnotate github issue tracker. 
 * https://github.com/BaderLab/AutoAnnotateApp/issues