rrPlugins

Introduction

The plugin API allows users to easily access roadrunner plugins. Only three concepts need to be understood:

Loading a plugin
Setting and Getting plugin properties
Executing the plugin

Before using the plugin system the plugin library must be imported using the line:

import rrplugins as tel

To load a plugin called “add_noise” use the Python command:

p = tel.Plugin("tel_add_noise")

The variable p now represents the plugin. Plugins expose a number of properties, these are variables that can be inspected or set. For example the add noise plugin has a property called Sigma. To set this to a particular value we would use:

p.Sigma = 0.5

Likewise, properties can be inspected:

print(p.Sigma)

To list all propreties in a plugin use the method listOfProperties. The following uses call together with pprint to make the output more understandable:

p.listOfProperties()
[['NoiseType', 'Type of noise (Gaussian = 0).'], ['Sigma', 'Size of applied noise'], ['InputData', 'Data on which noise will be applied to'], ['AssumeTime', "Assume the first column in the input data is time, and don't add noise to it."], ['Progress', 'Indicate progress in (0-100%)'], ['Seed', "Seed to use for each use of 'execute' (0 to ignore)"]]

To run a plugin so that it carries out its function, use the execute method:

p.execute()

The results from an execute call will either be saved to a file or more likely via properties of the plugin. As a trivial example, consider a plugin called “test” that has three properties, x, y and z. When the execute() method is called the plugin will take the values stored in x and y, add them together and store the result in z. The following script illustrates how the plugin would be used from Python:

import rrplugins as tel
p = tel.Plugin("test")
p.x = 1.2
p.y = 4.5
p.execute()
print(p.z)

The following script illustrates a more substantial example using the add_noise plugin:

import roadrunner
import rrplugins as tel

rr = roadrunner.RoadRunner()
rr.load("path to any model. Eg. some models are provided in source code, like, sbml_test_0001")

data = rr.simulate(0, 10, 50)

noisePlugin = tel.Plugin("tel_add_noise")

d = tel.getDataSeries(data)

noisePlugin.InputData = d

noisePlugin.Sigma = 5.e-6

noisePlugin.execute()

noisePlugin.InputData.plot()

DataSeries

The plugin system supports a special data type called a Data Series. This is a convenient way to represent rows and colums of data. The data type also has the ability to label columns with a text string and to associate each value in the data series with an additional value called a weight. In practice the data series will usually store experimental data and the weights will represent a measure of undertaintly, perhaps a standard deviation, of the data point. A Data Series can be created using the call:

import rrplugins as tel
data = tel.DataSeries()

Data can be entered into a data series either by loading the data from a specially formated file or from a Python NumPy array. For example:

data.readDataSeries ("mydata.txt")

To read numpy arrays into a data series use the code:

import numpy as np
values = np.array([[1,2],{2,5],[3,7]])
data = tel.DataSeries.fromNumPy (values)

The number of rows and columns in a Data Series can be obtained using:

print(data.rows)
print(data.cols)

Currently individual values in a data series can be accessed using the set and get methods:

p.setElement (1, 2, 4.567)
print(p.getElement(1, 2))

Data series can be plotted using the plot method:

data.plot()

The following script is an example of using the add_noise plugin. This plugin takes a data series and add a given amount of Guassian noise to all data except the data in the first column.

import rrplugins as tel
p = tel.Plugin ("tel_add_noise")
p.viewManual()
pl = p.listOfProperties()
for item in pl:
    print(item)

p.Sigma = 0.00005
series = DataSeries.loadDataSeries("..\\Examples\\testData.dat")
series.plot()
p.InputData = series
p.execute()
p.InputData.plot()

print("Test Finished")

Plugins

Plugin objects are instanciated using Plugin class. For example to instanciate a plugin called myplugin, we would use the code:

p = Plugin("myplugin")

All interactions with plugins are via plugin properties. Values can be set and retrieved via plugin properties. For example, if a plugin has a property sigma, we can assign or access the value using the code:

p.sigma = 0.1
print(p.sigma)

Plugins have a single method that can be used to excecute the plugin’s functionality:

p.execute()

Once a plugin has been executed, any output from the plugin can be retrieved via properties. Let’s suppose for example there is a plugin all “test”, which has three properties called, x, y and result. When executed the plugin will take the values in x and y, compute the sum and assign it to result. The plugin can therefore be used as follows:

p = Plugin("add")
p.x = 3.4
p.y = 5.6
p.execute()
print(p.result)