ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/osprai/osprai/trunk/help/osprai-doc.html
Revision: 34
Committed: Sat Jul 31 00:08:34 2010 UTC (9 years, 6 months ago) by clausted
File size: 13773 byte(s)
Log Message:
Use CSS numbering to simulated the IPython prompt in the documentation. Added benefit: User can now select code in web browser and paste it into IPython--the prompt is left off.
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 Svn, RapidSVN, or TortoiseSVN.
30 Windows users can install all of the necessary prerequisites by installing PythonXY (link), 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 <p>
220 ...Mass transport limitation model example...
221
222 <pre>
223 from osprai_one import *
224 def demo_mtl():
225 print "Test the model module..."
226 ba0 = BiosensorArray(1,300) ## Create ba1 with one ROI and 300 datapoints.
227 roi0 = ba0.roi[0]
228 roi0.time = arange(300, dtype=float) ## Samples every 1 second.
229 roi0.value = zeros(300, dtype=float) + 20 ## Baseline signal is 20 units.
230 roi0.params = {'t1': {'value':30.0, 'min':30.0, 'max':30.0, 'fixed':True} }
231 roi0.params['rmax'] = {'value': 100.0}
232 roi0.params['conc'] = {'value': 1e-6}
233 roi0.params['kon'] = {'value': 5e4}
234 roi0.params['t2'] = {'value': 150.0}
235 roi0.params['koff'] = {'value': 5e-3}
236 roi0.params['t3'] = {'value': 270.0}
237 roi0.params['kmtl'] = {'value': 2e6}
238 roi0.name = "kmtl=2e6"
239 roi0.model = simple1to1_mtl
240 roi0.value =roi0.model(roi0.time, roi0.value, roi0.params)
241
242 ba1 = deepcopy(ba0)
243 roi0 = ba1.roi[0]
244 roi0.name = "No MTL"
245 roi0.model = simple1to1
246 roi0.value =roi0.model(roi0.time, roi0.value, roi0.params)
247 dualgraph(ba0, ba1, "With and without MTL")
248 print "Done with test demo_mtl."
249 </pre>
250
251
252 <h3>
253 File format conversion
254 </h3>
255 ...examples of formats...
256
257 <pre>
258 print "Test of scatterplot using time points 500, 1000, 1500, 2000"
259 scatterplot(ba3, 3600, 4200, 3600, 4700, "Scatterplot")
260
261 print "Cutting out an interval..."
262 ba3 = copyinterval(ba3, 2800, 6200)
263 linegraph(ba3)
264 print "Done with test test_cal_module_vu_module."
265 return
266 </pre>
267
268 <pre>
269 from osprai_one import *
270 print "Loading SPR data files..."
271 ba1 = readbiosensor("example-biosensor.txt")
272 ba1 = readicmtxt("example-icm.txt")
273 ba1 = readsprit("example-sprit.txt")
274 ba1 = applykey(ba1, "example-key.tsv")
275 print "Writing SPR data files..."
276 writesprit(ba1,"testwritesprit.txt")
277 writeclamp(ba1,"testwriteclamp.txt")
278 writebiosensor(ba1, "testwritebiosensor.txt")
279 print "Done with test_io_module."
280 </pre>
281
282 <hr>
283 <i>
284 Written by Christopher Lausted <br>
285 30 July 2010 <br>
286 Institute for Systems Biology <br>
287 <small style="color:Gray">Tested in Firefox 3.6.8</small>
288 </i>
289
290 </html>