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 py_type = "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 py_type = "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 py_type = "num_or_num_tuple",
119 dim = [4, 6],
120 desc_short = "diffusion tensor parameters",
121 desc = "The diffusion tensor data."
122 )
123 uf.add_keyarg(
124 name = "time_scale",
125 default = 1.0,
126 py_type = "num",
127 desc_short = "time scale",
128 desc = "The correlation time scaling value."
129 )
130 uf.add_keyarg(
131 name = "d_scale",
132 default = 1.0,
133 py_type = "num",
134 desc_short = "D scale",
135 desc = "The diffusion tensor eigenvalue scaling value."
136 )
137 uf.add_keyarg(
138 name = "angle_units",
139 default = "deg",
140 py_type = "str",
141 desc_short = "angle units",
142 desc = "The units for the angle parameters."
143 )
144 uf.add_keyarg(
145 name = "param_types",
146 default = 0,
147 py_type = "int",
148 desc_short = "parameter types",
149 desc = "A flag to select different parameter combinations."
150 )
151 uf.add_keyarg(
152 name = "spheroid_type",
153 py_type = "str",
154 desc_short = "spheroid type",
155 desc = "A string which, if supplied together with spheroid parameters, will restrict the tensor to either being 'oblate' or 'prolate'.",
156 can_be_none = True
157 )
158 uf.add_keyarg(
159 name = "fixed",
160 default = True,
161 py_type = "bool",
162 desc_short = "fixed flag",
163 desc = "A flag specifying whether the diffusion tensor is fixed or can be optimised."
164 )
165
166 uf.desc.append(Desc_container("The sphere (isotropic diffusion)"))
167 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")
168 uf.desc[-1].add_verbatim("""
169 1 - tau / tm
170 C(tau) = - e ,
171 5
172 """)
173 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")
174 uf.desc[-1].add_item_list_element("0", "{tm} (Default),")
175 uf.desc[-1].add_item_list_element("1", "{Diso},")
176 uf.desc[-1].add_paragraph("where")
177 uf.desc[-1].add_item_list_element(None, "1 / tm = 6Diso.")
178
179 uf.desc.append(Desc_container("The spheroid (axially symmetric diffusion)"))
180 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")
181 uf.desc[-1].add_verbatim("""
182 _1_
183 1 \ - tau / tau_i
184 C(tau) = - > ci . e ,
185 5 /__
186 i=-1
187 """)
188 uf.desc[-1].add_paragraph("where")
189 uf.desc[-1].add_item_list_element(None, "c-1 = 1/4 (3 dz^2 - 1)^2,")
190 uf.desc[-1].add_item_list_element(None, "c0 = 3 dz^2 (1 - dz^2),")
191 uf.desc[-1].add_item_list_element(None, "c1 = 3/4 (dz^2 - 1)^2,")
192 uf.desc[-1].add_paragraph("and")
193 uf.desc[-1].add_item_list_element(None, "1 / tau -1 = 6Diso - 2Da,")
194 uf.desc[-1].add_item_list_element(None, "1 / tau 0 = 6Diso - Da,")
195 uf.desc[-1].add_item_list_element(None, "1 / tau 1 = 6Diso + 2Da.")
196 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.")
197 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")
198 uf.desc[-1].add_item_list_element("0", "{tm, Da, theta, phi} (Default),")
199 uf.desc[-1].add_item_list_element("1", "{Diso, Da, theta, phi},")
200 uf.desc[-1].add_item_list_element("2", "{tm, Dratio, theta, phi},")
201 uf.desc[-1].add_item_list_element("3", "{Dpar, Dper, theta, phi},")
202 uf.desc[-1].add_item_list_element("4", "{Diso, Dratio, theta, phi},")
203 uf.desc[-1].add_paragraph("where")
204 uf.desc[-1].add_item_list_element(None, "tm = 1 / 6Diso,")
205 uf.desc[-1].add_item_list_element(None, "Diso = 1/3 (Dpar + 2Dper),")
206 uf.desc[-1].add_item_list_element(None, "Da = Dpar - Dper,")
207 uf.desc[-1].add_item_list_element(None, "Dratio = Dpar / Dper.")
208 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")
209 uf.desc[-1].add_item_list_element(None, "0 <= theta <= pi,")
210 uf.desc[-1].add_item_list_element(None, "0 <= phi <= 2pi,")
211 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")
212 uf.desc[-1].add_item_list_element(None, "0 <= alpha <= 2pi.")
213 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.")
214
215 uf.desc.append(Desc_container("The ellipsoid (rhombic diffusion)"))
216 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")
217 uf.desc[-1].add_verbatim("""
218 _2_
219 1 \ - tau / tau_i
220 C(tau) = - > ci . e ,
221 5 /__
222 i=-2
223 """)
224 uf.desc[-1].add_paragraph("where the weights on the exponentials are")
225 uf.desc[-1].add_item_list_element(None, "c-2 = 1/4 (d + e),")
226 uf.desc[-1].add_item_list_element(None, "c-1 = 3 dy^2 dz^2,")
227 uf.desc[-1].add_item_list_element(None, "c0 = 3 dx^2 dz^2,")
228 uf.desc[-1].add_item_list_element(None, "c1 = 3 dx^2 dy^2,")
229 uf.desc[-1].add_item_list_element(None, "c2 = 1/4 (d + e).")
230 uf.desc[-1].add_paragraph("Let")
231 uf.desc[-1].add_item_list_element(None, "R = sqrt(1 + 3Dr),")
232 uf.desc[-1].add_paragraph("then")
233 uf.desc[-1].add_item_list_element(None, "d = 3 (dx^4 + dy^4 + dz^4) - 1,")
234 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)).")
235 uf.desc[-1].add_paragraph("The correlation times are")
236 uf.desc[-1].add_item_list_element(None, "1 / tau -2 = 6Diso - 2Da . R,")
237 uf.desc[-1].add_item_list_element(None, "1 / tau -1 = 6Diso - Da (1 + 3Dr),")
238 uf.desc[-1].add_item_list_element(None, "1 / tau 0 = 6Diso - Da (1 - 3Dr),")
239 uf.desc[-1].add_item_list_element(None, "1 / tau 1 = 6Diso + 2Da,")
240 uf.desc[-1].add_item_list_element(None, "1 / tau 1 = 6Diso + 2Da . R.")
241 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].")
242 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")
243 uf.desc[-1].add_item_list_element("0", "{tm, Da, Dr, alpha, beta, gamma} (Default),")
244 uf.desc[-1].add_item_list_element("1", "{Diso, Da, Dr, alpha, beta, gamma},")
245 uf.desc[-1].add_item_list_element("2", "{Dx, Dy, Dz, alpha, beta, gamma},")
246 uf.desc[-1].add_item_list_element("3", "{Dxx, Dyy, Dzz, Dxy, Dxz, Dyz},")
247 uf.desc[-1].add_paragraph("where")
248 uf.desc[-1].add_item_list_element(None, "tm = 1 / 6Diso,")
249 uf.desc[-1].add_item_list_element(None, "Diso = 1/3 (Dx + Dy + Dz),")
250 uf.desc[-1].add_item_list_element(None, "Da = Dz - (Dx + Dy)/2,")
251 uf.desc[-1].add_item_list_element(None, "Dr = (Dy - Dx)/2Da.")
252 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")
253 uf.desc[-1].add_item_list_element(None, "0 <= alpha <= 2pi,")
254 uf.desc[-1].add_item_list_element(None, "0 <= beta <= pi,")
255 uf.desc[-1].add_item_list_element(None, "0 <= gamma <= 2pi.")
256 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")
257 uf.desc[-1].add_item_list_element(None, "0 <= theta <= pi,")
258 uf.desc[-1].add_item_list_element(None, "0 <= phi <= 2pi.")
259 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.")
260
261 uf.desc.append(Desc_container("Units"))
262 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.")
263 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.")
264 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.")
265
266 uf.desc.append(Desc_container("Prompt examples"))
267 uf.desc[-1].add_paragraph("To set an isotropic diffusion tensor with a correlation time of 10 ns, type:")
268 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(10e-9)")
269 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=10e-9)")
270 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(10.0, 1e-9)")
271 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=10.0, time_scale=1e-9, fixed=True)")
272 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:")
273 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((8.5e-9, 1.1, 20.0, 20.0), param_types=2)")
274 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:")
275 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((1.698e7, 1.417e7, 67.174, -83.718), param_types=3)")
276 uf.desc[-1].add_prompt("relax> diffusion_tensor.init(params=(1.698e7, 1.417e7, 67.174, -83.718), param_types=3)")
277 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)")
278 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)")
279 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')")
280 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)")
281 uf.desc[-1].add_paragraph("To select ellipsoidal diffusion, type:")
282 uf.desc[-1].add_prompt("relax> diffusion_tensor.init((1.340e7, 1.516e7, 1.691e7, -82.027, -80.573, 65.568), param_types=2)")
283 uf.backend = diffusion_tensor.init
284 uf.menu_text = "&init"
285 uf.gui_icon = "relax.diff_tensor"
286 uf.wizard_size = (1000, 750)
287 uf.wizard_height_desc = 400
288 uf.wizard_image = WIZARD_IMAGE_PATH + 'diff_tensor.png'
289