Systems Biology and Evolution Toolbox ( SBEToolbox )

Contents

SBEToolbox is an open-source Matlab toolbox for network analysis. It takes a network file as input, calculates a variety of centralities, topological metrics, clusters nodes into modules etc... Analyses can be performed either in Matlab workspace or by using the SBEToolbox's UI. SBEGUI of SBEToolbox is a menu-driven UI which acts as gateway to most of the functions in SBEToolbox. The software is easily extensible through built in plugin management tools. Users can create custom plugins and shape the software to their specific needs and publish / distribute the plugins for other users.

This document shows how to install and start using SBEToolbox.

Minimum Requirements

  1. MATLAB: SBEToolbox has been developed in MATLAB R2012a and MATLAB 2012b and makes use of all the improvements made to core MATLAB. Although, the Matlab code works in previous versions as well, some new features may be incompatible.
  2. Disk Space: ~ 200 MB of disk space.
  3. Memory: We recommend a minimum of 4GB RAM for fast computations, although it is not mandatory.
  4. Mac: Intel 64 bit, OS X 10.6 Snow Leopard or newer.
  5. Windows: Intel 32 bit / 64 bit Windows XP or newer.

Installing SBEToolbox

  1. Our latest software can be downloaded from https://github.com/biocoder/SBEToolbox/releases.
  2. Once you have download the software, extract and move the SBEToolbox directory to the path of your choice, then open Matlab.
  3. Go to SBEToolbox directory and run install.
  4. It will add all the paths necessary and will open pathtool window so that you can Save the paths.
  5. Now, click on Save and click on Close to close the pathtool window.

Starting SBEToolbox

  1. To start the UI of SBEToolbox, just type SBEGUI at the prompt.
  2. SBEToolbox 's UI Window can be broadly classified into 4 areas (as show below):
    • UI Menu Area: All the functions are accessed from this Menu area.
    • Function Output Area: When a menu option is selected for execution after a network is loaded, the output is shown in this area.
    • Current Network Information Pane: This area just below the Function Output Area shows a brief information about the current loaded network such as number of nodes, number of edges and updates if the current network is edited
    • Plugin Area: Plugins submitted by various users can be installed using the menu options under Plugins menu and will be listed in this area. A brief plugin description and author information is displayed when a plugin a selected from the drop down menu.
    • SBEToolbox Status Pane: A status message "Ready" or "Busy" is displayed indicating that SBEToolbox is performing computations and whether or not it is ready for further analysis.

Reading / Writing Data

  1. Network information can be loaded by clicking on the Network menu and using one of the load functions appropriate for the respective file formats.
  2. Supported file formats are .sif, .pajek, .tab (network information stored in tab-delimited format) and Matlab .mat format.
  3. When you download SBEToolbox, there is an example_dataset folder which have some interaction networks.
  4. The following screenshot shows how to load a network from .sif file:
  5. Once the network is loaded, the Current Network Information Pane is updated and it does not update until there is further change in the node / edge number while editing the network etc...
  6. The Current Network Information Pane is color coded for messages, Green for success, Orange for warnings and Red for any errors.
  7. After the network is loaded, user can execute network measures present under the Statistics menu and so on.
  8. SBEToolbox is capable of handling large networks (> 10, 000 nodes), but some of the statistics functions take longer to finish computation.

Extending SBEToolbox through Plugins

  1. Any network loaded into SBEToolbox is stored on the disk for that session.
  2. In this way network information is easily retrievable for current session and can be used to write additional functions.
  3. These functions can be incorporated into the UI of SBEToolbox as Plugins.
  4. We have developed some tools which make it easy and simple to manage and distribute Plugins.
  5. These tools can be used either through the menu options under Plugins menu or through command line in Matlab workspace.

Writing Plugins for SBEToolbox

  1. All the plugins are stored in Plugins directory under SBEToolbox. The hierarchy of SBEToolbox folder and Plugins folder is as follows:
    SBEToolbox
             |_ addins
             |_ annotation
             |_ plugins
                      |_ pluginList.info
                      |_ test_plugin
                                   |_ test_plugin.info
                                   |_ test_plugin.m
                      |_ demo_plugin
                                   |_ demo_plugin.info
                                   |_ demo_plugin.m
                      |_ .
                      |_ .
                      |_ .
             |_ lib
                  |_ gaimc
                  |_ bgl
             |_ session
             |_ help
    
  2. The displayable plugin name is stored in a file called pluginList.info in the plugins directory.
  3. This file contains the information of available plugins and is displayed in the drop-down menu in the Plugin Area of SBEToolbox's UI.
  4. For example, contents of the pluginList.info file may look like:
    test plugin
    Participation Coefficient MCL
    Knotty Centrality
    
  5. A new plugin can be created either by using the function called create_plugin or by selecting New From Template... option under Plugins Menu.
  6. Plugin name can contain any alphanumeric characters and 3 special characters: '-' (hyphen), ' ' (space), '_' (underscore).
  7. All the special characters are converted to underscore so as to create a plugin directory.
  8. The recommended way to start developing a plugin is to create a plugin from the template we provide.
  9. Please do not delete the template plugin folder called test_plugin under the Plugins directory as we use this structure to create new plugins from template.

Creating new Plugin on command line

  1. In the following example, we will use the create_plugin function and create a new plugin named demo plugin
  2. Observe how we have a space in the plugin name, but a folder called demo_plugin with complete structure as in the template test_plugin will be created under the Plugins directory and the pluginList.info will be updated.
    create_plugin({'demo plugin', 'This plugin will display first 10 node names of the loaded Network', ...
                          'Kranti Konganti ( konganti@tamu.edu )||Texas A&M University'})
    
  3. Adding a '|' ( pipe ) symbol between the text will be parsed as new lines and will displayed in the text fields of Plugin Area
  4. Now a new folder called demo_plugin is created under the Plugins directory and is immediately available in the SBEToolbox's UI after Refresh Plugin List button is clicked.
  5. My new pluginList.info file has been updated
    test plugin
    Participation Coefficient MCL
    Knotty Centrality
    
    demo plugin
    
  6. Before creating a new plugin:
  7. After creating a new plugin:
  8. The plugin directory demo_plugin contains 2 files, demo_plugin.info and the actual function file demo_plugin.m
  9. demo_plugin.info contains brief description of the plugin and author information entered during the plugin creation step.

Creating a Plugin through SBEToolbox UI

  1. Using a UI menu option to create a plugin from template is as easy as just a single click and entering Plugin information.
  2. In the following example, we will create a plugin named demo plugin 2 from template through UI.
  3. The information can be entered into the presented input dialog box which is resizable.
  4. After, clicking on Ok button, a new plugin named demo plugin 2 is created.
  5. For it to display in the drop down menu, we need to Refresh the plugin list.
  6. Now, to edit the code in the Matlab editor, click on the Edit Plugin Using Matlab Editor... option under Plugins menu.
  7. This will present the code in the Matlab editor for editing.
  8. All the functions in SBEToolbox uses data stored in 2 variables, sbeG and sbeNode.
  9. sbeG contains current network information as a sparse adjacent matrix and sbeNode is a cell string vector of node names.
  10. The current network information can be retrieved as:
    [graph, edges] = getcurrentnetsession;
    
  11. Once you have the network information, the plugin function can be written.
  12. The following code (of demo plugin 2 plugin) will read the current network information and display's first 15 node names in the Function Output Area of SBEToolbox.
  13. outputCell variable stores the output.
     1%% Test and load either largest extracted network or original network or the edited network
     2[~, e] = getcurrentnetsession;
     3
     4%% Define size of output
     5outputCell = cell(16,1);
     6
     7if isempty(e)
     8     outputCell{1} = sprintf('\n%s\n', 'Network not yet loaded !');
     9end
    10
    11% Output header
    12outputHeaderTitle = 'demo plugin 2 Output';
    13outputCell{1} = sprintf('\n%s\n', outputHeaderTitle);
    14
    15% Rest of the function output
    16for n = 2:16
    17     nodeIndOffset = n - 1;
    18     outputCell{n} = char(e{nodeIndOffset});
    19end
    

Packaging and distributing Plugins

  1. Once a user has finished developing a plugin, he can package it using the plugin_manage command or by clicking on Package Plugin... option under Plugins Menu.
  2. A new plugin archive file ( .tar.gz ) is created inside the plugins folder.
  3. You can distribute this plugin by hosting it on your own server.

Using SBEToolbox on command line

  1. SBEToolbox is flexible and all the functions that work in the UI work on the command line.
  2. Ex: To see what functions are incorporated into the main UI, do:
    help Contents
    
  3. Ex: To list the locally installed plugins, do:
    plugin_manage('list-local')
    

Exporting network information to Matlab Workspace

  1. To start working with the network on the command line, select Assign Global Variables to Workspace... option under the Network menu.
  2. It will save the adjacency matrix and node information in 2 variables sbeG and sbeNode.
  3. You can now start working with the network will all the functions listed under Contents.m.
  4. Ex: Annotating the Nodes:
    • SBEToolbox uses GO annotations and will attempt to retrieve the information for a node.
    • First, the annotations can be downloaded from http://www.geneontology.org/gene-associations/
    • Downloaded annotations must be stored inside SBEToolbox/annotation/ftpget.
    • These annotations must be formatted for use with SBEToolbox. Just execute save_GO_annotation function.
    • Once the annotations have been formatted, select a annotation database to search against:
      annotate_nodes
      
    • Then, get the full annotation of a node. Let's annotate 5th node in the variable sbeNode.
      sbeNode
      annotation = annotate_node(5, 'full');
      
    • To access individual annotation elements, do:
      Ex:
      
      >>annotation.DB
      
      ans = 
      
          'TAIR'
      
      >> annotation.DBObjectSynonym
      
      ans = 
      
          'AT1G01560|ATMPK11|MAP kinase 11|AT1G01560.1|F22L4.10|F22L4_10'
      

open_matlab.png (127.3 kB) Kranti Konganti, 02/22/2013 03:43 pm

install_sbetoolbox.png (271.1 kB) Kranti Konganti, 02/22/2013 03:43 pm

starting_sbetoolbox.png (212.3 kB) Kranti Konganti, 02/22/2013 03:51 pm

SBEToolbox.png (106.8 kB) Kranti Konganti, 02/22/2013 04:21 pm

sif_file_opened.png (73.5 kB) Kranti Konganti, 02/22/2013 08:29 pm

open_sif_file.png (198.3 kB) Kranti Konganti, 02/22/2013 08:29 pm

after_new_plugin.png (42.3 kB) Kranti Konganti, 02/27/2013 10:13 am

before_new_plugin.png (41.7 kB) Kranti Konganti, 02/27/2013 10:13 am

plugin_from_template_ui.png (115.2 kB) Kranti Konganti, 02/27/2013 11:25 am

set_annotation.png (136.3 kB) Kranti Konganti, 03/12/2013 01:22 pm

loading_annotation.png (78.5 kB) Kranti Konganti, 03/12/2013 01:22 pm

full_annotation_of_node.png (44.1 kB) Kranti Konganti, 03/12/2013 01:22 pm