The Osprai API is the set of public functions and classes contained in the osprai_one module. The API provides an interface to the software from a python command line, such as IPython. In the future, web or desktop graphical user interfaces could be written using this API to assist SPR users with common data anaylsis procedures.
To use Osprai, set your Python path environment variable to the location where it is installed. This can be done from the shell (bash example):
$ export PYTHONPATH=/home/user/osprai/trunk
$ ipython
Alternatively, the path can be set from inside the Python interpreter (IPython example):
>>> import sys
>>> sys.path.append('/home/user/osprai/trunk')
>>> import osprai_one as osp
>>> help osp
Biosensor Array class for storing SPRI data. This contains an array of SPR sensorgrams with their associated models and parameters. This can also contain the microarray geometery.
Examples:
>>> ba1 = BiosensorArray(800,1500) ## Allocate object with 800 spots of 1500 time points.
>>> ba1.roi[799].time[1499] = 7502.1 ## Set time in seconds.
>>> ba1.roi[799].value[1499] = 0.50 ## Set SPR reflectance signal.
>>> ba1.roi[799].name = "anti-IgG" ## Set name of microarray feature.
>>> print ba1.roi[799].name
anti-IgG
>>> ba1 = BiosensorArray(1, 300)
>>> ba1.roi[0].simulate(bulkRI=1000, kon=1e4, koff=1e-2, conc=1e-6)
>>> print round(ba1.roi[0].value[299], 1)
160.6
The Biosensor Array class holds all ROIs (spots) from an SPRI microarray run.
| Property | Type | Description |
| roi | list of object | List of RegOfInterest objects. |
| rois | integer | Size of roi (Number of ROIs). |
| dpoints | integer | Number of datapoints in each ROI. |
| primarydatafiles | list of string | List of file names. |
| comments | list of string | List of comments regarding experiments. |
Load data from sba file into this ba object.
Save (serialize) this ba object as a file. Use the extension ‘.sba’ and designate it file format 1. Use cPickle protocol 2 (binary).
Choose to plot every sensorgram.
Choose a list of sensorgrams to plot
Given roi coordinates, find corresponding uid (index).
This Region Of Interest class can hold one SPR sensorgram.
| Property | Type | Description |
| uid | integer | Unique ID integer. Never changes. |
| index | integer | Changes if ba size changes (add/remove rois). |
| time | nparray | Usually seconds. |
| value | nparray | Arbitrary units. |
| dpoints | integer | Can use for bounds checking. |
| name | string | Name of ROI. |
| desc | string | Description of ROI |
| gridx | integer | Can be Block number from GAL file. |
| gridy | integer | Unused? |
| spotx | integer | ROI column number. |
| spoty | integer | ROI row number. |
| bgroi | list of integer | One or more background ROIs. |
| calibM | float | Slope used for calibration |
| calibB | float | Intercept used for calibration. |
| plottable | boolean | Whether to plot |
| injconc | list of float | One or more analyte concentrations. |
| injstart | list of float | One or more injection start times. |
| injstop | list of float | One or more injection start times. |
| injrind | list of float | One or more expected refractive index jumps. |
| flow | float | Flowrate of injection. |
| model | ref to funct | Model describing this ROI. |
| params | dict of dict | Parameters for this model. |
Fill ROI with 300 s of simulated data from simple 1:1 binding. First, there is a brief calibration injection from 35 to 65 s that appears as a square wave of height bulkRI. At time 100 s, there is a jump of 10% bulkRI followed by binding at a rate dependent on kon and conc. At time 200 s, dissociation occurs at rate koff. The maximum response (Rmax) is fixed at 1000 units. The model is based on these equations:
alpha = c*kon+koff
Req = Rmax*c*kon / alpha
R = Req * [1 - exp(-t*alpha)]
Find datapoint closest to given time. For example:
>>> ba1 = BiosensorArray(1, 300)
>>> ba1.roi[0].simulate()
>>> print ba1.roi[0].time2dp(40.333)
40
Return list of SPR values between t1 and t2. For example:
>>> ba1 = BiosensorArray(1, 300)
>>> ba1.roi[0].simulate()
>>> print min(ba1.roi[0].time2val(35, 65))
1000.0
This is the viewer module for SPR data in a ba_class. Traces can be displayed as dotted lines, continuous lines, or combinations. Typically, up to six traces are displayed at a time. Features include zooming, measurements, and save-to-PNG. Graphics utilize the old Tk GUI toolkit.
Examples:
>>> import vu_module as vu
>>> import io_module as io
>>> ba1 = io.readsprit("spritdata.txt")
>>> vu.dotgraph(ba1, "Title")
>>> vu.linegraph(ba1, "Title")
>>> vu.dualgraph(ba1, ba2, "Title")
>>> vu.scatterplot(ba1, t1, t2, t3, t4, title)
Display signal vs time using dotted lines.
| Parameters: |
|
|---|---|
| Returns: | nothing |
Display signal vs time using dotted AND continuous lines. To graph measured and fitted data together, specify the same object for baDot and baLine.
| Parameters: |
|
|---|---|
| Returns: | nothing |
Display signal vs time using continuous lines.
| Parameters: |
|
|---|---|
| Returns: | nothing |
Plot binding changes between (t4-t3) versus (t2-t1). Also print the results to the standard output.
| Parameters: |
|
|---|---|
| Returns: | nothing |
Calibration module for SPRI data in a ba_class. This uses a known jump in index to turn arbitrary units into RIU. Other routines provide background subtraction and data rearrangement.
Example:
>>> import ba_class as ba
>>> ba1 = ba.BiosensorArray(2, 300) ## Create ba simulated data.
>>> ba1.roi[0].simulate(bulkRI=900, kon=1e4, koff=1e-2, conc=0.0)
>>> ba1.roi[1].simulate(bulkRI=900, kon=1e4, koff=1e-2, conc=1e-5)
>>> t1, t2 = 15, 50
>>> n1, n2 = 1335700, 1336600
>>> baCal = ba1 ## Calibration injection is in same ba.
>>> ba2 = calibrate(ba1, baCal, t1, t2, n1, n2)
>>> bgset(ba2, 0) ## The first ROI is the background ref.
>>> ba3 = bgsubt(ba2)
>>> zerotime(ba3) ## Optional, time already starts at zero.
>>> zerovalue(ba3) ## Optional, value already starts at zero.
>>> print round(ba3.roi[1].value[299], 2)
337.79
Set i as the background ROI for all of the ROIs.
| Parameters: | |
|---|---|
| Returns: | nothing |
Apply the background subtraction and return a new ba object.
| Parameters: | ba0 (ba_class) – Object containing the source data. |
|---|---|
| Returns: | A new ba object |
Use data in baCal to calibrate ba0. A simple two-point linear calibration using timepoints t1 and t2 and corresponding refractive indices n1 and n2. Average 30 seconds of data (t-15 to 5+15 seconds). The ba object returned will remember the slopes and intercepts used.
| Parameters: |
|
|---|---|
| Returns: | nothing |
Copy data from the interval between t1 and t2 and return a new ba object.
| Parameters: |
|
|---|---|
| Returns: | A new ba object |
Flatten nested lists into one list.
| Parameters: | lst – Non-list, list, or list of lists! |
|---|---|
| Returns: | flat list |
Input/Output module for converting files to Biosensor Array class. Supported sensorgram types include Biosensor, CLAMP, SPRit, and Plexera ICM. Supported microarray types include GAL and ISB Map.
Examples:
> import osprai_one as osp
> ba1 = osp.readsprit("spritdata.txt")
> ba1 = osp.readclamp("clampdata.txt")
> ba1 = osp.readicmtxt("icmdata.txt")
> ba1 = io.readbiosensor("biodata.txt")
> ba1 = osp.readcsv("rawdata.csv")
> ba2 = osp.applygal(ba1, "galfile.gal")
> ba2 = osp.applykey(ba1, "keyfile.tsv")
> ba3 = osp.applymethod(ba2, "icmmethod.xls")
> osp.writesprit(ba3, "newspritfile.txt")
> osp.writeclamp(ba3, "newclampfile.txt")
This class helps to convert between strings and lists. This will help with CSV or TSV file import and export. The string form has data in columns separated by a delimiter. The list form is a list of lists of strings like data[column][row] Best to convert numbers to strings before entering them in table.
Example:
>>> tsv = TsvTable(delimiter=',')
>>> tsv.read("1,2.2,3a \n 4,5.5,6b")
>>> print tsv.d
[['1', '4'], ['2.2', '5.5'], ['3a', '6b']]
>>> tsv.setcolumn(2, ['3.3', '6.6'])
>>> tsv.getcolumn(2)
['3.3', '6.6']
>>> print tsv.columns, tsv.rows
3 2
>>> print tsv.write()
1,2.2,3.3
4,5.5,6.6
Read a GAL file and apply its microarray information. Return a new object containing the data of ba0 modified with the data of the GAL file.
An example GAL file:
ATF 1
6 5
"Type=GenePix ArrayList V1.0"
"BlockCount=1"
"BlockType=0"
"Block1=10000, 38780, 150, 20, 200, 18, 200"
"SlideBarcode=abc0001"
"ScanResolution=10"
Block Column Row ID Name
1 1 1 aIgG Antibody01
1 1 2 aIgM Antibody02
A description of this GAL file:
ATF -> File conforms to Axon Text File
1 -> Version number of ATF
6 -> Header lines before the "Block, Column, Row, ..." line
5 -> Data columns (Block, Column, Row, Name, ID)
BlockCount=1 -> Number of blocks described in the file
BlockType=0 -> Type of block, 0 = rectangular
BlockX=xOrigin,yOrigin,diameter,xFeatures,yFeatures,xSpacing,ySpacing
SlideBarcode -> Barcode (optional)
ScanResolution -> Resolution in microns (optional)
The blocks are ordered from left to right and then top to bottom. Fields must be separated by tabs. Quotes are optional and might be used when fields contain spaces. Each record (microarray feature) is applied to an ROI in the order listed in the GAL file. The Block, Column, and Row number is not considered when determined the corresponding ROI.
Example:
>>> import osprai_one as osp
>>> ba0 = osp.BiosensorArray(20,100)
>>> ba1 = osp.applygal(ba0, "./exampledata/example-20spot.gal")
Successfully loaded information for 20 ROIs.
Read a Key file and apply its microarray information. Multiple background ROIs are not yet supported. Here is a very simple example:
No. Description1 Description2 Background ROI Col Row
1 Rat TNF Antibody01 2 1 1
2 ratIgG Antibody02 4 2 1
3 Hum TNF Antibody03 4 3 1
4 humIgG Antibody04 2 4 1
Example:
>>> import osprai_one as osp
>>> ba0 = osp.BiosensorArray(2,100)
>>> ba1 = osp.applykey(ba0, "./exampledata/example-key.tsv")
Successfully loaded information for 2 ROIs.
Read a ICM Analyte/Method xls file and apply its information.
(This feature is under construction.)
Measure the binding level changes at multiple intervals along a sensorgram. Write the data to a file. If interval is 500 and baselines are [100, 1100] then binding levels are changes between 100-600s and between 1100-01600s. Average 30s of data.
Read a Biacore-style text file into a ba class. Here is a very simple example of the tab-delimited format:
Ab1 Fc=4- 1_X Ab1 Fc=4 -1_Y Ab2 Fc=4 -1_X Ab2 Fc=4 -1_Y
13.1 23.7644 93.1 0.713912
13.6 23.4265 93.6 0.0541172
14.1 23.1625 94.1 0.332768
14.6 23.5752 94.6 0.849459
Example:
>>> import osprai_one as osp
>>> ba0 = osp.readbiosensor("./exampledata/example-biosensor.txt")
This Biosensor file has 9 datapoints for 2 ROIs.
Read a Clamp text file into a ba class. It has two tab-delimited columns per SPR flowcell/roi.. It has a varying number of header lines with injection information. Here is a very simple example with 2 rois and 3 datapoints:
Vers 3.41 Data
Conc1 0 0 0 0
Start1 301.5 301.5 301.5 301.5
Stop1 949.8 949.8 949.8 949.8
RInd1 0 0 0 0
Conc2 0 0 0 0
Start2 986.4 0 0 0
Stop2 1626 0 0 0
RInd2 0 0 0 0
Flow 1 1 1 1
Time1 Data1 Time2 Data2
0.094 0.062 0.094 0.053
1.094 0.026 1.094 0.05
2.094 0.119 2.094 0.055
Example:
>>> import osprai_one as osp
>>> ba0 = osp.readclamp("./exampledata/example-clamp.txt")
This feature is under construction.
Read a comma-separated value text file into a ba class. The first column contains time data while the others contain response data. Here is a very simple example of the format:
1.0001, 23.7644, 0.7139
2.0001, 23.4265, 0.0541
3.0001, 23.1625, 0.3327
4.0001, 23.5752, 0.8494
Example:
>>> import osprai_one as osp
>>> ba0 = osp.readcsv("./exampledata/example-csv.csv")
This file has 4 datapoints for 2 ROIs.
Read a ICM text file into a ba class. Here is a very simple example of the tab-delimited format:
03/05/2010 13:37:21.312 249.408 0.000 0.000
03/05/2010 13:37:22.312 249.306 0.000 0.000
Example:
>>> import osprai_one as osp
>>> ba0 = osp.readicmtxt("./exampledata/example-icm.txt")
This ICM file has 6034 datapoints for 25 ROIs.
Read a SPRit text file into a ba class. It has two tab-delimited columns and two header lines. Here is a very simple example with 2 rois and 3 datapoints:
Elapsed Time (Seconds) Average Intensity (Pixel Intensity)
BEGIN
0.000000e+000 2.863145e+003
5.013000e+000 2.863367e+003
1.002500e+001 2.862950e+003
0.000000e+000 2.862875e+003
5.013000e+000 2.862510e+003
Example:
>>> import osprai_one as osp
>>> ba0 = osp.readsprit("./exampledata/example-sprit.txt")
Successfully loaded information for 2 ROIs.
Write a ba class to a Biosensor text file.
Write a ba class to a Clamp text file.
Write a ba class to a SPRit text file.
Example model functions module for SPRI data. Just a few simple, common interaction models will go here. In the future, each new model will go in its own module/file. Each model is a function taking three parameters.
Returns: numpy array of calculated SPR signal values.
The dictionary keys are the names of model parameters (e.g. ‘rmax’ for maximal response, or ‘kon’ for kinetic on-rate). Each model parameter is described by a subdictionary containing four entries.
- 'value' The current value of the parameter.
- 'min' The minimum allowable value.
- 'max' The maximum allowable value.
- 'fixed' Either ‘float’, ‘fixed’, or a reference to another ROI.
The min, max, and fixed keys are used during automatic curve-fitting. A fixed parameter is not allowed to change, while a float parameter is adjusted until the least-squares algorithm has minimized the sum-squared error. The fixed parameter may also be an integer, in which case it is fixed to the value of a parameter of the same name in another ROI.
The model function returns an array of values obtained by numerical integration. The model is represented by differential equations and integrated using the rectangle rule or, preferentially, using the trapezoidal rule.
Functions are also available that provide parameter dictionaries containing all the necessary default values.
Examples:
>>> import mdl_module as mdl, numpy as np
>>> times, data = np.arange(300), np.zeros(300)
>>>
>>> param1 = {'rate': {'value':1.0, 'min':-10.0, 'max':10.0, 'fixed':True} }
>>> data1 = mdl.drift(times, data, param1)
>>> print round(data1[299], 1)
299.0
>>> param1 = dict(rate=dict(value=-1.0, min=-10.0, max=10.0, fixed=True))
>>> data1 = mdl.drift(times, data, param1)
>>> print round(data1[299], 1)
-299.0
>>>
>>> param2 = mdl.simple1to1_def_params()
>>> param2['rmax'] ['value'] = 1000.0
>>> param2['conc']['value'] = 1e-6
>>> param2['t1']['value'] = 100
>>> param2['kon']['value'] = 1e4
>>> param2['t2']['value'] = 200.0
>>> param2['koff']['value'] = 1e-2
>>> param2['t3']['value'] = 300.0
>>> data2 = mdl.simple1to1(times, data, param2)
>>> print round(data2[299], 1)
160.3
Linear Least-squares regression class. Example:
>>> r = LinearRegression()
>>> r.data(0, 0)
>>> r.data(10, 23)
>>> r.data(20, 40)
>>> print r.slope(), r.intercept()
2.0 1.0
>>> print r.yvalues()
[1.0, 21.0, 41.0]
Add a data point by providing an x and y value.
Return the y-intercept from the linear regression.
Return the slope from the linear regression.
Return the list of x values provided.
Return the calculated y values for the given x values.
This function simply models a constant signal drift in units/second. It requires numpy arrays of times and starting data values. It only requires one parameter in the params list, params['rate']['value'].
Return dictionary of default parameters for drift model. For example:
>>> from numpy import arange, zeros
>>> defaultparam0 = drift_def_params()
>>> data0 = drift(arange(100), zeros(100), defaultparam0)
>>> print round(data0[99], 1)
99.0
This function simply adds gaussian noise. It requires numpy arrays of times and starting data values, It only requires one parameter in the params list, params['rms']['value'].
This function simply models a 1:1 interaction. The model parameters are described in the table below.
Model:
[A] + [L] --kon--> [AL]
[A] + [L] <-koff-- [AL]
Derivation:
d[AL]/dt = kon*[A]*[L] - koff*[AL]
y = [AL]
(rmax-y) = [L]
conc = [A]
rmax = [AL] + [L]
dy/dt = conc*kon*(rmax-y) - koff*y
| Model Parameter | Description |
|---|---|
| params[‘t0’][‘value’] | time of start baseline stabilization, (s) |
| params[‘t1’][‘value’] | time of injection for binding, (s) |
| params[‘rmax’][‘value’] | maximum response, (RIU) |
| params[‘conc’][‘value’] | concentration of analyte [A], (M) |
| params[‘kon’][‘value’] | on-rate of analyte, (1/Ms) |
| params[‘t2’][‘value’] | time of end binding & begin washing, (s) |
| params[‘koff’][‘value’] | off-rate of analyte, (1/s) |
| params[‘t3’][‘value’] | time end of washing & data fitting, (s) |
| Optional | |
| params[‘cofa’][‘value’] | concentration factor, (1/dilution factor) |
Return a dictionary of default parameters for simple1to1 model. For example:
>>> from numpy import arange, zeros
>>> defaultparam0 = simple1to1_def_params()
>>> data0 = simple1to1(arange(300), zeros(300), defaultparam0)
>>> print round(data0[299], 1)
160.3
This function simply models a 1:1 interaction with mass transport limitation. The model parameters are described in the table below.
Model:
[Abulk] --km-> [Asurf] + [L] --kon--> [AL]
[Abulk] <-km-- [Asurf] + [L] <-koff-- [AL]
Derivation:
d[AL]/dt = (kon*[A]*[L] - koff*[AL]) / (1 + kon*[L]/kmtl)
y = [AL]
(rmax-y) = [L]
conc = [Abulk]
rmax = [AL] + [L]
dy/dt = (kon*conc*(rmax-y) - koff*y) / (1 + kon*(rmax-y)/kmtl)
| Model Parameter | Description |
|---|---|
| params[‘t0’][‘value’] | time of start baseline stabilization, (s) |
| params[‘t1’][‘value’] | time of injection for binding, (s) |
| params[‘rmax’][‘value’] | maximum response, (RIU) |
| params[‘conc’][‘value’] | concentration of analyte [Abulk], (M) |
| params[‘kon’][‘value’] | on-rate of analyte, (1/Ms) |
| params[‘t2’][‘value’] | time of end binding & begin washing, (s) |
| params[‘koff’][‘value’] | off-rate of analyte, (1/s) |
| params[‘t3’][‘value’] | time end of washing & data fitting, (s) |
| params[‘kmtl’][‘value’] | rate of diffusion, (RIU/Ms) |
| Optional | |
| params[‘cofa’][‘value’] | concentration factor, (1/dilution factor) |
Return dictionary of default parameters for simple1to1_mtl model. For example:
>>> from numpy import arange, zeros
>>> defaultparam0 = simple1to1_mtl_def_params()
>>> data0 = simple1to1_mtl(arange(300), zeros(300), defaultparam0)
>>> print round(data0[299], 1)
161.1
Model up to 8 simple 1:1 SPR injections of varying concentration.
| Model Parameter | Description |
|---|---|
| params[‘kon’][‘value’] | on-rate of analyte, (1/Ms) |
| params[‘koff’][‘value’] | off-rate of analyte, (1/s) |
| params[‘rmax’][‘value’] | maximum response, (RIU) |
| params[‘tp’][‘value’] | time prior to binding, (s) |
| params[‘ta’][‘value’] | time/duration of association, (s) |
| params[‘td’][‘value’] | time/duration of dissociation, (s) |
| params[‘t0’][‘value’] | timepoint of first (no.0) injection, (s) |
| ... | ... |
| params[‘t7’][‘value’] | timepoint of eighth (no.7) injection, (s) |
| params[‘c0’][‘value’] | concentration of first injection, (s) |
| ... | ... |
| params[‘c7’][‘value’] | concentration of eighth injection, (s) |
Injections where tN=0 are ignored. For example, if you have only six injections, set t6=0 and t7=0.
Return a dictionary of default parameters for simple1to1_series model. While parameters for eight injection times are provided, only the first injection time is nonzero. For example:
>>> from numpy import arange, zeros
>>> defaultparam0 = simple1to1_series_def_params()
>>> data0 = simple1to1_series(arange(300), zeros(300), defaultparam0)
>>> print round(data0[299], 1)
160.3
Curve-fitting module for SPRI data. These routines are based on the Levenberg-Marquart Algorithm (LMA) from SciPy. This module provides several extended features that make it particularly powerful for the analysis of high-throughput SPRI data.
- Constrained parameters. Invalid results such as negative kinetic rates can be avoided.
- Simultaneous fitting of multiple curves. Parameters used in one ROI may be tied to those in other ROIs.
- Multiple models may be specified. Different ROIs may exhibit different binding interactions.
Users should take advantage of the mclma() function. The lma() and clma() functions have been deprecated.
Examples:
>>> import osprai_one as osp, numpy as np
>>> ba1 = osp.BiosensorArray(1,300)
>>> roi = ba1.roi[0]
>>> ## Simple 1to1 binding curve.
>>> ## Note KD = 2.2e-2 / 4.4e-4 = 5e-7, log10(5e-7) = -6.3
>>> roi.simulate(bulkRI=0.0, kon=4.4e4, koff=2.2e-2, conc=7.7e-7)
>>> ## Create a copy ba2 and use for fitting three parameters.
>>> ba2 = osp.deepcopy(ba1)
>>> roi = ba2.roi[0]
>>> roi.model = osp.simple1to1
>>> roi.params = osp.simple1to1_def_params()
>>> roi.params['rmax']['fixed'] = 'float'
>>> roi.params['kon']['fixed'] = 'float'
>>> roi.params['koff']['fixed'] = 'float'
>>> roi.params['conc']['value'] = 7.7e-7
>>> ## Do curvefitting, then check result.
>>> osp.mclma(ba2.roi, verbose=False)
2
>>> roi.value = osp.zeros(len(roi.value))
>>> roi.value = roi.model(roi.time, roi.value, roi.params)
>>> kD = float(roi.params['koff']['value']) / float(roi.params['kon']['value'])
>>> print round((np.log10(kD)), 1)
-6.3
Constrained LMA curve-fitting. (Deprecated) Least-squares curve-fitting is performed on the data in the specified ROI. The ROI must contain SPR data, a model, and initial (guess) parameters. The roi.params values are modified in place. The maximum number of iterations is set to 999.
| Parameters: | roi (RegOfInterest) – ROI containing data, a model, and initial parameter guesses. |
|---|---|
| Returns: | number of iterations completed. |
Normal LMA curve-fitting. (Deprecated) Least-squares curve-fitting is performed on the data in the specified ROI. The ROI must contain SPR data, a model, and initial (guess) parameters. The roi.params values are modified in place. The maximum number of iterations is set to 500.
| Parameters: | roi (RegOfInterest) – ROI containing data, a model, and initial parameter guesses. |
|---|---|
| Returns: | number of iterations completed. |
Multiple-curve Constrained Levenberg-Marquart Algorithm. Least-squares curve-fitting is performed on the data in the specified ROIs. The ROIs must contain SPR data, a model, and initial (guess) parameters. The roi.params values are modified in place. The maxiter specifies the maximum number of iterations (default 999). The verbose option is used to display progress (default True).
| Parameters: | rois (List of RegOfInterest) – ROI containing data, a model, and initial parameter guesses. |
|---|---|
| Returns: | number of iterations completed. |