Tutorial:Cerebral Plugin

From OpenTutorials
Jump to: navigation, search

Slideshow Cerebral_Plugin (about ?? minutes)
Handout Cerebral_Plugin.pdf (?? pages)

Tutorial Sources
Tutorial Curators Anna Kuchinsky

Cerebral Cytoscape Plugin

In this set of tutorials, you will install the Cerebral Cytoscape plugin, learn how to create and interact with a Cerebral layout, and learn how to use the features of Cerebral v.2's multi-experiment comparison tool. A sample dataset will be used throughout - this is a small representation of the TLR4 signaling pathway, an important immune pathway involved in the response to Gram-negative bacteria. The dataset is derived from a 2006 paper from our group, "Modulation of the TLR-mediated inflammatory response by the endogenous human host defense peptide LL-37," reporting the results of a two treatment/four timepoint microarray experiment. This file contains a subset of the data - two treatments (LPS alone, LPS+LL-37) at one timepoint (4h). The fold changes provided in the sample file are real, however the p-values have all been set to 0.01.

Creating a Cerebral view

First, you must install Cytoscape and the Cerebral plugin.

Installing the Cerebral plugin

  1. Download both the latest version of File:Cerebral.jar and File:Prefuse.jar.
  2. Save the two files in Cytoscape's plugin directory.
  3. Launch Cytoscape and ensure that the plugins are loaded. If successful, you will see the Cerebral tab in Cytoscape's control panel. In the Plugins menu, you will see Create Cerebral view, Restore previous Cerebral views and Export Cerebral view. These may take a few seconds to appear after Cytoscape opens.

Cerebral Tab in Control Panel

Loading the sample data

  1. Download the XGMML file containing all necessary data for the TLR4 network and experiment: File:Tlr4 tutorial.xgmml
    1. A word about the information you need to run Cerebral: In order to generate a localization-based layout, Cerebral requires you to provide localization annotation for as many of the nodes in your network as possible. There are many sources for such data, however once you have collected the information, it must be stored in a format that Cytoscape is able to read. This can be as a node attribute or spreadsheet file. The text values for the localization attribute can be whatever the user desires - Cerebral will read in any text - but please note that the values are case-sensitive, so "cytoplasm" and "Cytoplasm" will be treated as two separate localization sites by the algorithm.
  2. Load the data by selected File->Import->Network (multiple file types) from the Cytoscape menu, or using the Ctrl+L keyboard shortcut. The network will appear in the main Cytoscape panel. Node labels may be missing. To turn them on, select ID as the target of the passthrough mapper in Cytoscape's VizMapper then click in the network to make them appear.
  3. To see the attribute data contained in the TLR4 sample file, click the Select Attributes icon in Cytoscape's Data Panel and place checkmarks next to the Localization, Function, and LPS/LPS+LL=37 attributes. Selecting a node or nodes will make their attribute values visible in the Data Panel.

Performing the layout

  1. From the Plugins menu, select Create Cerebral view.
  2. Select the attribute containing the localization information from the first dropdown menu. In our tutorial, this is the Localization attribute.
  3. The attribute values in the loaded file will be used to populate the layer placement table. Cerebral divides in the Cytoscape window into horizontal stripes, one for each localization site read in from the attribute file. By highlighting a row and using the arrow buttons to move the row up or down, you can control the order that these stripes will be arranged in. We recommend ordering that provides a cross-section style view of the cell: extracellular nodes at the top, followed by plasma membrane, cytoplasmic, and nuclear nodes.
  4. At this point, you could generate your network diagram by clicking the Create layout button. If, however, you would like to customize the graph further, proceed to the next step.
  5. Cerebral is capable of placing the target nodes of a particular interaction type(s) at the very bottom of the graph, beneath the lowest localization layer. This is useful for separating the genes that are regulated by a pathway from the actual pathway itself. To place a certain subset of nodes in this bottommost region, go to the Plugins menu and select Create Cerebral view.
  6. In the Downstream nodes part of the Cerebral dialog box, select the type or types of interaction whose target nodes (in a simple interaction formal file, the target node is the second node, or column, in a given interaction) should be placed in the bottommost graph layer using the checkboxes. If you are using our sample TLR4 data, choose interaction from the dropdown menu of attributes. Check the box for Transregulation- in our file, this is the term we are using to refer to interactions where a transcription factor regulates the expression of a particular gene.
  7. Provide a label for this region of the graph. For our sample data, you may wish to use Downstream Genes or something to that effect.
  8. The target nodes specified in step 6 can be grouped according to any attribute loaded. Select the attribute containing the characteristic of interest from the dropdown menu. In our tutorial we have included functional information for each node in the Function attribute. Select this attribute from the dropdown menu.
  9. Click the Create layout button.

Cerebral view of your network

Cerebral will take a few moments (3-5 seconds for a hundred-node network, 1-2 minutes for a network with ~1000 nodes) to generate the layout. When complete, you will see a network like the one shown in the figure above. Note that Cerebral is a non-deterministic layout algorithm and will generate a slightly different layout each time, thus your network may not appear exactly the same as the one shown above.

Interaction with a Cerebral view

As a Cytoscape plugin, Cerebral provides access to most native Cytoscape functions. Because we use a different rendering engine, however, there are some slight differences, as well as extra functions. The following sections describe some of the unique aspects of Cerebral that you should be aware of in order to get the most out of the program.

Modifying your network

The Cerebral and VizMapper tabs in the Cytoscape Control Panel can be used to alter the visual appearance of your network. In the Cerebral tab, the Edge curviness slider can be used to adjust the degree of edge bundling - try moving the slider and note how the curved edges emanating from high-degree nodes change. The Label density slider affects how many node labels are drawn - Cerebral uses a "smart labeling" strategy to ensure that node labels for the most important nodes are visible when the slider is set to the more dense end of the spectrum - labels for a node that is being moused-over are drawn first, followed by its neighbors, then any user-selected nodes, and then we go down the list of nodes in descending order of degree. The Group label size slider controls the size of the labels for whatever clusters may have been created in the bottom-most layer of the graph (in the tutorial example, these are the functional category labels in the "downstream gene" layer). Unchecking the Show function clusters button and then clicking anywhere in the network view will turn off of the background colouring of any downstream clusters you may have created, while the color swatch, set to green by default, can be clicked on and used to change the color of the background groups. NB: Because of the difficult rendering engine Cerebral uses, you must click in the network for any changes to the cluster background to appear. The Show layer separators button controls whether the lines between layers are displayed or not, while the High quality rendering button controls how smooth the network appears - check this box to turn it on. We recommend only leaving it off if you are regularly altering a large network - for small networks such as the tutorial example, it is not very computationally intensive to have high-quality rendering on.

The VizMapper tab allows you to perform all sorts of actions to alter the visual properties of the nodes, edges, and global defaults in a way that is meaningful to you. For more information on how to use this tab (note that in Cytoscape v.2.4 and earlier, the VizMapper was only accessible through the VizMapper icon and not a tab), please see the VizMapper tutorial. NB: Because of the different rendering engine Cerebral uses, any time you make a change in the VizMapper tab, it will not become visible in the main view until you click anywhere in the main view.

Pinning nodes, re-doing layouts, and grouping nodes

After generating a layout in Cerebral, you may wish to refine the layout further. Pinning and grouping nodes can help with this. Pinning allows you to "tack" as many nodes as you wish in place, and then re-do a layout, keeping those nodes in place. This can be useful if you have several key nodes that you wish to have centralized in the graph. Try dragging a series of nodes to the center of the screen and then right-click on each of these nodes, and select Pin node to tack each one down. Then hit the Relayout button on the Cerebral tab of the Control Panel to generate a new layout, with your selected nodes pinned in place. Pinning can be also done to a group of selected nodes all at once. Nodes remain pinned until you select them, right-click, and choose Unpin node.

Grouping allows you to define a series of nodes as a group and then alter the visual style of that group only. To create a group, select one or more nodes, right-click on them, and choose Add selected nodes to a new group. In the Groups window at the bottom of the Cerebral tab in the Control Panel, a line will appear for you new group - click in here and type a name for the group. You can click the Add group button in this window to create a new group before you add nodes to it - create the group, give it a name, and now when you right-click on a selected node in the network, it will give you the option of adding it to any of the groups you have created.

Any groups you have created will appear in a new attribute called "Cerebral groups," which can be brought up in the Data Panel by going to the "Select Attributes" icon and putting a checkmark in the box next to "Cerebral groups". As this is a new attribute, you can use the VizMapper to assign visual properties to it, for example you could have the nodes in a particular group be larger than other nodes, or outline in a different color.

Exporting your Cerebral network

Because Cerebral is built on the prefuse rendering engine, the native Cytoscape image export tolls do not work. To export a Cerebral view, go to the Plugins menu and select Export Cerebral view. This will bring up a dialog box allowing you to specify the file name, file type (.png is the default; the other options are .ppm, .gif, .raw, .bmp and .jpg), and the size of the file - you can magnify the view up to 10x, allowing you to print a poster-sized view of a large network.

Saving a restoring Cerebral views

If you want to save a Cerebral view and return to it later, we recommend saving a Cytoscape session file. From the File menu, choose Save As... and name your session. You can then close Cytoscape. When you re-open Cytoscape, open your session by choosing File->Open and selecting your file. Your Cerebral session will appear exactly as you left it.

NB: If you want to change your layout from Cerebral to one of Cytoscape's default layouts, you cannot create a new layout directly. Instead, you must destroy your Cerebral view by right-clicking your network name in the Network tab of the Control Panel and choosing Destroy view. Right-click again and choose Create view to generate the default grid layout, and then you can use any layouts under the Layout menu (though you will have lost any visual attributes you have set - you will have to re-select the style in the VizMapper to bring them back).

Using the multi-experiment viewer tools

Cerebral v.2 introduces a powerful new analysis environment for the exploration of quantitative data, such as that derived from microarray experiments, across multiple experimental conditions. Users can upload data for several treatments, timepoints or a combination thereof, and then use Cerebral to visualize that data in a network context, compare and contrast different experiments, and cluster data. In this tutorial, you will learn how to use these new features using expression data contained in the tlr4_tutorial.xgmml file. If you haven't already loaded this file and created a Cerebral view, do so now.

Loading the quantitative data

  1. In the data panel, use the Select Attributes icon to bring up the list of attributes contained in tlr4_tutorial.xgmml. Check the boxes next to the four LPS and LPSLL37 attributes to make them appear in the Data Panel. These are the fold changes and p-values for two experimental treatments at 4 hours.
  2. Select the Parallel Coordinates tab from the tab menu at the bottom of the Data Panel.
  3. Click the Select expression attributes icon (leftmost icon in the right-hand portion of the Parallel Coordinates panel). A popup window listing all loaded attributes will appear. Choose which of the expression attributes you wish to load by control-clicking as many as desired. For this example, select LPS04h and LPSLL3704h. NB: Only select the expression (fold-change) attributes - do NOT select the p-value attributes.

Complete TLR4 network with attributes

You will now have a view that should look something like the figure above. The main network view still shows the complete TLR4 network with the original coloring. Two smaller views, one for each of the expression conditions we loaded, now appear to the left of these views. These are called the small multiple views and show the expression-based coloring for each condition. In the Parallel Coordinates tab, a graph has appeared with our two conditions represented as vertical axes and lines drawn to show the expression profile across the conditions. At the right-hand side, several small thumbnails appear, each showing a different expression profile of a number - these are the clusters of similarly-profiled genes Cerebral has generated from the loaded expression data. In the next sections, we will explore each of these views and functions in turn.

Expression-colored mini-views of the data

  1. Click on a mini-view (either its name or within the mini-network) to promote its coloring to the main network view. (NB: to return to the original coloring, click again in the mini-view.)
  2. Try panning, zooming, and selected nodes in either the main view or a mini-view - you will notice the views are all linked, so zooming in on the main view has the same effect in the mini-views.
  3. You can resize the mini-views by both dragging the divider between the mini-views and main view, and by using the slider at the bottom of the mini-view pane, which controls how many columns are used to display the mini-views (this is useful when you have 4+ conditions loaded and want to see all their mini-views at once).
  4. You can re-order the mini-views by clicking a mini-view's title and dragging it to the desired position. You will also note this changes the order of the vertical axes in the Parallel Coordinates view, and of the clusters in the cluster viewer. You can also re-order mini-views by clicking a vertical axis in the Parallel Coordinates view and dragging it to the desired position.
  5. You can control which nodes are colored according to the degree of their fold-change and the associated p-value by using the two sliders in the Cerebral tab of the Control Panel. The Significance cut-off slider specifies a p-value threshold, above which a node will not be colored. At the default value of 0.05, all nodes with a fold-change meeting our default expression cut-off of +/-1.5 are colored. Note that with this sample data, if we move the slider to 0.001, or type that value into the box, no nodes will be colored as none have a p-value that low. The Expression cut-off slider and text box work in the same way - you can set the fold-change above or below which nodes will be colored in. NB: Ratio vs. non-ratio data. In ratio data, an increase of 20% is written as 1.20 whereas in non-ratio data, it would be written as 0.2. Cerebral scans each condition and looks for data in the -1.0 to +1.0 range - if there are no expression data points in this range, ratio data is assumed and this box is checked by default. If data is found in that range, non-ratio data is assumed and the box is unchecked. Either behavior can be overridden by the user.
  6. You can also change the coloring used for the mini-view expression scale using the Expression color scale editor. Click on the colored bar to bring up the editor. Let us try a few different coloring schemes to get some experience with the color editor - remember to click the Apply button after each change to have it take effect in the network views:
    1. Change to a yellow:blue scheme by clicking the yellow/blue bar (second from the top in the gallery)
    2. Specify your own solid 2-color scheme by first clicking the yellow-16 to 0 segment at the top of the editor, then clicking the yellow swatch that appears near the minimum/maximum specification. Select your desired color from the palette and click OK to apply the changes. Do the same thing, changing the blue segment to whatever color you please.
    3. Go back to the green/red solid scheme (first line in the gallery). Click the green-black gradient button (to the left of the green/red bar, bottom icon). This adds a green gradient to the end of the color bar, which is initially set to the -32 to -16 range. Our expression values range between ~-5 and +12, so let's set the green gradient to cover the range from -12 to 0 by typing these values in the Minimum/Maximum boxes. Now, click the red gradient and perform the same set of actions, setting a gradient to range from 0 to 12. Look at the mini-view coloring. You may have noticed that most of the nodes are colored faintly, with only one bright red node. This is the result of having an outlier in the expression values - one node whose fold-change is much, much higher or lower than other nodes. The next coloring scheme will show you how to work around these outliers.
    4. Open the color editor again and select the scheme with a small dark green section, a small light green section, a large yellow section, and small orangeish and red sections. Set the minimum value for the dark green bar to -5 and the maximum value for the dark red bar to 12. This provides a much more informative coloring, where the presence of a single outlier does not affect the degree of coloring of other interesting nodes.

Profile view of the data

  1. In the Parallel Coordinates tab of the Data Panel, two vertical axes appear, one for each experimental condition. Click on the vertical axis and drag it to re-order the conditions. Click the icon with three vertical lines to space the aces evenly.
  2. You can pan and zoom in the Parallel Coordinates window just as you do in the main Cytoscape windows - right-clicking and moving the mouse up or down zooms in and out, which middle-clicking and dragging pans. The magnifying glass icons can be used to zoom into a selected region or zoom out.
  3. Click your mouse near one of the vertical axes and, while holding down the mouse button, drag the mouse to create a rectangle on the vertical axis. A purple bar will appear, as will fold-change values. You can use this tool to select a fold-change range (try selecting from ~12 down to about 1 on the LPS04h condition). If you then click the funnel icon underneath the cluster diagrams, all the lines (nodes) that pass through the selected range will be filtered out (displayed as light grey lines in the Parallel Coordinates tab and their nodes will appear transparent in the main and mini-views). To un-filter the lines, click the icon of the funnel with the X.

Comparison view of the data

  1. The main view can be colored to show the difference in expression values between two selected conditions. Click the comparison button for the LPS04h condition (the button with the small window icons to the right of the mini-view title), then click the comparison button for the LPSLL3704h conditions (you can also shift-click the two conditions of interest to compare them). This tells Cerebral to color the main view according to the change from the first selected condition to the second condition, and the main view's title will reflect this.
  2. The difference coloring is a direct subtraction - the fold-change in condition 2 minus the fold-change in condition 1. A node's color is determined by the magnitude of this difference. Clicking on the Comparison color scale bar brings up the color editor and allows you to change the default coloring scheme.

Clustering the data

  1. At the right-hand side of the Parallel Coordinates tab, several small thumbnails are visible. These are clustered gene expression profiles - genes whose expression shows similar behavior across different conditions. The clusters are calculated using the k-means clustering algorithm, with a default k of 10 (meaning 10 clusters will be created). An average expression profile representative of each cluster is shown in each thumbnail, along with the number of genes in the network that belong to the cluster.
  2. Drag the slider to the left or right to change the k-value and, therefore, the number of clusters created. Smaller k-values mean fewer clusters and more variable profiles within a cluster. The best number of clusters for a given set can be difficult to determine, but we recommend trying values in the 10-20 range and evaluating the results by looking at the thumbnails.
  3. Clicking on a cluster of interest filters out all other nodes - just the cluster members will be colored in the main and mini-views, and only the members' lines will appear in black in the Parallel Coordinates viewer. Shift-clicking allows you to select multiple clusters simultaneously, while clicking anywhere in the network views or profile views will de-select clusters.