1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24 """The diffusion_tensor user function definitions."""
25
26
27 from generic_fns import diffusion_tensor, pipes
28 from graphics import WIZARD_IMAGE_PATH
29 from user_functions.data import Uf_info; uf_info = Uf_info()
30 from user_functions.objects import Desc_container
31
32
33
34 uf_class = uf_info.add_class('diffusion_tensor')
35 uf_class.title = "Class for manipulating the diffusion tensor."
36 uf_class.menu_text = "&diffusion_tensor"
37 uf_class.gui_icon = "relax.diff_tensor"
38
39
40
41 uf = uf_info.add_uf('diffusion_tensor.copy')
42 uf.title = "Copy diffusion tensor data from one data pipe to another."
43 uf.title_short = "Diffusion tensor data copying."
44 uf.add_keyarg(
45 name = "pipe_from",
46 py_type = "str",
47 desc_short = "source data pipe",
48 desc = "The name of the data pipe to copy the diffusion tensor data from.",
49 wiz_element_type = 'combo',
50 wiz_combo_iter = pipes.pipe_names,
51 wiz_read_only = True,
52 can_be_none = True
53 )
54 uf.add_keyarg(
55 name = "pipe_to",
56 py_type = "str",
57 desc_short = "destination data pipe",
58 desc = "The name of the data pipe to copy the diffusion tensor data to.",
59 wiz_element_type = 'combo',
60 wiz_combo_iter = pipes.pipe_names,
61 wiz_read_only = True,
62 can_be_none = True
63 )
64
65 uf.desc.append(Desc_container())
66 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).")
67
68 uf.desc.append(Desc_container("Prompt examples"))
69 uf.desc[-1].add_paragraph("To copy the diffusion tensor from the data pipe 'm1' to the current data pipe, type:")
70 uf.desc[-1].add_prompt("relax> diffusion_tensor.copy('m1')")
71 uf.desc[-1].add_prompt("relax> diffusion_tensor.copy(pipe_from='m1')")
72 uf.desc[-1].add_paragraph("To copy the diffusion tensor from the current data pipe to the data pipe 'm9', type:")
73 uf.desc[-1].add_prompt("relax> diffusion_tensor.copy(pipe_to='m9')")
74 uf.desc[-1].add_paragraph("To copy the diffusion tensor from the data pipe 'm1' to 'm2', type:")
75 uf.desc[-1].add_prompt("relax> diffusion_tensor.copy('m1', 'm2')")
76 uf.desc[-1].add_prompt("relax> diffusion_tensor.copy(pipe_from='m1', pipe_to='m2')")
77 uf.backend = diffusion_tensor.copy
78 uf.menu_text = "©"
79 uf.gui_icon = "oxygen.actions.list-add"
80 uf.wizard_size = (700, 500)
81 uf.wizard_image = WIZARD_IMAGE_PATH + 'diff_tensor.png'
82
83
84
85 uf = uf_info.add_uf('diffusion_tensor.delete')
86 uf.title = "Delete the diffusion tensor data from the relax data store."
87 uf.title_short = "Diffusion tensor data deletion."
88
89 uf.desc.append(Desc_container())
90 uf.desc[-1].add_paragraph("This will delete all diffusion tensor data from the current data pipe.")
91 uf.backend = diffusion_tensor.delete
92 uf.menu_text = "&delete"
93 uf.gui_icon = "oxygen.actions.list-remove"
94 uf.wizard_size = (600, 400)
95 uf.wizard_image = WIZARD_IMAGE_PATH + 'diff_tensor.png'
96
97
98
99 uf = uf_info.add_uf('diffusion_tensor.display')
100 uf.title = "Display the diffusion tensor information."
101 uf.title_short = "Diffusion tensor data display."
102 uf.display = True
103
104 uf.desc.append(Desc_container())
105 uf.desc[-1].add_paragraph("This will display all of the diffusion tensor information of the current data pipe.")
106 uf.backend = diffusion_tensor.display
107 uf.menu_text = "dis&play"
108 uf.gui_icon = "oxygen.actions.document-preview"
109 uf.wizard_size = (600, 400)
110 uf.wizard_image = WIZARD_IMAGE_PATH + 'diff_tensor.png'
111
112
113
114 uf = uf_info.add_uf('diffusion_tensor.init')
115 uf.title = "Initialise the diffusion tensor."
116 uf.title_short = "Diffusion tensor set up."
117 uf.add_keyarg(
118 name = "params",
119 py_type = "num_or_num_tuple",
120 dim = [4, 6],
121 desc_short = "diffusion tensor parameters",
122 desc = "The diffusion tensor data."
123 )
124 uf.add_keyarg(
125 name = "time_scale",
126 default = 1.0,
127 py_type = "num",
128 desc_short = "time scale",
129 desc = "The correlation time scaling value."
130 )
131 uf.add_keyarg(
132 name = "d_scale",
133 default = 1.0,
134 py_type = "num",
135 desc_short = "D scale",
136 desc = "The diffusion tensor eigenvalue scaling value."
137 )
138 uf.add_keyarg(
139 name = "angle_units",
140 default = "deg",
141 py_type = "str",
142 desc_short = "angle units",
143 desc = "The units for the angle parameters."
144 )
145 uf.add_keyarg(
146 name = "param_types",
147 default = 0,
148 py_type = "int",
149 desc_short = "parameter types",
150 desc = "A flag to select different parameter combinations."
151 )
152 uf.add_keyarg(
153 name = "spheroid_type",
154 py_type = "str",
155 desc_short = "spheroid type",
156 desc = "A string which, if supplied together with spheroid parameters, will restrict the tensor to either being 'oblate' or 'prolate'.",
157 can_be_none = True
158 )
159 uf.add_keyarg(
160 name = "fixed",
161 default = True,
162 py_type = "bool",
163 desc_short = "fixed flag",
164 desc = "A flag specifying whether the diffusion tensor is fixed or can be optimised."
165 )
166
167 uf.desc.append(Desc_container("The sphere (isotropic diffusion)"))
168 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")
169 uf.desc[-1].add_verbatim("""
170 1 - tau / tm
171 C(tau) = - e ,
172 5
173 """)
174 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")
175 uf.desc[-1].add_item_list_element("0", "{tm} (Default),")
176 uf.desc[-1].add_item_list_element("1", "{Diso},")
177 uf.desc[-1].add_paragraph("where")
178 uf.desc[-1].add_item_list_element(None, "1 / tm = 6Diso.")
179
180 uf.desc.append(Desc_container("The spheroid (axially symmetric diffusion)"))
181 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")
182 uf.desc[-1].add_verbatim("""
183 _1_
184 1 \ - tau / tau_i
185 C(tau) = - > ci . e ,
186 5 /__
187 i=-1
188 """)
189 uf.desc[-1].add_paragraph("where")
190 uf.desc[-1].add_item_list_element(None, "c-1 = 1/4 (3 dz^2 - 1)^2,")
191 uf.desc[-1].add_item_list_element(None, "c0 = 3 dz^2 (1 - dz^2),")
192 uf.desc[-1].add_item_list_element(None, "c1 = 3/4 (dz^2 - 1)^2,")
193 uf.desc[-1].add_paragraph("and")
194 uf.desc[-1].add_item_list_element(None, "1 / tau -1 = 6Diso - 2Da,")
195 uf.desc[-1].add_item_list_element(None, "1 / tau 0 = 6Diso - Da,")
196 uf.desc[-1].add_item_list_element(None, "1 / tau 1 = 6Diso + 2Da.")
197 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.")
198 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")
199 uf.desc[-1].add_item_list_element("0", "{tm, Da, theta, phi} (Default),")
200 uf.desc[-1].add_item_list_element("1", "{Diso, Da, theta, phi},")
201 uf.desc[-1].add_item_list_element("2", "{tm, Dratio, theta, phi},")
202 uf.desc[-1].add_item_list_element("3", "{Dpar, Dper, theta, phi},")
203 uf.desc[-1].add_item_list_element("4", "{Diso, Dratio, theta, phi},")
204 uf.desc[-1].add_paragraph("where")
205 uf.desc[-1].add_item_list_element(None, "tm = 1 / 6Diso,")
206 uf.desc[-1].add_item_list_element(None, "Diso = 1/3 (Dpar + 2Dper),")
207 uf.desc[-1].add_item_list_element(None, "Da = Dpar - Dper,")
208 uf.desc[-1].add_item_list_element(None, "Dratio = Dpar / Dper.")
209 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")
210 uf.desc[-1].add_item_list_element(None, "0 <= theta <= pi,")
211 uf.desc[-1].add_item_list_element(None, "0 <= phi <= 2pi,")
212 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")
213 uf.desc[-1].add_item_list_element(None, "0 <= alpha <= 2pi.")
214 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.")
215
216 uf.desc.append(Desc_container("The ellipsoid (rhombic diffusion)"))
217 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")
218 uf.desc[-1].add_verbatim("""
219 _2_
220 1 \ - tau / tau_i
221 C(tau) = - > ci . e ,
222 5 /__
223 i=-2
224 """)
225 uf.desc[-1].add_paragraph("where the weights on the exponentials are")
226 uf.desc[-1].add_item_list_element(None, "c-2 = 1/4 (d + e),")
227 uf.desc[-1].add_item_list_element(None, "c-1 = 3 dy^2 dz^2,")
228 uf.desc[-1].add_item_list_element(None, "c0 = 3 dx^2 dz^2,")
229 uf.desc[-1].add_item_list_element(None, "c1 = 3 dx^2 dy^2,")
230 uf.desc[-1].add_item_list_element(None, "c2 = 1/4 (d + e).")
231 uf.desc[-1].add_paragraph("Let")
232 uf.desc[-1].add_item_list_element(None, "R = sqrt(1 + 3Dr),")
233 uf.desc[-1].add_paragraph("then")
234 uf.desc[-1].add_item_list_element(None, "d = 3 (dx^4 + dy^4 + dz^4) - 1,")
235 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)).")
236 uf.desc[-1].add_paragraph("The correlation times are")
237 uf.desc[-1].add_item_list_element(None, "1 / tau -2 = 6Diso - 2Da . R,")
238 uf.desc[-1].add_item_list_element(None, "1 / tau -1 = 6Diso - Da (1 + 3Dr),")
239 uf.desc[-1].add_item_list_element(None, "1 / tau 0 = 6Diso - Da (1 - 3Dr),")
240 uf.desc[-1].add_item_list_element(None, "1 / tau 1 = 6Diso + 2Da,")
241 uf.desc[-1].add_item_list_element(None, "1 / tau 1 = 6Diso + 2Da . R.")
242 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].")
243 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")
244 uf.desc[-1].add_item_list_element("0", "{tm, Da, Dr, alpha, beta, gamma} (Default),")
245 uf.desc[-1].add_item_list_element("1", "{Diso, Da, Dr, alpha, beta, gamma},")
246 uf.desc[-1].add_item_list_element("2", "{Dx, Dy, Dz, alpha, beta, gamma},")
247 uf.desc[-1].add_item_list_element("3", "{Dxx, Dyy, Dzz, Dxy, Dxz, Dyz},")
248 uf.desc[-1].add_paragraph("where")
249 uf.desc[-1].add_item_list_element(None, "tm = 1 / 6Diso,")
250 uf.desc[-1].add_item_list_element(None, "Diso = 1/3 (Dx + Dy + Dz),")
251 uf.desc[-1].add_item_list_element(None, "Da = Dz - (Dx + Dy)/2,")
252 uf.desc[-1].add_item_list_element(None, "Dr = (Dy - Dx)/2Da.")
253 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")
254 uf.desc[-1].add_item_list_element(None, "0 <= alpha <= 2pi,")
255 uf.desc[-1].add_item_list_element(None, "0 <= beta <= pi,")
256 uf.desc[-1].add_item_list_element(None, "0 <= gamma <= 2pi.")
257 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")
258 uf.desc[-1].add_item_list_element(None, "0 <= theta <= pi,")
259 uf.desc[-1].add_item_list_element(None, "0 <= phi <= 2pi.")
260 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.")
261
262 uf.desc.append(Desc_container("Units"))
263 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.")
264 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.")
265 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.")
266
267 uf.desc.append(Desc_container("Prompt examples"))
268 uf.desc[-1].add_paragraph("To set an isotropic diffusion tensor with a correlation time of 10 ns, type:")
269 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(10e-9)")
270 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=10e-9)")
271 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(10.0, 1e-9)")
272 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=10.0, time_scale=1e-9, fixed=True)")
273 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:")
274 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((8.5e-9, 1.1, 20.0, 20.0), param_types=2)")
275 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:")
276 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((1.698e7, 1.417e7, 67.174, -83.718), param_types=3)")
277 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=(1.698e7, 1.417e7, 67.174, -83.718), param_types=3)")
278 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)")
279 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)")
280 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')")
281 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)")
282 uf.desc[-1].add_paragraph("To select ellipsoidal diffusion, type:")
283 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((1.340e7, 1.516e7, 1.691e7, -82.027, -80.573, 65.568), param_types=2)")
284 uf.backend = diffusion_tensor.init
285 uf.menu_text = "&init"
286 uf.gui_icon = "relax.diff_tensor"
287 uf.wizard_size = (1000, 750)
288 uf.wizard_height_desc = 400
289 uf.wizard_image = WIZARD_IMAGE_PATH + 'diff_tensor.png'
290