ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/osprai/osprai/trunk/sphinx/tutorial01.rst
Revision: 45
Committed: Thu Feb 3 02:52:40 2011 UTC (8 years, 11 months ago) by clausted
File size: 11617 byte(s)
Log Message:
Create a reST version of the tutorial, called tutorial01.rst, based on a html version.  Add a reference to it in index.rst. 
Line File contents
1 .. Osprai tutorial #1
2 Chris Lausted 110202
3
4 =================
5 OSPRAI Tutorial 1
6 =================
7
8 Viewing data from an SPR file
9 -----------------------------
10
11 Analysis begins with viewing data generated by a biosensor instrument such as a Biacore or Plexera.
12 Launch a python interpreter such as the standard interpreter or IPython and navigate to the directory containing the OSPRAI code and example data files.
13 Enter the following commands to load and view an example data file.
14
15 .. parsed-literal::
16
17 >>> from osprai_one import *
18 >>> ba1 = readicmtxt("example-icm.txt")
19 This ICM files has 6034 datapoints for 25 ROIs.
20 >>> linegraph(ba1)
21
22 .. image:: ./images/figure02.png
23
24 The first line imports all of the functions and data classes needed by the user.
25 Function ``readicmtxt()`` reads an SPR data file saved by the Plexera Instrument Control Software.
26 Other data formats are supported and described later.
27 A object of the class Biosensor_array (BA) is created named ``ba1`` containing the data.
28
29 Function ``linegraph()`` plots the data as a sensorgram--the SPR signal versus time.
30 This plot appears in a separate window.
31 At the lower left corner of the window are buttons for zooming, copying, and saving (PNG format).
32 These buttons will be familiar to matplotlib users.
33 At the lower right corner are three buttons for changing which ROIs are displayed.
34 While it is possible to display all ROIs in a BA object, a plot with 25 ROIs would be too cluttered.
35 By default, only the first six ROIs in the BA are shown.
36 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.
37 An arbitrary list of ROIs can be specified by clicking the "Choose..." button.
38 The window must be closed in order to continue the execution of Osparai commands
39
40 Calibration and background subtraction
41 --------------------------------------
42
43 Data produced by a biosensing instrument can be reported as angle shift, reflectance, wavelength shift, resonance units (RU), or other units.
44 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.
45 The example file used here is uncalibrated and unreferenced.
46 Enter the following commands for calibration and referencing.
47
48 .. parsed-literal::
49
50 >>> ba2 = calibrate(ba1, ba1, 2850, 3120, 1333000, 1334000)
51 >>> linegraph(ba2, "Calibrated SPR Data")
52 .. image:: ./images/figure03a.png"
53 >>> bgset(ba2, 16)
54 >>> ba3 = bgsubt(ba2)
55 >>> dotgraph(ba3, "Referenced SPR Data")
56
57 .. image:: ./images/figure03b.png
58
59 .. parsed-literal::
60
61 >>> dualgraph(ba2, ba3, "Unreferenced and Referenced SPR Data")
62
63 .. image:: ./images/figure03c.png
64
65 Function ``calibrate()`` uses the data in ``ba1`` to calibrate the data in ``ba1`` and place it in a new object ``ba2``.
66 The two-point calibration uses the time points (t1,t2) where the refractive indices (n1,n2) are known.
67 In this case, we use t1=2850s with n1=1333000 <i>&#181</i>RIU, and t2=3120 with n2=1334000.
68 Function ``bgset()`` is used to specify one ROI as the reference for all ROIs in the ba object.
69 In this case, ROI number 16 is used.
70 No data is affected by this step.
71 To apply background subtraction, we call the ``bgsubt()`` function.
72 This creates a new object ``ba3``.
73 Function ``dotgraph()`` provides a slightly different display, with dotted data points instead of continuous lines.
74 Function ``dualgraph()`` displays both dotted and continuous sensorgrams.
75 This feature is useful for comparing two related Biosensor_array objects of the same size.
76
77 Data simulation
78 ---------------
79
80 Now we will create some simulated sensorgrams using a simple 1:1 interaction model.
81 ...the model is a reference to a function...
82 ...the parameters are provided as a list of lists...
83
84 .. parsed-literal::
85
86 >>> reset
87 >>> from osprai_one import *
88 >>> dpar = {}
89 >>> dpar['t1'] = dict(value=30.0, min=30.0, max=30.0, fixed='fixed')
90 >>> dpar['rmax'] = dict(value=100.0, min=1.0, max=1000.0, fixed='fixed')
91 >>> dpar['conc'] = dict(value=1e-5, min=1e-12, max=1e1, fixed='fixed')
92 >>> dpar['cofa'] = dict(value=1.0, min=1e-10, max=1e10, fixed='fixed')
93 >>> dpar['kon'] = dict(value=2e4, min=1e1, max=1e10, fixed='fixed')
94 >>> dpar['t2'] = dict(value=150.0, min=150.0, max=150.0, fixed='fixed')
95 >>> dpar['koff'] = dict(value=1e-2, min=1e-5, max=1e-1, fixed='fixed')
96 >>> dpar['t3'] = dict(value=270.0, min=270.0, max=270.0, fixed='fixed')
97 >>> print dpar
98 {'cofa': {'fixed': 'fixed', 'max': 10000000000.0, 'min': 1e-010, 'value
99 'conc': {'fixed': 'fixed','max': 10.0,'min': 1.0e-012,'value': 1.0e-005},
100 'koff': {'fixed': 'fixed','max': 0.1,'min': 1.0e-005,'value': 0.01},
101 'kon': {'fixed': 'fixed','max': 10000000000.0,'min': 10.0,'value': 20000.0},
102 'rmax': {'fixed': 'fixed', 'max': 1000.0, 'min': 1.0, 'value': 100.0},
103 't1': {'fixed': 'fixed', 'max': 30.0, 'min': 30.0, 'value': 30.0},
104 't2': {'fixed': 'fixed', 'max': 150.0, 'min': 150.0, 'value': 150.0},
105 't3': {'fixed': 'fixed', 'max': 270.0, 'min': 270.0, 'value': 270.0}}
106 >>>
107 >>> ba1 = BiosensorArray(3,300)
108 >>> for roi in ba1.roi:
109 >>> roi.time = arange(300, dtype=float) ## Samples every 1 second.
110 >>> roi.value = zeros(300, dtype=float) + 20 ## Baseline signal is 20 units.
111 >>> roi.params = deepcopy(dpar)
112 >>> roi.model = simple1to1
113 >>> ba1.roi[0].params['cofa']['value'] = 1.0 / 27
114 >>> ba1.roi[1].params['cofa']['value'] = 1.0 / 9
115 >>> ba1.roi[2].params['cofa']['value'] = 1.0 / 3
116 >>> for roi in ba1.roi:
117 >>> roi.value = roi.model(roi.time, roi.value, roi.params)
118 >>> dotgraph(ba1, "Simulation")
119
120 .. image:: ./images/figure04.png
121
122
123 Curve-fitting
124 -------------
125
126 Osprai uses a modified version of the Levenberg-Marquardt least-squares algorithm (LMA) for fitting parameters.
127 The function ``mcmla()`` provides LMA fitting on multiple curves with constrained parameters.
128 The use of constraints can improve speed and eliminate nonsense solutions such as negative values for binding kinetic rate parameters.
129 In this example, we constrain the ``rmax`` parameter to deliberately produce incorrect ``kon`` and ``koff`` parameter results.
130
131 .. parsed-literal::
132
133 >>> ba2 = deepcopy(ba1)
134 >>> ba2.roi[0].params['rmax'] = {'value':10.0, 'min':1.0, 'max':80.0, 'fixed':'float'}
135 >>> ba2.roi[0].params['kon']['fixed'] = 'float'
136 >>> ba2.roi[0].params['koff']['fixed'] = 'float'
137 >>> ba2.roi[1].params['rmax']['fixed'] = 0
138 >>> ba2.roi[1].params['kon']['fixed'] = 0
139 >>> ba2.roi[1].params['koff']['fixed'] = 0
140 >>> ba2.roi[2].params['rmax']['fixed'] = 0
141 >>> ba2.roi[2].params['kon']['fixed'] = 0
142 >>> ba2.roi[2].params['koff']['fixed'] = 0
143 >>> mclma(ba2.roi)
144 ... 0 koff 0.0100 kon 20000.0000 rmax 10.0000 1 2 ssq 1477505.8
145 0 koff 0.0100 kon 20000.0000 rmax 10.0000 1 2 ssq 1477505.8
146 0 koff 0.0100 kon 20000.0000 rmax 10.0000 1 2 ssq 1477505.8
147 0 koff 0.0100 kon 20000.0000 rmax 10.0000 1 2 ssq 1477505.8
148 0 koff 0.0100 kon 20000.0039 rmax 10.0000 1 2 ssq 1477505.8
149 0 koff 0.0100 kon 20000.0000 rmax 10.0000 1 2 ssq 1477505.8
150 0 koff 0.0100 kon 19999.9870 rmax 79.9923 1 2 ssq 73019.8
151 0 koff 0.0100 kon 19999.9870 rmax 79.9923 1 2 ssq 73019.8
152 0 koff 0.0100 kon 19999.9909 rmax 79.9923 1 2 ssq 73019.8
153 0 koff 0.0100 kon 19999.9870 rmax 79.9923 1 2 ssq 73019.8
154 0 koff 0.0081 kon 29949.8389 rmax 80.0000 1 2 ssq 23159.0
155 0 koff 0.0081 kon 29949.8389 rmax 80.0000 1 2 ssq 23159.0
156 0 koff 0.0081 kon 29949.8446 rmax 80.0000 1 2 ssq 23159.0
157 0 koff 0.0081 kon 29949.8389 rmax 80.0000 1 2 ssq 23159.0
158 0 koff 0.0081 kon 28038.4215 rmax 80.0000 1 2 ssq 22549.1
159 0 koff 0.0081 kon 28038.4215 rmax 80.0000 1 2 ssq 22549.1
160 0 koff 0.0081 kon 28038.4268 rmax 80.0000 1 2 ssq 22549.1
161 0 koff 0.0081 kon 28038.4215 rmax 80.0000 1 2 ssq 22549.1
162 0 koff 0.0081 kon 28217.6911 rmax 80.0000 1 2 ssq 22541.4
163 0 koff 0.0081 kon 28217.6911 rmax 80.0000 1 2 ssq 22541.4
164 0 koff 0.0081 kon 28217.6965 rmax 80.0000 1 2 ssq 22541.4
165 0 koff 0.0081 kon 28217.6911 rmax 80.0000 1 2 ssq 22541.4
166 0 koff 0.0081 kon 28196.8328 rmax 80.0000 1 2 ssq 22541.3
167 0 koff 0.0081 kon 28196.8328 rmax 80.0000 1 2 ssq 22541.3
168 0 koff 0.0081 kon 28196.8382 rmax 80.0000 1 2 ssq 22541.3
169 0 koff 0.0081 kon 28196.8328 rmax 80.0000 1 2 ssq 22541.3
170 0 koff 0.0081 kon 28199.1282 rmax 80.0000 1 2 ssq 22541.3
171 0 koff 0.0081 kon 28199.1282 rmax 80.0000 1 2 ssq 22541.3
172 0 koff 0.0081 kon 28199.1335 rmax 80.0000 1 2 ssq 22541.3
173 0 koff 0.0081 kon 28199.1282 rmax 80.0000 1 2 ssq 22541.3
174 0 koff 0.0081 kon 28198.8747 rmax 80.0000 1 2 ssq 22541.3
175
176 >>> for roi in ba2.roi:
177 >>> roi.value = roi.model(roi.time, roi.value, roi.params)
178 >>> dualgraph(ba1, ba2, "Fitted Data with an incorrect rmax constraint")
179
180 .. image:: ./images/figure05a.png
181
182 First, we make a copy of ``ba1`` using the ``deepcopy()`` function.
183 Next, we specify which parameters we wish to solve for by changing their 'fixed' key from 'fixed' to 'float'.
184 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'.
185 Here, we choose the the first ROI, ``roi[0]``, and change 'fixed' to 'float' for 'rmax', 'kon', and 'koff' parameters.
186 In addition, we specify that 'rmax' will have a 'max' value of 80.0.
187 Next, we specify that the 'rmax', 'kon', and 'koff' values for ``roi[1]`` and ``roi[2]`` are the same as for ``roi[0]``.
188 We do this by setting their 'fixed' key to 0, a reference to ``roi[0]``.
189
190 We call the curve-fitting function with ``mclma(ba2.roi)``
191 This function will print out the values of the floating parameters and the sum-squared error after each iteration.
192 After 30 iterations, in this case, the algorithm converges upon a solution.
193 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).
194 We then use a ``for`` loop to simulate the three sensorgrams in ``ba2`` using the fitted parameters.
195 Last, we plot both the original sensorgrams of ``ba1`` and the fitted sensorgrams of ``ba2`` using the ``dualgraph()`` function.
196
197
198 File format conversion
199 ----------------------
200
201 Functions are provided to read and write several Biacore and Plexera file formats.
202 Optionally, microarray annotations can be added to the SPR data from GAL or Key files.
203 These annotations are saved when data files are written, if the file format provides support.
204 Examples are given below.
205
206 .. parsed-literal::
207
208 >>> ba = readbiosensor("example-biosensor.txt")
209 This Biosensor file has 9 datapoints for 2 ROIs.
210 >>> ba = readicmtxt("example-icm.txt")
211 This ICM file has 6034 datapoints for 25 ROIs.
212 >>> ba = readsprit("example-sprit.txt")
213 This SPRit file has 9 datapoints for 2 ROIs.
214 >>> ba = applykey(ba1, "example-key.tsv")
215 >>> writesprit(ba,"testwritesprit.txt")
216 >>> writeclamp(ba,"testwriteclamp.txt")
217 >>> writebiosensor(ba, "testwritebiosensor.txt")
218
219
220
221 Online help
222 -----------
223 The Python ``help()`` function can be used at any time to display the online documentation for all Osprai functions and classes.
224
225 .. parsed-literal::
226
227 >>> import osprai_one
228 >>> help(osprai_one)
229
230 Help on module osprai_one:
231
232 **NAME**
233 osprai_one
234
235 **FILE**
236 *( ...many pages of documentation follow... )*
237
238 >>> help(linegraph)
239
240 Help on function linegraph in module vu_module:
241
242 **linegraph**(baLine, title='')
243 Graph data of baLine using lines.