ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/osprai/osprai/trunk/help/osprai-doc.html
Revision: 35
Committed: Thu Aug 19 07:31:59 2010 UTC (8 years, 9 months ago) by clausted
File size: 14719 byte(s)
Log Message:
Updates to the documentation.  Mention the online help.  Add hyperlinks to SVN clients.
Line File contents
1 <html>
2
3 <head>
4 <meta http-equiv='Content-Type' content='text/html; charset=us-ascii' />
5 <link rel="STYLESHEET" href="./osprai-doc.css" type="text/css" />
6 <title>OSPRAI Tutorial</title>
7 </head>
8
9 <body>
10 <h1>
11 OSPRAI Documentation
12 </h1>
13
14 <p>
15 OSPRAI is the Open-source SPR Analysis and Integration software.
16 </p>
17
18 <h2>
19 Getting Started
20 </h2>
21
22 <h3>
23 Software installation
24 </h3>
25 OSPRAI is written in Python so as to run on all popular platforms, including Linux, Windows, and Macintosh.
26 Install Python 2.4 (or newer) and the following libraries: python-tk, matplotlib, and scipy.
27 Additionally, it is useful to install IPython, the interaction Python shell, as well as a good python-aware text editor, such as Scite or gedit.
28 OSPRAI is hosted by Bioinformatics.org and managed using the Subversion version control system.
29 It can be obtained from the website or by using a Subversion client such as <a href="http://subversion.apache.org">Svn</a>, <a href="http://rapidsvn.tigris.org">RapidSVN</a>, or <a href="http://tortoisesvn.tigris.org">TortoiseSVN</a>.
30 Windows users can install all of the necessary prerequisites by installing <a href="http://www.pythonxy.com">PythonXY</a>, while Ubuntu Linux users can find everything they need in the Ubuntu repositories.
31 An example for Ubuntu users follows.
32
33 <pre>
34 > sudo apt-get install python-tk python-matplotlib scipy ipython scite
35 > svn checkout svn://bioinformatics.org/svnroot/osprai/osprai
36 </pre>
37
38
39 <h3>
40 Viewing data from an SPR file
41 </h3>
42 Analysis begins with viewing data generated by a biosensor instrument such as a Biacore or Plexera.
43 Launch a python interpreter such as the standard interpreter or IPython and navigate to the directory containing the OSPRAI code and example data files.
44 Enter the following commands to load and view an example data file.
45
46 <pre>
47 <code>from osprai_one import *
48 <code>ba1 = readicmtxt("example-icm.txt")
49 <kbd>This ICM files has 6034 datapoints for 25 ROIs.</kbd>
50 <code>linegraph(ba1)
51 <img src="figure02.png">
52 </pre>
53
54 The first line imports all of the functions and data classes needed by the user.
55 Function <samp>readicmtxt()</samp> reads an SPR data file saved by the Plexera Instrument Control Software.
56 Other data formats are supported and described later.
57 A object of the class Biosensor_array (BA) is created named <var>ba1</var> containing the data.
58 <p>
59 Function <samp>linegraph()</samp> plots the data as a sensorgram--the SPR signal versus time.
60 This plot appears in a separate window.
61 At the lower left corner of the window are buttons for zooming, copying, and saving (PNG format).
62 These buttons will be familiar to matplotlib users.
63 At the lower right corner are three buttons for changing which ROIs are displayed.
64 While it is possible to display all ROIs in a BA object, a plot with 25 ROIs would be too cluttered.
65 By default, only the first six ROIs in the BA are shown.
66 Clicking the "Next6" button will change the plot to display ROIs 6-11 and a subsequent click on the "Prev6" button will display ROIs 0-5 again.
67 An arbitrary list of ROIs can be specified by clicking the "Choose..." button.
68 The window must be closed in order to continue the execution of Osparai commands
69
70 <h3>
71 Calibration and background subtraction
72 </h3>
73 Data produced by a biosensing instrument can be reported as angle shift, reflectance, wavelength shift, resonance units (RU), or other units.
74 This data can come from a single surface or channel, in which case the bulk refractive index changes of the samples and washes can be seen, or it may be the difference between two surfaces or channels.
75 The example file used here is uncalibrated and unreferenced.
76 Enter the following commands for calibration and referencing.
77
78 <pre>
79 <code>ba2 = calibrate(ba1, ba1, 2850, 3120, 1333000, 1334000)
80 <code>linegraph(ba2, "Calibrated SPR Data")
81 <img src="figure03a.png">
82 <code>bgset(ba2, 16)
83 <code>ba3 = bgsubt(ba2)
84 <code>dotgraph(ba3, "Referenced SPR Data")
85 <img src="figure03b.png">
86 <code>dualgraph(ba2, ba3, "Unreferenced and Referenced SPR Data")
87 <img src="figure03c.png">
88 </pre>
89
90 Function <samp>calibrate()</samp> uses the data in <var>ba1</var> to calibrate the data in <var>ba1</var> and place it in a new object <var>ba2</var>.
91 The two-point calibration uses the time points (t1,t2) where the refractive indices (n1,n2) are known.
92 In this case, we use t1=2850s with n1=1333000 <i>&#181</i>RIU, and t2=3120 with n2=1334000.
93 Function <samp>bgset()</samp> is used to specify one ROI as the reference for all ROIs in the ba object.
94 In this case, ROI number 16 is used.
95 No data is affected by this step.
96 To apply background subtraction, we call the <samp>bgsubt()</samp> function.
97 This creates a new object <var>ba3</var>.
98 Function <samp>dotgraph()</samp> provides a slightly different display, with dotted data points instead of continuous lines.
99 Function <samp>dualgraph()</samp> displays both dotted and continuous sensorgrams.
100 This feature is useful for comparing two related Biosensor_array objects of the same size.
101
102 <h3>
103 Data simulation
104 </h3>
105 Now we will create some simulated sensorgrams using a simple 1:1 interaction model.
106 ...the model is a reference to a function...
107 ...the parameters are provided as a list of lists...
108
109 <pre>
110 <code>reset
111 <code>from osprai_one import *
112 <code>dpar = {}
113 <code>dpar['t1'] = dict(value=30.0, min=30.0, max=30.0, fixed='fixed')
114 <code>dpar['rmax'] = dict(value=100.0, min=1.0, max=1000.0, fixed='fixed')
115 <code>dpar['conc'] = dict(value=1e-5, min=1e-12, max=1e1, fixed='fixed')
116 <code>dpar['cofa'] = dict(value=1.0, min=1e-10, max=1e10, fixed='fixed')
117 <code>dpar['kon'] = dict(value=2e4, min=1e1, max=1e10, fixed='fixed')
118 <code>dpar['t2'] = dict(value=150.0, min=150.0, max=150.0, fixed='fixed')
119 <code>dpar['koff'] = dict(value=1e-2, min=1e-5, max=1e-1, fixed='fixed')
120 <code>dpar['t3'] = dict(value=270.0, min=270.0, max=270.0, fixed='fixed')
121 <code>print dpar
122 <kbd>{'cofa': {'fixed': 'fixed', 'max': 10000000000.0, 'min': 1e-010, 'value
123 'conc': {'fixed': 'fixed','max': 10.0,'min': 1.0e-012,'value': 1.0e-005},
124 'koff': {'fixed': 'fixed','max': 0.1,'min': 1.0e-005,'value': 0.01},
125 'kon': {'fixed': 'fixed','max': 10000000000.0,'min': 10.0,'value': 20000.0},
126 'rmax': {'fixed': 'fixed', 'max': 1000.0, 'min': 1.0, 'value': 100.0},
127 't1': {'fixed': 'fixed', 'max': 30.0, 'min': 30.0, 'value': 30.0},
128 't2': {'fixed': 'fixed', 'max': 150.0, 'min': 150.0, 'value': 150.0},
129 't3': {'fixed': 'fixed', 'max': 270.0, 'min': 270.0, 'value': 270.0}}</kbd>
130
131 <code>ba1 = BiosensorArray(3,300)
132 <code>for roi in ba1.roi:
133 <code> roi.time = arange(300, dtype=float) ## Samples every 1 second.
134 <code> roi.value = zeros(300, dtype=float) + 20 ## Baseline signal is 20 units.
135 <code> roi.params = deepcopy(dpar)
136 <code> roi.model = simple1to1
137 <code>ba1.roi[0].params['cofa']['value'] = 1.0 / 27
138 <code>ba1.roi[1].params['cofa']['value'] = 1.0 / 9
139 <code>ba1.roi[2].params['cofa']['value'] = 1.0 / 3
140 <code>for roi in ba1.roi:
141 <code> roi.value = roi.model(roi.time, roi.value, roi.params)
142 <code>dotgraph(ba1, "Simulation")
143 <img src="figure04.png">
144 </pre>
145
146
147 <h3>
148 Curve-fitting
149 </h3>
150 Osprai uses a modified version of the Levenberg-Marquardt least-squares algorithm (LMA) for fitting parameters.
151 The function <samp>mcmla()</samp> provides LMA fitting on multiple curves with constrained parameters.
152 The use of constraints can improve speed and eliminate nonsense solutions such as negative values for binding kinetic rate parameters.
153 In this example, we constrain the <var>rmax</var> parameter to deliberately produce incorrect <var>kon</var> and <var>koff</var> parameter results.
154
155 <pre>
156 <code>ba2 = deepcopy(ba1)
157 <code>ba2.roi[0].params['rmax'] = {'value':10.0, 'min':1.0, 'max':80.0, 'fixed':'float'}
158 <code>ba2.roi[0].params['kon']['fixed'] = 'float'
159 <code>ba2.roi[0].params['koff']['fixed'] = 'float'
160 <code>ba2.roi[1].params['rmax']['fixed'] = 0
161 <code>ba2.roi[1].params['kon']['fixed'] = 0
162 <code>ba2.roi[1].params['koff']['fixed'] = 0
163 <code>ba2.roi[2].params['rmax']['fixed'] = 0
164 <code>ba2.roi[2].params['kon']['fixed'] = 0
165 <code>ba2.roi[2].params['koff']['fixed'] = 0
166 <code>mclma(ba2.roi)
167 <kbd>0 koff 0.0100 kon 20000.0000 rmax 10.0000 1 2 ssq 1477505.8
168 0 koff 0.0100 kon 20000.0000 rmax 10.0000 1 2 ssq 1477505.8
169 0 koff 0.0100 kon 20000.0000 rmax 10.0000 1 2 ssq 1477505.8
170 0 koff 0.0100 kon 20000.0000 rmax 10.0000 1 2 ssq 1477505.8
171 0 koff 0.0100 kon 20000.0039 rmax 10.0000 1 2 ssq 1477505.8
172 0 koff 0.0100 kon 20000.0000 rmax 10.0000 1 2 ssq 1477505.8
173 0 koff 0.0100 kon 19999.9870 rmax 79.9923 1 2 ssq 73019.8
174 0 koff 0.0100 kon 19999.9870 rmax 79.9923 1 2 ssq 73019.8
175 0 koff 0.0100 kon 19999.9909 rmax 79.9923 1 2 ssq 73019.8
176 0 koff 0.0100 kon 19999.9870 rmax 79.9923 1 2 ssq 73019.8
177 0 koff 0.0081 kon 29949.8389 rmax 80.0000 1 2 ssq 23159.0
178 0 koff 0.0081 kon 29949.8389 rmax 80.0000 1 2 ssq 23159.0
179 0 koff 0.0081 kon 29949.8446 rmax 80.0000 1 2 ssq 23159.0
180 0 koff 0.0081 kon 29949.8389 rmax 80.0000 1 2 ssq 23159.0
181 0 koff 0.0081 kon 28038.4215 rmax 80.0000 1 2 ssq 22549.1
182 0 koff 0.0081 kon 28038.4215 rmax 80.0000 1 2 ssq 22549.1
183 0 koff 0.0081 kon 28038.4268 rmax 80.0000 1 2 ssq 22549.1
184 0 koff 0.0081 kon 28038.4215 rmax 80.0000 1 2 ssq 22549.1
185 0 koff 0.0081 kon 28217.6911 rmax 80.0000 1 2 ssq 22541.4
186 0 koff 0.0081 kon 28217.6911 rmax 80.0000 1 2 ssq 22541.4
187 0 koff 0.0081 kon 28217.6965 rmax 80.0000 1 2 ssq 22541.4
188 0 koff 0.0081 kon 28217.6911 rmax 80.0000 1 2 ssq 22541.4
189 0 koff 0.0081 kon 28196.8328 rmax 80.0000 1 2 ssq 22541.3
190 0 koff 0.0081 kon 28196.8328 rmax 80.0000 1 2 ssq 22541.3
191 0 koff 0.0081 kon 28196.8382 rmax 80.0000 1 2 ssq 22541.3
192 0 koff 0.0081 kon 28196.8328 rmax 80.0000 1 2 ssq 22541.3
193 0 koff 0.0081 kon 28199.1282 rmax 80.0000 1 2 ssq 22541.3
194 0 koff 0.0081 kon 28199.1282 rmax 80.0000 1 2 ssq 22541.3
195 0 koff 0.0081 kon 28199.1335 rmax 80.0000 1 2 ssq 22541.3
196 0 koff 0.0081 kon 28199.1282 rmax 80.0000 1 2 ssq 22541.3
197 0 koff 0.0081 kon 28198.8747 rmax 80.0000 1 2 ssq 22541.3</kbd>
198
199 <code>for roi in ba2.roi:
200 <code> roi.value = roi.model(roi.time, roi.value, roi.params)
201 <code>dualgraph(ba1, ba2, "Fitted Data with an incorrect rmax constraint")
202 <img src="figure05a.png">
203 </pre>
204
205 First, we make a copy of <var>ba1</var> using the <samp>deepcopy()</samp> function.
206 Next, we specify which parameters we wish to solve for by changing their 'fixed' key from 'fixed' to 'float'.
207 All three ROIs in this BA have the same model and the same parameters, so we only set the parameters in one of the ROIs to 'float'.
208 Here, we choose the the first ROI, <samp>roi[0]</samp>, and change 'fixed' to 'float' for 'rmax', 'kon', and 'koff' parameters.
209 In addition, we specify that 'rmax' will have a 'max' value of 80.0.
210 Next, we specify that the 'rmax', 'kon', and 'koff' values for <samp>roi[1]</samp> and <samp>roi[2]</samp> are the same as for <samp>roi[0]</samp>.
211 We do this by setting their 'fixed' key to 0, a reference to <samp>roi[0]</samp>.
212 <p>
213 We call the curve-fitting function with <samp>mclma(ba2.roi)</samp>
214 This function will print out the values of the floating parameters and the sum-squared error after each iteration.
215 After 30 iterations, in this case, the algorithm converges upon a solution.
216 Since 'rmax' was constrained to 80.0, with the real 'rmax' is 100.0, the resulting best-fit kon is found to be high (28000 vs. 20000).
217 We then use a <samp>for</samp> loop to simulate the three sensorgrams in <var>ba2</var> using the fitted parameters.
218 Last, we plot both the original sensorgrams of <var>ba1</var> and the fitted sensorgrams of <var>ba2</var> using the <samp>dualgraph()</samp> function.
219
220 <h3>
221 File format conversion
222 </h3>
223 Functions are provided to read and write several Biacore and Plexera file formats.
224 Optionally, microarray annotations can be added to the SPR data from GAL or Key files.
225 These annotations are saved when data files are written, if the file format provides support.
226 Examples are given below.
227
228 <pre>
229 <code>ba = readbiosensor("example-biosensor.txt")
230 <kbd>This Biosensor file has 9 datapoints for 2 ROIs.</kbd>
231 <code>ba = readicmtxt("example-icm.txt")
232 <kbd>This ICM file has 6034 datapoints for 25 ROIs.</kbd>
233 <code>ba = readsprit("example-sprit.txt")
234 <kbd>This SPRit file has 9 datapoints for 2 ROIs.</kbd>
235 <code>ba = applykey(ba1, "example-key.tsv")
236 <code>writesprit(ba,"testwritesprit.txt")
237 <code>writeclamp(ba,"testwriteclamp.txt")
238 <code>writebiosensor(ba, "testwritebiosensor.txt")
239 </pre>
240
241 <h3>
242 Online help.
243 </h3>
244 The Python <samp>help()</samp> function can be used at any time to display the online documentation for all Osprai functions and classes.
245
246 <pre>
247 <code>import osprai_one
248 <code>help(osprai_one)
249 <kbd>
250 Help on module osprai_one:
251
252 <b>NAME</b>
253 osprai_one
254
255 <b>FILE</b>
256 <i>( ...many pages of documentation follow... )</i>
257 </kbd>
258 <code>help(linegraph)
259 <kbd>
260 Help on function linegraph in module vu_module:
261
262 <b>linegraph</b>(baLine, title='')
263 Graph data of baLine using lines.
264 </kbd>
265 </pre>
266
267 <hr>
268 <i>
269 Written by Christopher Lausted <br>
270 16 August 2010 <br>
271 Institute for Systems Biology <br>
272 <small style="color:Gray">Tested in Firefox 3.6.8</small>
273 </i>
274
275 </html>
276
277
278
279 <!-- UNUSED MATERIAL---------------------------------------------------------
280
281
282 <pre>
283 print "Test of scatterplot using time points 500, 1000, 1500, 2000"
284 scatterplot(ba3, 3600, 4200, 3600, 4700, "Scatterplot")
285
286 print "Cutting out an interval..."
287 ba3 = copyinterval(ba3, 2800, 6200)
288 linegraph(ba3)
289 print "Done with test test_cal_module_vu_module."
290 return
291 </pre>
292
293
294 <p>
295 ...Mass transport limitation model example...
296
297 <pre>
298 from osprai_one import *
299 def demo_mtl():
300 print "Test the model module..."
301 ba0 = BiosensorArray(1,300) ## Create ba1 with one ROI and 300 datapoints.
302 roi0 = ba0.roi[0]
303 roi0.time = arange(300, dtype=float) ## Samples every 1 second.
304 roi0.value = zeros(300, dtype=float) + 20 ## Baseline signal is 20 units.
305 roi0.params = {'t1': {'value':30.0, 'min':30.0, 'max':30.0, 'fixed':True} }
306 roi0.params['rmax'] = {'value': 100.0}
307 roi0.params['conc'] = {'value': 1e-6}
308 roi0.params['kon'] = {'value': 5e4}
309 roi0.params['t2'] = {'value': 150.0}
310 roi0.params['koff'] = {'value': 5e-3}
311 roi0.params['t3'] = {'value': 270.0}
312 roi0.params['kmtl'] = {'value': 2e6}
313 roi0.name = "kmtl=2e6"
314 roi0.model = simple1to1_mtl
315 roi0.value =roi0.model(roi0.time, roi0.value, roi0.params)
316
317 ba1 = deepcopy(ba0)
318 roi0 = ba1.roi[0]
319 roi0.name = "No MTL"
320 roi0.model = simple1to1
321 roi0.value =roi0.model(roi0.time, roi0.value, roi0.params)
322 dualgraph(ba0, ba1, "With and without MTL")
323 print "Done with test demo_mtl."
324 </pre>
325
326 --------------------------------------------------- END OF DOCUMENTATION -->