Plugins for Tellurium

Introduction

The Tellurium plugin library exposes a simple framework for adding functionality to the RoadRunner core, by means of external plugins. The code fragment below shows briefly how to load plugins, check for plugins, and use an individual plugin.

from teplugins import *

try:    
    # Create a plugin manager
    pm = createPluginManager()
        
    # Load plugins from the plugin folder
    result = loadPlugins(pm)
    
    print 'Number of Plugins: ' + `getNumberOfPlugins(pm)`
    print 'Plugin Names: ' + `getPluginNames(pm)`
    
    #Go trough all plugins and print information
    aPlugin = getFirstPlugin(pm)
    while True:
        if aPlugin == None:
            break            
        print '=========================================='
        print 'Name: ' + `getPluginName(aPlugin)`
        print 'Author: ' + `getPluginAuthor(aPlugin)`
        print 'Copyright: ' + `getPluginCopyright(aPlugin)`
        print 'Version: ' + `getPluginVersion(aPlugin)`
        print 'Category: ' + `getPluginCategory(aPlugin)`                        
        print 'Description:' + `getPluginDescription(aPlugin)`
        print 'Parameters: ' + `getListOfPluginPropertyNames(aPlugin)`                    
        
        #get next plugin
        aPlugin = getNextPlugin(pm)
    
    unLoadPlugins(pm)    
    
except Exception as e:
    print 'There was a problerm: ' + `e`    

The above code produces something like the following output (depends on installed plugins):

>>> 
Number of Plugins: 3
Plugin Names: ['AddNoise', 'ChiSquare', 'Levenberg-Marquardt', 'SBMLModel']
==========================================
Name: 'AddNoise'
Author: 'Totte Karlsson'
Copyright: 'Totte Karlsson, Herbert Sauro, Systems Biology, UW 2012-2014'
Version: '1.0'
Category: 'Signal Processing'
Description:'The AddNoise plugin adds Gaussian noise to synthetic data. The amount of noise is controlled by the plugins Sigma property. Specifically, noise is generated for each single data value, with a probability corresponding to a Gaussian distribution centered around the value, and with a variance equal to (sigma^2). The Plugin accepts Tellurium data as input, in the "InputData" property. Currently only Gaussian noise is supported. The progress of the application of noise can be read in the Progress property. Noise will not be generated onto the first column of data, if its column label is equal to "Time", (not case sensitive). The AddNoise plugin was developed at the University of Washington by Totte Karlsson, 2012-2014.'
Parameters: ['NoiseType', 'Sigma', 'InputData', 'Progress']
==========================================
Name: 'ChiSquare'
Author: 'Totte Karlsson'
Copyright: 'Totte Karlsson, Herbert Sauro, Systems Biology, UW 2012-2014'
Version: '0.8'
Category: 'Misc'
Description:None
Parameters: ['ExperimentalData', 'ModelData', 'NrOfModelParameters', 'ChiSquare', 'ReducedChiSquare']
==========================================
Name: 'Levenberg-Marquardt'
Author: 'Totte Karlsson'
Copyright: 'Totte Karlsson, Herbert Sauro, Systems Biology, UW 2012-2014'
Version: '0.8'
Category: 'Fitting'
Description:'The Levenberg-Marquardt plugin is used to fit a proposed SBML models parameters to experimental data. The current implementation is based on the lmfit C library by Joachim Wuttke. The Plugin has numerous parameters for fine tuning the algorithm. See the embedded PDF for more information. '
Parameters: ['SBML', 'ExperimentalData', 'FittedData', 'Residuals', 'InputParameterList', 'OutputParameterList', 'ConfidenceLimits', 'ExperimentalDataSelectionList', 'FittedDataSelectionList', 'Norm', 'Norms', 'NrOfIter', 'StandardizedResiduals', 'NormalProbabilityOfResiduals', 'ChiSquare', 'ReducedChiSquare', 'ftol', 'xtol', 'gtol', 'epsilon', 'stepbound', 'patience']
==========================================
Name: 'SBMLModel'
Author: 'Totte Karlsson'
Copyright: 'Totte Karlsson, Herbert Sauro, Systems Biology, UW 2012-2014'
Version: '1.0'
Category: 'Examples'
Description:'The SBMLModel plugin exposes one property containing data, as a string, for an ExampleModel. The ExampleModel plugin was developed at the University of Washington by Totte Karlsson, 2012-2014.'
Parameters: ['Model']
>>> 

Overview

The Tellurium Plugin API is centered around three important concepts:

• A Plugin Manager
• Plugins
• Plugin Properties

How to use plugins

A typical use case of the Plugin API may be as follows:

1. Client creates a PluginManager.
2. Client load plugins using the Plugin Manager.
3. Client get a handle to a plugin.
4. Client get a handle to a specific property in the plugin.
5. Client set the value of the property.
6. Client excutes the plugin.
7. Client retrieve the value of a plugins property, e.g. a "result" property.

PluginEvent functionality

In addition to data properties that communicate data between a client and the plugin, the framework also support for a variety of plugin event functions. In short, an event is a regular function that is defined and implemented by the client of a plugin, but executed from within the plugin, during the plugins execution.

A single plugin may support of up to three event functions. The intended use of these functions are to signal the events of the following:

1. Plugin Initialization
2. Plugin Progress
3. Plugin Finalization

Each event function support up to two opaque data properties. The plugin documentation needs to provide the exact type of these arguments. In it simplest form, a plugin may choose to define an event function taking no arguments at all. Below are listed a few properties, characteristics of events in the Tellurium Plugin framework.

1. A plugin event is a regular function defined by the client of the plugin.
2. A plugin event function do not return any value.
3. The type and number of arguments needed in the plugin event is defined by the plugin (see plugin docs).
4. Plugin events are assigned to the plugin before a plugins execute function.
5. Assigning events is optional. A plugins internal work should not be affected wether an event is assigned or not.
6. Plugin events are blocking functions. If the work in a plugin is executed in a thread, see executeEx, the plugin event will be executed in the same thread as the plugin worker. Depending on your environment and if the plugin event function is executed in a separate thread, regular use of thread synchronization measuress may be needed in order to not create an unstable system.

See the examples page that provide example code on how to use plugins, properties and event functions.

How to write plugins

Note

Writing plugins in Python is not yet supported

Using telPlugins.py

In order to use this wrapper, telplugins need to be installed properly. Typically all neeeded to be done is to run the install_tellurium_plugins.py script, available in the root folder of the release.