Background

The Legend Creator includes a variety of features, for example describing a color gradient used for node fill color. This is a commonly used style mapping, and one that is difficult to recreate accurately in downstream tools.

First, let's review how Styles are used in Cytoscape.

In addition to setting Default style options, one can also set Mappings to define style options based on data in the node or edge table.
Legend Creator can work with continuous and discrete mappings. Continuous mappings are created based on numerical values, where the range is determined by looking at the node table, such as expression level.
Passthrough mappings will not create a legend entry, and are not discussed in this tutorial.

Getting started

We need a network with some style mappings to demonstrate the features of the Legend Creator. Let's load the Yeast Perturbation network, provided by Cytoscape as a sample session file.

Open the Yeast Perturbation sample session from the Sample Sessions sessions in the Starter Panel when you first launch Cytoscape.
You can also access the Starter Panel via View → Show Starter Panel.

Legend Panel

Next, we will take a look at the Legend Creator interface.

Select the Legend Panel tab of the Control Panel.
The app will automatically scan the network to review the style mappings and nodes in the network to determine how to build each legend entry.
This scan can also be started manually using the Scan network button.

Note: Legends are generated as annotations, and as such, are not updated dynamically. You must manually remove and recreate the legend if you change your styles.

Legend Panel

The Title and Subtitle can be updated from the default values. It's not possible to control the font, size or alignment in the Legend Creator interface, but we will see how to edit those later.
Check the Lay out vertically option to position the legend along the right margin of the network.
Check the box Draw bounding box if you want to include a rectangle surrounding all the legend entries.
The Legend Panel shows the style mappings identified by the scan and these are checked by default. The name of the relevant node table column and the name of the mapped attribute are displayed. Uncheck any mappings you want to exclude from the legend.
Click Add Legend button on the bottom of the panel to add the selected mappings.

In this example, the Node Label Font Size and Node Size are both mapped to the node degree, or the number of neighbors a node has (Degree and degree.layout respectively) and the Node Fill Color is mapped to gal1Rexp.

First Draft

The network now includes the legend to the right of the network. The legend includes three components, one for each of the mappings we selected. The first two show both font label size and node size increasing with node degree, i.e., those with more neighbors. Third, a color gradient entry shows expression level of our protein of interest.

Depending on the purpose of the visualization you are creating, some mappings may not add much information to the legend and sometimes mappings are redundant. The easiest way to decide which entries are useful is to generate the full legend, look at the result and then make updates and recreate the legend.

First Draft: Node Degree

The first two mappings are similar in that they both map measures of the nodes’ degree to the size of both the nodes and its label, via a continuous mapping.

Note: Although size is a useful attribute to map, showing it in a legend is not always useful. Our perception of size is qualitative; we can tell big from small, but we can’t tell a 50 pixel diameter from 63 pixel diameter if they are not right next to each other and the same shape. Adding a legend to show the quantitative measure of size is not always necessary.

First Draft: Node Fill Color

The other mapping is a color gradient. It should match our continuous mapping for the variable gal1RGexp in the Style panel. This is clearly the most important entry in our legend. Perceptually, color attributes are the most powerful mapping and should be used for the strongest message you are trying to convey.

Note: Because color is such an important attribute perceptually, it is important to use color with care. Rather than defining arbitrary colors for minimum and maximum values, we recommended using pre-defined color palettes that have been designed to make sure they have consistent color saturation across the range. If you double-click on a gradient in the Style panel to bring up the editor, a button to choose palettes is available in the upper left.

Layout and Placement

The Legend can be layed out vertically or horizontally, and will always be placed outside the bounds of the network.
To move the legend, first click the Toggle Annotation Selection option in the Network View Tools under the network (red arrow). Unselect Toggle Edge Selection and Toggle Node Selection. You can then select the legend by shift-and-drag. Once selected, you can reposition the legend.

Annotation Panel

To edit more specific aspects of the legend, such as the font, size, or the color of the background, you will need to use the Annotation control panel. There, you’ll see every legend item in a list view. All legend items are placed in the background layer by default. There are several operations available to edit annotations:

Edit the font, size, color, rotation etc of individual legend items.
Delete individual legend items.
Move items between layer, or up/down within layers.
Reposition individual items of the legend.

You can also Next, we will make a round of updates to individual legend items to improve the look and readabillity.

Annotation Panel: Font Face and Size

In the legend in the Network View Window, right-click on the title, Legend, to select it and click on the Appearance tab in the Annotation panel.
In the Font drop-down, select Dialog. This is the font face used for node labels in the Yeast Perturbation sample network.
To do the same with the subtitles for the three mappings, we need to select each of them in the list of legend items in the Annotation panel, for example Node Label Font Size: Degree. Once selected, set the font to Dialog in the Appearance tab.
Next, update the font Size to 30.
Repeat with the other subtitles.

Annotation Panel: Ungrouping Items

After updating the font size of the subtitles, they are now too close to the legend graphics, so next we will learn how to change the placement of individual items in the legend.

By default, the individual legend items are grouped are grouped per mapping, and in order to move one of them independently they first need to be ungrouped. In the Annotation panel, select the folder representing one mapping, and click the Ungroup Selected Annotations button at the top of the panel.
Select one of the subtitles, for example Node Label Font Size: Degree in the list of ungrouped items in the Annotation panel.
Drag the selected item to reposition it. Repeat with the other subtitle.

Annotation Panel: Grouping Items

The legend is now more readable, but before we can consider it complete, we should recreate the items for each of the parts of the legend, to make it easier and more reliable to move the legend around.

In the Network View Window, select all items belonging to the first mapping by click-and-drag.
In the Annotation panel, click the Group Selected Annotations button at the top of the annotation panel.
Repeat with the remaining two mapping legends.

Summary

The Legend Creator creates legends for the most common attributes applied to nodes in your graph. Adding legends for edge attributes, such as line style, color and thickness, is not supported in the current version, but is a planned feature.