1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 """The diffusion_tensor user function definitions."""
24
25
26 from graphics import WIZARD_IMAGE_PATH
27 from pipe_control import diffusion_tensor, pipes
28 from user_functions.data import Uf_info; uf_info = Uf_info()
29 from user_functions.objects import Desc_container
30
31
32
33 uf_class = uf_info.add_class('diffusion_tensor')
34 uf_class.title = "Class for manipulating the diffusion tensor."
35 uf_class.menu_text = "&diffusion_tensor"
36 uf_class.gui_icon = "relax.diff_tensor"
37
38
39
40 uf = uf_info.add_uf('diffusion_tensor.copy')
41 uf.title = "Copy diffusion tensor data from one data pipe to another."
42 uf.title_short = "Diffusion tensor data copying."
43 uf.add_keyarg(
44 name = "pipe_from",
45 basic_types = ["str"],
46 desc_short = "source data pipe",
47 desc = "The name of the data pipe to copy the diffusion tensor data from.",
48 wiz_element_type = 'combo',
49 wiz_combo_iter = pipes.pipe_names,
50 wiz_read_only = True,
51 can_be_none = True
52 )
53 uf.add_keyarg(
54 name = "pipe_to",
55 basic_types = ["str"],
56 desc_short = "destination data pipe",
57 desc = "The name of the data pipe to copy the diffusion tensor data to.",
58 wiz_element_type = 'combo',
59 wiz_combo_iter = pipes.pipe_names,
60 wiz_read_only = True,
61 can_be_none = True
62 )
63
64 uf.desc.append(Desc_container())
65 uf.desc[-1].add_paragraph("This will copy the diffusion tensor data between data pipes. The destination data pipe must not contain any diffusion tensor data. If the source or destination data pipes are not supplied, then both will default to the current data pipe (hence specifying at least one is essential).")
66
67 uf.desc.append(Desc_container("Prompt examples"))
68 uf.desc[-1].add_paragraph("To copy the diffusion tensor from the data pipe 'm1' to the current data pipe, type:")
69 uf.desc[-1].add_prompt("relax> diffusion_tensor.copy('m1')")
70 uf.desc[-1].add_prompt("relax> diffusion_tensor.copy(pipe_from='m1')")
71 uf.desc[-1].add_paragraph("To copy the diffusion tensor from the current data pipe to the data pipe 'm9', type:")
72 uf.desc[-1].add_prompt("relax> diffusion_tensor.copy(pipe_to='m9')")
73 uf.desc[-1].add_paragraph("To copy the diffusion tensor from the data pipe 'm1' to 'm2', type:")
74 uf.desc[-1].add_prompt("relax> diffusion_tensor.copy('m1', 'm2')")
75 uf.desc[-1].add_prompt("relax> diffusion_tensor.copy(pipe_from='m1', pipe_to='m2')")
76 uf.backend = diffusion_tensor.copy
77 uf.menu_text = "©"
78 uf.gui_icon = "oxygen.actions.list-add"
79 uf.wizard_size = (700, 500)
80 uf.wizard_image = WIZARD_IMAGE_PATH + 'diff_tensor.png'
81
82
83
84 uf = uf_info.add_uf('diffusion_tensor.delete')
85 uf.title = "Delete the diffusion tensor data from the relax data store."
86 uf.title_short = "Diffusion tensor data deletion."
87
88 uf.desc.append(Desc_container())
89 uf.desc[-1].add_paragraph("This will delete all diffusion tensor data from the current data pipe.")
90 uf.backend = diffusion_tensor.delete
91 uf.menu_text = "&delete"
92 uf.gui_icon = "oxygen.actions.list-remove"
93 uf.wizard_size = (600, 400)
94 uf.wizard_image = WIZARD_IMAGE_PATH + 'diff_tensor.png'
95
96
97
98 uf = uf_info.add_uf('diffusion_tensor.display')
99 uf.title = "Display the diffusion tensor information."
100 uf.title_short = "Diffusion tensor data display."
101 uf.display = True
102
103 uf.desc.append(Desc_container())
104 uf.desc[-1].add_paragraph("This will display all of the diffusion tensor information of the current data pipe.")
105 uf.backend = diffusion_tensor.display
106 uf.menu_text = "dis&play"
107 uf.gui_icon = "oxygen.actions.document-preview"
108 uf.wizard_size = (600, 400)
109 uf.wizard_image = WIZARD_IMAGE_PATH + 'diff_tensor.png'
110
111
112
113 uf = uf_info.add_uf('diffusion_tensor.init')
114 uf.title = "Initialise the diffusion tensor."
115 uf.title_short = "Diffusion tensor set up."
116 uf.add_keyarg(
117 name = "params",
118 basic_types = ["number"],
119 container_types = ["tuple"],
120 dim = [(), (4,), (6,)],
121 desc_short = "diffusion tensor parameters",
122 desc = "The diffusion tensor data.",
123 none_elements = True,
124 can_be_none = True
125 )
126 uf.add_keyarg(
127 name = "time_scale",
128 default = 1.0,
129 basic_types = ["number"],
130 desc_short = "time scale",
131 desc = "The correlation time scaling value."
132 )
133 uf.add_keyarg(
134 name = "d_scale",
135 default = 1.0,
136 basic_types = ["number"],
137 desc_short = "D scale",
138 desc = "The diffusion tensor eigenvalue scaling value."
139 )
140 uf.add_keyarg(
141 name = "angle_units",
142 default = "deg",
143 basic_types = ["str"],
144 desc_short = "angle units",
145 desc = "The units for the angle parameters."
146 )
147 uf.add_keyarg(
148 name = "param_types",
149 default = 0,
150 basic_types = ["int"],
151 desc_short = "parameter types",
152 desc = "A flag to select different parameter combinations."
153 )
154 uf.add_keyarg(
155 name = "spheroid_type",
156 basic_types = ["str"],
157 desc_short = "spheroid type",
158 desc = "A string which, if supplied together with spheroid parameters, will restrict the tensor to either being 'oblate' or 'prolate'.",
159 can_be_none = True
160 )
161 uf.add_keyarg(
162 name = "fixed",
163 default = True,
164 basic_types = ["bool"],
165 desc_short = "fixed flag",
166 desc = "A flag specifying whether the diffusion tensor is fixed or can be optimised."
167 )
168
169 uf.desc.append(Desc_container("The sphere (isotropic diffusion)"))
170 uf.desc[-1].add_paragraph("When the molecule diffuses as a sphere, all three eigenvalues of the diffusion tensor are equal, Dx = Dy = Dz. In this case, the orientation of the XH bond vector within the diffusion frame is inconsequential to relaxation, hence, the spherical or Euler angles are undefined. Therefore solely a single geometric parameter, either tm or Diso, can fully and sufficiently parameterise the diffusion tensor. The correlation function for the global rotational diffusion is")
171 uf.desc[-1].add_verbatim("""
172 1 - tau / tm
173 C(tau) = - e ,
174 5
175 """)
176 uf.desc[-1].add_paragraph("To select isotropic diffusion, the parameter should be a single floating point number. The number is the value of the isotropic global correlation time, tm, in seconds. To specify the time in nanoseconds, set the time scale to 1e-9. Alternative parameters can be used by changing the 'param_types' flag to the following integers")
177 uf.desc[-1].add_item_list_element("0", "{tm} (Default),")
178 uf.desc[-1].add_item_list_element("1", "{Diso},")
179 uf.desc[-1].add_paragraph("where")
180 uf.desc[-1].add_item_list_element(None, "1 / tm = 6Diso.")
181
182 uf.desc.append(Desc_container("The spheroid (axially symmetric diffusion)"))
183 uf.desc[-1].add_paragraph("When two of the three eigenvalues of the diffusion tensor are equal, the molecule diffuses as a spheroid. Four pieces of information are required to specify this tensor, the two geometric parameters, Diso and Da, and the two orientational parameters, the polar angle theta and the azimuthal angle phi describing the orientation of the axis of symmetry. The correlation function of the global diffusion is")
184 uf.desc[-1].add_verbatim("""
185 _1_
186 1 \ - tau / tau_i
187 C(tau) = - > ci . e ,
188 5 /__
189 i=-1
190 """)
191 uf.desc[-1].add_paragraph("where")
192 uf.desc[-1].add_item_list_element(None, "c-1 = 1/4 (3 dz^2 - 1)^2,")
193 uf.desc[-1].add_item_list_element(None, "c0 = 3 dz^2 (1 - dz^2),")
194 uf.desc[-1].add_item_list_element(None, "c1 = 3/4 (dz^2 - 1)^2,")
195 uf.desc[-1].add_paragraph("and")
196 uf.desc[-1].add_item_list_element(None, "1 / tau -1 = 6Diso - 2Da,")
197 uf.desc[-1].add_item_list_element(None, "1 / tau 0 = 6Diso - Da,")
198 uf.desc[-1].add_item_list_element(None, "1 / tau 1 = 6Diso + 2Da.")
199 uf.desc[-1].add_paragraph("The direction cosine dz is defined as the cosine of the angle alpha between the XH bond vector and the unique axis of the diffusion tensor.")
200 uf.desc[-1].add_paragraph("To select axially symmetric anisotropic diffusion, the parameters should be a tuple of floating point numbers of length four. A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas. Alternative sets of parameters, 'param_types', are")
201 uf.desc[-1].add_item_list_element("0", "{tm, Da, theta, phi} (Default),")
202 uf.desc[-1].add_item_list_element("1", "{Diso, Da, theta, phi},")
203 uf.desc[-1].add_item_list_element("2", "{tm, Dratio, theta, phi},")
204 uf.desc[-1].add_item_list_element("3", "{Dpar, Dper, theta, phi},")
205 uf.desc[-1].add_item_list_element("4", "{Diso, Dratio, theta, phi},")
206 uf.desc[-1].add_paragraph("where")
207 uf.desc[-1].add_item_list_element(None, "tm = 1 / 6Diso,")
208 uf.desc[-1].add_item_list_element(None, "Diso = 1/3 (Dpar + 2Dper),")
209 uf.desc[-1].add_item_list_element(None, "Da = Dpar - Dper,")
210 uf.desc[-1].add_item_list_element(None, "Dratio = Dpar / Dper.")
211 uf.desc[-1].add_paragraph("The spherical angles {theta, phi} orienting the unique axis of the diffusion tensor within the PDB frame are defined between")
212 uf.desc[-1].add_item_list_element(None, "0 <= theta <= pi,")
213 uf.desc[-1].add_item_list_element(None, "0 <= phi <= 2pi,")
214 uf.desc[-1].add_paragraph("while the angle alpha which is the angle between this axis and the given XH bond vector is defined between")
215 uf.desc[-1].add_item_list_element(None, "0 <= alpha <= 2pi.")
216 uf.desc[-1].add_paragraph("The spheroid type should be 'oblate', 'prolate', or None. This will be ignored if the diffusion tensor is not axially symmetric. If 'oblate' is given, then the constraint Da <= 0 is used while if 'prolate' is given, then the constraint Da >= 0 is used. If nothing is supplied, then Da will be allowed to have any values. To prevent minimisation of diffusion tensor parameters in a space with two minima, it is recommended to specify which tensor is to be minimised, thereby partitioning the two minima into the two subspaces along the boundary Da = 0.")
217
218 uf.desc.append(Desc_container("The ellipsoid (rhombic diffusion)"))
219 uf.desc[-1].add_paragraph("When all three eigenvalues of the diffusion tensor are different, the molecule diffuses as an ellipsoid. This diffusion is also known as fully anisotropic, asymmetric, or rhombic. The full tensor is specified by six pieces of information, the three geometric parameters Diso, Da, and Dr representing the isotropic, anisotropic, and rhombic components of the tensor, and the three Euler angles alpha, beta, and gamma orienting the tensor within the PDB frame. The correlation function is")
220 uf.desc[-1].add_verbatim("""
221 _2_
222 1 \ - tau / tau_i
223 C(tau) = - > ci . e ,
224 5 /__
225 i=-2
226 """)
227 uf.desc[-1].add_paragraph("where the weights on the exponentials are")
228 uf.desc[-1].add_item_list_element(None, "c-2 = 1/4 (d + e),")
229 uf.desc[-1].add_item_list_element(None, "c-1 = 3 dy^2 dz^2,")
230 uf.desc[-1].add_item_list_element(None, "c0 = 3 dx^2 dz^2,")
231 uf.desc[-1].add_item_list_element(None, "c1 = 3 dx^2 dy^2,")
232 uf.desc[-1].add_item_list_element(None, "c2 = 1/4 (d + e).")
233 uf.desc[-1].add_paragraph("Let")
234 uf.desc[-1].add_item_list_element(None, "R = sqrt(1 + 3Dr),")
235 uf.desc[-1].add_paragraph("then")
236 uf.desc[-1].add_item_list_element(None, "d = 3 (dx^4 + dy^4 + dz^4) - 1,")
237 uf.desc[-1].add_item_list_element(None, "e = - 1 / R ((1 + 3Dr)(dx^4 + 2dy^2 dz^2) + (1 - 3Dr)(dy^4 + 2dx^2 dz^2) - 2(dz^4 + 2dx^2 dy^2)).")
238 uf.desc[-1].add_paragraph("The correlation times are")
239 uf.desc[-1].add_item_list_element(None, "1 / tau -2 = 6Diso - 2Da . R,")
240 uf.desc[-1].add_item_list_element(None, "1 / tau -1 = 6Diso - Da (1 + 3Dr),")
241 uf.desc[-1].add_item_list_element(None, "1 / tau 0 = 6Diso - Da (1 - 3Dr),")
242 uf.desc[-1].add_item_list_element(None, "1 / tau 1 = 6Diso + 2Da,")
243 uf.desc[-1].add_item_list_element(None, "1 / tau 1 = 6Diso + 2Da . R.")
244 uf.desc[-1].add_paragraph("The three direction cosines dx, dy, and dz are the coordinates of a unit vector parallel to the XH bond vector. Hence the unit vector is [dx, dy, dz].")
245 uf.desc[-1].add_paragraph("To select fully anisotropic diffusion, the parameters should be a tuple of length six. A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas. Alternative sets of parameters, 'param_types', are")
246 uf.desc[-1].add_item_list_element("0", "{tm, Da, Dr, alpha, beta, gamma} (Default),")
247 uf.desc[-1].add_item_list_element("1", "{Diso, Da, Dr, alpha, beta, gamma},")
248 uf.desc[-1].add_item_list_element("2", "{Dx, Dy, Dz, alpha, beta, gamma},")
249 uf.desc[-1].add_item_list_element("3", "{Dxx, Dyy, Dzz, Dxy, Dxz, Dyz},")
250 uf.desc[-1].add_paragraph("where")
251 uf.desc[-1].add_item_list_element(None, "tm = 1 / 6Diso,")
252 uf.desc[-1].add_item_list_element(None, "Diso = 1/3 (Dx + Dy + Dz),")
253 uf.desc[-1].add_item_list_element(None, "Da = Dz - (Dx + Dy)/2,")
254 uf.desc[-1].add_item_list_element(None, "Dr = (Dy - Dx)/2Da.")
255 uf.desc[-1].add_paragraph("The angles alpha, beta, and gamma are the Euler angles describing the diffusion tensor within the PDB frame. These angles are defined using the z-y-z axis rotation notation where alpha is the initial rotation angle around the z-axis, beta is the rotation angle around the y-axis, and gamma is the final rotation around the z-axis again. The angles are defined between")
256 uf.desc[-1].add_item_list_element(None, "0 <= alpha <= 2pi,")
257 uf.desc[-1].add_item_list_element(None, "0 <= beta <= pi,")
258 uf.desc[-1].add_item_list_element(None, "0 <= gamma <= 2pi.")
259 uf.desc[-1].add_paragraph("Within the PDB frame, the XH bond vector is described using the spherical angles theta and phi where theta is the polar angle and phi is the azimuthal angle defined between")
260 uf.desc[-1].add_item_list_element(None, "0 <= theta <= pi,")
261 uf.desc[-1].add_item_list_element(None, "0 <= phi <= 2pi.")
262 uf.desc[-1].add_paragraph("When param_types is set to 3, then the elements of the diffusion tensor matrix defined within the PDB frame can be supplied.")
263
264 uf.desc.append(Desc_container("Units"))
265 uf.desc[-1].add_paragraph("The correlation time scaling value should be a floating point number. The only parameter affected by this value is tm.")
266 uf.desc[-1].add_paragraph("The diffusion tensor eigenvalue scaling value should also be a floating point number. Parameters affected by this value are Diso, Dpar, Dper, Da, Dx, Dy, and Dz. Significantly, Dr is not affected.")
267 uf.desc[-1].add_paragraph("The units for the angle parameters should be either 'deg' or 'rad'. Parameters affected are theta, phi, alpha, beta, and gamma.")
268
269 uf.desc.append(Desc_container("Prompt examples"))
270 uf.desc[-1].add_paragraph("To set an isotropic diffusion tensor with a correlation time of 10 ns, type:")
271 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(10e-9)")
272 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=10e-9)")
273 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(10.0, 1e-9)")
274 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=10.0, time_scale=1e-9, fixed=True)")
275 uf.desc[-1].add_paragraph("To select axially symmetric diffusion with a tm value of 8.5 ns, Dratio of 1.1, theta value of 20 degrees, and phi value of 20 degrees, type:")
276 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((8.5e-9, 1.1, 20.0, 20.0), param_types=2)")
277 uf.desc[-1].add_paragraph("To select a spheroid diffusion tensor with a Dpar value of 1.698e7, Dper value of 1.417e7, theta value of 67.174 degrees, and phi value of -83.718 degrees, type one of:")
278 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((1.698e7, 1.417e7, 67.174, -83.718), param_types=3)")
279 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=(1.698e7, 1.417e7, 67.174, -83.718), param_types=3)")
280 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((1.698e-1, 1.417e-1, 67.174, -83.718), param_types=3, d_scale=1e8)")
281 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=(1.698e-1, 1.417e-1, 67.174, -83.718), param_types=3, d_scale=1e8)")
282 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=3, d_scale=1e8, angle_units='rad')")
283 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=(1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=3, d_scale=1e8, angle_units='rad', fixed=True)")
284 uf.desc[-1].add_paragraph("To select ellipsoidal diffusion, type:")
285 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((1.340e7, 1.516e7, 1.691e7, -82.027, -80.573, 65.568), param_types=2)")
286 uf.backend = diffusion_tensor.init
287 uf.menu_text = "&init"
288 uf.gui_icon = "relax.diff_tensor"
289 uf.wizard_size = (1000, 750)
290 uf.wizard_height_desc = 400
291 uf.wizard_image = WIZARD_IMAGE_PATH + 'diff_tensor.png'
292