Diff for "Cytoscape_User_Manual/Filters"

QuickFind

Cytoscape now includes a new Quick Find feature, which enables you to quickly find nodes and edges.

attachment:quick_find2.png

Using Quick Find is very simple. Here is how it works:

• Import a network. For example, load up sampleData/galFiltered.sif.

• Start typing in the text box. For example, enter "yd". The search box will automatically display a list of all matching nodes.

attachment:quick_find3.png

• Select a matching node. Cytoscape will automatically zoom in on the selected node.

attachment:quick_find4.png

Configuring Quick Find

Quick Find works by creating an internal index of all nodes within the network. By default, Cytoscape indexes all nodes by the node identifier. However, you can configure Quick Find to index nodes or edges, and you can set any attribute as the index.

For example, if you load up a BioPAX file (such as sampleData/Apoptosis_BioPAX.xml), your network will be automatically annotated with numerous attributes. To index the network based on cellular location, click the Quick Find configuration button, and select "biopax.cellular_location" from the dropdown list.

attachment:quick_find5.png

You can then quickly find all proteins located in the "plasma membrane" by just typing "p".

attachment:quick_find6.png

Tip: If you don't know what to search for, just leave the search box empty, and click on the down arrow directly next to the search box. Cytoscape will provide you with an initial list of matches. In the case below, we will get a list of all distinct cellular locations in the network.

attachment:quick_find7.png

Dynamic Filtering via Quick Find

If you choose to index on a numerical attribute, the Quick Find search box changes to a dynamic slider for quick filtering.

For example:

1. Import a network such as sampleData/galFiltered.sif using File → Import → Network (multiple file types).

2. Import an expression data file such as sampleData/galExpData.pvals using File → Import → Attribute/Expression Matrix... .

3. Configure Quick Find to index the network using the gal1RGExp attribute.
   • attachment:quick_find8.png
4. Use the slider widget to automatically filter the entire network.

attachment:quick_find9.png

Filters

Filters allow you to quickly select multiple nodes or edges of interest by comparing node and edge attributes loaded onto Cytoscape networks to properties you specify. For example, you can select all the nodes whose name contains a specific pattern, or whose attribute has value within certain range, if it is a numeric attribute. Cytoscape provides filters as a core plugin. Users can do complex selection by defining basic filters (based on single attribute) and compound filters (based on multiple attributes) -- Boolean operations of basic filters. Based on the feedback from Cytoscape users, the Cytoscape team determined it is necessary to redesign the user interfaces for the filters. The newly designed filters will preserve all the functionalities of the old filters, but with much user-friendly interfaces. However, by the time of the release of Cytoscape 2.5, the new filters were not implemented completely. Therefore, in this version, both the old filters and new filters will be there. But, in the future, the old filters will be replaced completely by the new filters.

Using Old Filters

Several types of filters are available. Basic filters allow the selection of multiple nodes or edges according to attribute data:

• String filters allow selection of nodes or edges with attributes matching specified text patterns. These patterns may include the wildcards * and ?.

• Numerical filters allow selection of nodes or edges according to numerical attributes and the mathematical operators >, =, and <.

Compound filters allow selection based on the application of pre-existing filters:

• Topology filters allow selection of nodes with neighbors that match some pre-existing filter.
• Boolean filters allow the combination of multiple filters using the AND, OR and XOR operators.

Example filters are shipped with the plugin to get started.

To use the old filters, click "Select" on the menu, on the pulldown, select "use old filters", you will see a filters window which initially looks like the following:

attachment:init_filter_dialog.png

If the first filter is selected, then the window looks as shown:

attachment:first_filter_dialog.png

There are three panels in the Filters window:

• The right-hand panel: An existing or newly created filter can be edited in this area. Each filter type has its own user interface for editing.
• The lower left panel: All available filters are shown in this list. Initially, this list will contain only sample filters, but as you create more, they will be added here.
• The upper left panel: Pressing the Create new filter button adds a filter to the “Available Filters” box, and the Remove selected filter button deletes the currently selected filter.

Creating Filters

Clicking the Create new filter button allows you to select a type of filter to create, as shown below.

attachment:create_new_filter_dialog.png

The important thing to realize when creating a filter is that the filter does not do anything by itself. Once created, the filter must be applied to the network.

String Filter

attachment:string_filter.png

The String Filter allows you to filter nodes or edges by a given text attribute of your current loaded network. Search terms are entered in the text box at the bottom. For example, to match any Node whose canonicalName starts with “YDL”, you would select “Node”, “canonicalName” and then type in “YDL*”. The * is important, as it matches any number of characters after YDL. If you want to be more specific and only select nodes whose canonicalName starts with YDL00 followed by any other two characters, you would type “YDL00??”. The “?” denotes any single character, while the “*” represents zero or more characters. Full regular expression searching is supported, although is not covered here. Once the filter is defined, it will be assigned a default descriptive name.

Numerical Filter

attachment:numerical_filter.png

The Numerical Filter also allows you to filter nodes or edges, and presents you with a list of available attributes. This filter matches all values in the network of your selected attribute that are greater than, less than, or equal to a number you type in the search box.

Node Topology Filter

attachment:node_topology_filter.png

The node topology filter allows you to select all nodes selected by a preexisting filter and having n neighbours found at a distance of m or fewer edges away. For instance, to select all the nodes adjacent to a node with the canonical name matching ‘YD*’, you would “select nodes with 1 neighbors”, “within distance 1”, “that pass the filter Node: canonicalName ~ YD*”.

The node topology filter depends on the existence of other filters. By default, [No Filter] is selected; it doesn't filter out anything, but rather selects all nodes.

Boolean Filter

attachment:boolean_filter.png

The Boolean Meta-Filter allows you to define a new filter that is a logical combination of existing filters. Available filters are displayed. By selecting one or more filters, you can then choose whether Nodes or Edges pass “ALL” (AND), “AT LEAST ONE” (OR), or “ONLY ONE” (XOR) of the selected filters. Once created, Boolean filters can then themselves be combined using the Boolean filter to create arbitrarily complex logical combinations of filters. Note that unlike the String and Numerical Filters, Boolean filters will need to be assigned a name manually.

Saving Filters

Filters are currently saved automatically in the filters.props file found in the .cytoscapedirectory, found in each user's home directory. Once created, filters are saved for future sessions, as long as you exit Cytoscape normally via File → Quit (i.e. not via ctrl-c on Linux).

Running filters

Any available filter can be run by pressing the ‘Apply selected filter’ button. When a filter is applied to your network and multiple nodes or edges are selected, all of the normal selection-related operations may be performed, such as Delete Selected Node/Edges, Copy To New Network, and Invert Selection.

Using New Filters

By default, you should see a filter icon on the toolbar: attachment:filter_icon.png If you click on it, the filter panel on the management panel will be selected. The filters panel can also be selected by click on the filters tab of the management panel, or by the menu Select --> Use Filters.

After the filters panel is selected, the filters panel initially looks like the following,

attachment:filterInit.png

Click the option button attachment:OptionButton.png on the right of the filter selection comboBox, a popup menu will show up.

attachment:FilterPopupMenu.PNG

1. Create a filter To create a filter, click the option button, select “Create new filter…”. Give a name to the filter by fill the new filter dialog

attachment:NewFilterDialog.PNG

2. Define the filter After a new filter is created, the filter definition is empty initially. Users may define the filter by choosing attribute (one at a time) in the attribute combobox and click the add button at the right side. Note that each attribute has a prefix, either “node.”, or “edge.”, which denote the kind of attribute. Depends on the data type of the selected attribute, different UI widgets will be added to the filter definition panel. If the data type of the selected attribute is String, a text-Indexed-comboBox will be added. If the data type of the selected attribute is Number (double, float, or integer), a Numeric-indexed-RangeSlider will be added to the filter definition panel. The following figure shows two UI widgets were added to the filter definition panel, one is a String type and the other is a Number type. FilterDefinition.PNG For each UI widget, there is a label at the left side to show the name of the attribute the widget represents, and there is a trash-can icon at the right of the widget. A click on the trash-can icon will delete the widget. In this way, user can modify the filter definition after it is defined.

3. Apply the filter

Now a filter is defined, users may choose appropriate values (string patterns in the comboBox, value ranges in the rangerSlider) and click the apply button to do the selection. Each UI widget has associated index with it, text index for comboBox, numeric index for rangerslider. Their usage is exactly the same as in the QuickFInd. Note that the filter apply the “AND” relationship of the widgets. In the previous figure as an example, select all the nodes/edges whose attribute “XXX” has the pattern “XXX”, and whose attribute “YYY” has the values in the range ZZZ~ZZZ. “AND” relationship between widgets is the only one implemented so far. Other Boolean operations, such as OR, XOR, NOT, are not implemented yet in the Cytoscape 2.5.

The advanced options

By default, the advanced panel in the filter definition panel is collapsed, user may open it by click on the plus sign. See figure below.

attachment:FilterAdvancedPanel.png

There are three rows in the advanced panel,

1. The first row, labeled Save. The two checkboxes, global and session will determine where the filter is saved. By default, filters are saved in session. By check the global checkbox, the filter will be saved in the global property. Note also that the prefix of the filter name in the filter selection comboBox will reflect where it is saved.

2. The second row “Select” will determine what will be selected on the network, node, edge or both. If node is checked, edge is unchecked, then the attributes listed in the attribute comboBox will be only those with prefix “node.”.

3. The last row “Interaction” will determine either “Source” or “Target” nodes will be selected, since a network graph is a direct graph, there is distinction between source node and target node.

Other menu items in the popupMenu.

In the popup menu, other than “Create a new filter…”, there are “Delete filter”, “Rename filter …”, “Copy existing filter”.

Click “Delete filter” will delete the selected filter.

Click “Rename filter” will give user the option to change the name for the selected filter.

Click “Copy existing filter” will duplicate the selected filter.

Select Menu

The Select → Nodes and Select → Edges menus provide several mechanisms for selecting nodes and edges. Most options are fairly straightforward; however, some need extra explanation.

Select → Nodes → By Name... selects nodes by the node identifier (ID). This is the value seen in the left-most column of the attribute browser. This does not change, even if the displayed node label changes!

Select → Nodes → From File... selects nodes based on node identifiers found in a specified file. The file format is simply one node id per line:

Node1
Node2
Node3
...