1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 """The frame_order user function definitions."""
24
25
26 import dep_check
27 if dep_check.wx_module:
28 from wx import FD_SAVE
29 else:
30 FD_SAVE = -1
31
32
33 from graphics import WIZARD_IMAGE_PATH
34 from specific_analyses.frame_order.uf import average_position, num_int_pts, pdb_model, pivot, quad_int, ref_domain, select_model
35 from user_functions.data import Uf_info; uf_info = Uf_info()
36 from user_functions.objects import Desc_container
37 from user_functions.wildcards import WILDCARD_STRUCT_PDB_ALL
38
39
40
41 uf_class = uf_info.add_class('frame_order')
42 uf_class.title = "Class containing the user functions of the Frame Order theories."
43 uf_class.menu_text = "&frame_order"
44 uf_class.gui_icon = "relax.frame_order"
45
46
47
48 uf = uf_info.add_uf('frame_order.average_position')
49 uf.title = "Define the mechanics of the average domain position."
50 uf.title_short = "Average domain position mechanics."
51 uf.add_keyarg(
52 name = "pivot",
53 default = "com",
54 py_type = "str",
55 dim = 3,
56 desc_short = "average position pivot",
57 desc = "The type of pivot to use for the rotation to the average domain position. This can be one of 'com' or 'motional'.",
58 list_titles = ['X coordinate', 'Y coordinate', 'Z coordinate'],
59 wiz_element_type = "combo",
60 wiz_combo_choices = [
61 "Centre of Mass (CoM)",
62 "Motional pivot"
63 ],
64 wiz_combo_data = [
65 "com",
66 "motional"
67 ],
68 wiz_read_only = True
69 )
70 uf.add_keyarg(
71 name = "translation",
72 default = False,
73 py_type = "bool",
74 desc_short = "translation flag",
75 desc = "A flag specifying if the average domain position should be allowed to translate during optimisation. If False, then translation can be disabled."
76 )
77
78 uf.desc.append(Desc_container())
79 uf.desc[-1].add_paragraph("Prior to optimisation, the mechanics of the average moving domain position must be specified. Having the domain shifted to the correct average position is essential for understanding the dynamics as this information is the major contributor to the RDC and PCS. The motional eigenframe (spherical or Euler angles) and ordering (via order parameters, cone angles or torsion angles) come second, and are therefore severely distorted by an incorrect average domain position.")
80 uf.desc[-1].add_paragraph("There are two pieces of information affecting this average position - a rotation and translation. For the rotation, a pivot point is required. Note that this pivot is not related to the pivot of the motions. However if you believe that your starting structure lies within the uniform distribution of positions of the domain motions, then the two pivots can be linked by setting the average position pivot to the motional pivot. The default however is to set the pivot to the centre of mass (CoM) of the moving domain.")
81 uf.desc[-1].add_paragraph("The second option allows the average domain position to translate during optimisation. By default, only a rotation of the initial structure of the domain is rotated to the average position. But if the rotation is not sufficient to shift the domain to the average position, then a translation will be required. This option will be ignored if no PDC data is present, as RDCs do not contain information about the translation of the domain.")
82
83 uf.desc.append(Desc_container("Prompt examples"))
84 uf.desc[-1].add_paragraph("To use the centre of mass as the rotational pivot and to allow translation of the average domain position during optimisation, type one of:")
85 uf.desc[-1].add_prompt("relax> frame_order.translate('com', True)")
86 uf.desc[-1].add_prompt("relax> frame_order.translate(translation=True)")
87 uf.desc[-1].add_prompt("relax> frame_order.translate(pivot='com', translation=True)")
88 uf.desc[-1].add_paragraph("To use the motional pivot as the average domain rotational pivot while disallowing translation of, type one of:")
89 uf.desc[-1].add_prompt("relax> frame_order.translate('motional')")
90 uf.desc[-1].add_prompt("relax> frame_order.translate('motional', False)")
91 uf.desc[-1].add_prompt("relax> frame_order.translate(pivot='motional', translation=False)")
92 uf.backend = average_position
93 uf.menu_text = "&average_position"
94 uf.wizard_height_desc = 450
95 uf.wizard_size = (1000, 750)
96 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
97
98
99
100 uf = uf_info.add_uf('frame_order.pdb_model')
101 uf.title = "Create a PDB file representation of the frame order dynamics."
102 uf.title_short = "Frame order dynamics PDB representation."
103 uf.add_keyarg(
104 name = "ave_pos_file",
105 default = "ave_pos.pdb",
106 py_type = "str",
107 arg_type = "file sel",
108 desc_short = "average structure file name",
109 desc = "The name of the 3D structure PDB file for the molecular structure with the moving domains shifted to the average position.",
110 wiz_filesel_wildcard = WILDCARD_STRUCT_PDB_ALL,
111 wiz_filesel_style = FD_SAVE,
112 can_be_none = True
113 )
114 uf.add_keyarg(
115 name = "rep_file",
116 default = "frame_order.pdb",
117 py_type = "str",
118 arg_type = "file sel",
119 desc_short = "PDB representation file name",
120 desc = "The name of the PDB file for the geometric object representation of the frame order dynamics.",
121 wiz_filesel_wildcard = WILDCARD_STRUCT_PDB_ALL,
122 wiz_filesel_style = FD_SAVE,
123 can_be_none = True
124 )
125 uf.add_keyarg(
126 name = "dist_file",
127 default = "domain_distribution.pdb",
128 py_type = "str",
129 arg_type = "file sel",
130 desc_short = "distribution file name",
131 desc = "The name of the file which will contain multiple models spanning the full dynamics distribution of the frame order model.",
132 wiz_filesel_wildcard = WILDCARD_STRUCT_PDB_ALL,
133 wiz_filesel_style = FD_SAVE,
134 can_be_none = True
135 )
136 uf.add_keyarg(
137 name = "dir",
138 py_type = "str",
139 arg_type = "dir",
140 desc_short = "directory name",
141 desc = "The directory where the file is to be located.",
142 can_be_none = True
143 )
144 uf.add_keyarg(
145 name = "size",
146 default = 30.0,
147 py_type = "num",
148 desc_short = "geometric object size",
149 desc = "The size of the geometric object in Angstroms."
150 )
151 uf.add_keyarg(
152 name = "inc",
153 default = 36,
154 py_type = "int",
155 desc_short = "increment number",
156 desc = "The number of increments used to create the geometric object.",
157 wiz_element_type = "spin"
158 )
159 uf.add_keyarg(
160 name = "force",
161 default = False,
162 py_type = "bool",
163 desc_short = "force flag",
164 desc = "A flag which, if set to True, will overwrite the any pre-existing files."
165 )
166
167 uf.desc.append(Desc_container())
168 uf.desc[-1].add_paragraph("This function creates a PDB file containing an artificial geometric structure representing the Frame Order cone models.")
169 uf.desc[-1].add_paragraph("There are four different types of residue within the PDB. The pivot point is represented as as a single carbon atom of the residue 'PIV'. The cone consists of numerous H atoms of the residue 'CON'. The cone axis vector is presented as the residue 'AXE' with one carbon atom positioned at the pivot and the other x Angstroms away on the cone axis (set by the geometric object size). Finally, if Monte Carlo have been performed, there will be multiple 'MCC' residues representing the cone for each simulation, and multiple 'MCA' residues representing the multiple cone axes.")
170 uf.desc[-1].add_paragraph("To create the diffusion in a cone PDB representation, a uniform distribution of vectors on a sphere is generated using spherical coordinates with the polar angle defined by the cone axis. By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors. These are all placed into the PDB file as H atoms and are all connected using PDB CONECT records. Each H atom is connected to its two neighbours on the both the longitude and latitude. This creates a geometric PDB object with longitudinal and latitudinal lines representing the filled cone.")
171 uf.backend = pdb_model
172 uf.menu_text = "pdb_&model"
173 uf.gui_icon = "oxygen.actions.document-save"
174 uf.wizard_height_desc = 400
175 uf.wizard_size = (1000, 750)
176 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
177
178
179
180 uf = uf_info.add_uf('frame_order.pivot')
181 uf.title = "Set the pivot points for the two body motion in the structural coordinate system."
182 uf.title_short = "Pivot point setting."
183 uf.add_keyarg(
184 name = "pivot",
185 py_type = "num_list",
186 dim = 3,
187 desc_short = "pivot point",
188 desc = "The pivot point for the motion (e.g. the position between the 2 domains in PDB coordinates).",
189 can_be_none = True
190 )
191 uf.add_keyarg(
192 name = "order",
193 default = 1,
194 min = 1,
195 max = 100,
196 py_type = "int",
197 desc_short = "pivot point number",
198 desc = "The ordinal number of the pivot point. The value of 1 is for the first pivot point, the value of 2 for the second pivot point, and so on.",
199 wiz_element_type = "spin"
200 )
201 uf.add_keyarg(
202 name = "fix",
203 py_type = "bool",
204 default = False,
205 desc_short = "fixed flag",
206 desc = "A flag specifying if the pivot point should be fixed during optimisation."
207 )
208
209 uf.desc.append(Desc_container())
210 uf.desc[-1].add_paragraph("This will set the pivot points for the two domain system within the PDB coordinate system. This is required for interpreting PCS data as well as for the generation of cone or other PDB representations of the domain motions.")
211 uf.desc[-1].add_paragraph("This user function can also be used to change the optimisation status of an already set pivot point. By simply providing the fixed flag and not the pivot point values, the pivot can be changed to be either fixed during optimisation or that it will be optimised.")
212
213 uf.desc.append(Desc_container("Prompt examples"))
214 uf.desc[-1].add_paragraph("To set the pivot point, type one of:")
215 uf.desc[-1].add_prompt("relax> frame_order.pivot([12.067, 14.313, -3.2675])")
216 uf.desc[-1].add_prompt("relax> frame_order.pivot(pivot=[12.067, 14.313, -3.2675])")
217 uf.desc[-1].add_paragraph("To change an already set and fixed pivot point so that it can now be optimised, type:")
218 uf.desc[-1].add_prompt("relax> frame_order.pivot(fix=False)")
219 uf.backend = pivot
220 uf.menu_text = "&pivot"
221 uf.wizard_size = (900, 600)
222 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
223
224
225
226 uf = uf_info.add_uf('frame_order.num_int_pts')
227 uf.title = "Set the number of integration points used in the quasi-random Sobol' sequence during optimisation."
228 uf.title_short = "Number of integration points."
229 uf.add_keyarg(
230 name = "num",
231 default = 200000,
232 min = 3,
233 max = 10000000,
234 py_type = "int",
235 desc_short = "number of points",
236 desc = "The number of integration points to use in the Sobol' sequence during optimisation.",
237 wiz_element_type = "spin"
238 )
239
240 uf.desc.append(Desc_container())
241 uf.desc[-1].add_paragraph("This allows the number of integration points used during the Frame Order target function optimisation to be changed from the default. This is used in the quasi-random Sobol' sequence for the numerical integration.")
242 uf.backend = num_int_pts
243 uf.menu_text = "&num_int_pts"
244 uf.gui_icon = "oxygen.actions.edit-rename"
245 uf.wizard_size = (900, 500)
246 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
247
248
249
250 uf = uf_info.add_uf('frame_order.quad_int')
251 uf.title = "Turn the high precision quadratic integration on or off."
252 uf.title_short = "Quadratic integration."
253 uf.add_keyarg(
254 name = "flag",
255 default = False,
256 py_type = "bool",
257 desc_short = "flag",
258 desc = "The flag with if True will perform high precision numerical integration via the scipy.integrate quad(), dblquad() and tplquad() integration methods rather than the rough quasi-random numerical integration."
259 )
260
261 uf.desc.append(Desc_container())
262 uf.desc[-1].add_paragraph("This allows the high precision numerical integration of the Scipy quad() and related functions to be used instead of the lower precision quasi-random Sobol' sequence integration. This is for the optimisation of the Frame Order target functions. The quadratic integration is orders of magnitude slower than the Sobol' sequence integration, but the precision is much higher.")
263 uf.backend = quad_int
264 uf.menu_text = "&quad_int"
265 uf.gui_icon = "oxygen.actions.edit-rename"
266 uf.wizard_size = (900, 500)
267 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
268
269
270
271 uf = uf_info.add_uf('frame_order.ref_domain')
272 uf.title = "Set the reference domain for the '2-domain' Frame Order theories."
273 uf.title_short = "Reference domain setting."
274 uf.add_keyarg(
275 name = "ref",
276 py_type = "str",
277 desc_short = "reference frame",
278 desc = "The domain which will act as the frame of reference. This is only valid for the '2-domain' Frame Order theories."
279 )
280
281 uf.desc.append(Desc_container())
282 uf.desc[-1].add_paragraph("Prior to optimisation of the '2-domain' Frame Order theories, which of the two domains will act as the frame of reference must be specified. This is important for the attachment of cones to domains, etc.")
283
284 uf.desc.append(Desc_container("Prompt examples"))
285 uf.desc[-1].add_paragraph("To set up the isotropic cone frame order model with 'centre' domain being the frame of reference, type:")
286 uf.desc[-1].add_prompt("relax> frame_order.ref_domain(ref='centre')")
287 uf.backend = ref_domain
288 uf.menu_text = "&ref_domain"
289 uf.gui_icon = "oxygen.actions.edit-rename"
290 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
291
292
293
294 uf = uf_info.add_uf('frame_order.select_model')
295 uf.title = "Select and set up the Frame Order model."
296 uf.title_short = "Model choice."
297 uf.add_keyarg(
298 name = "model",
299 py_type = "str",
300 desc_short = "Frame Order model",
301 desc = "The name of the preset Frame Order model.",
302 wiz_element_type = "combo",
303 wiz_combo_choices = [
304 "Free rotor model",
305 "Rigid model",
306 "Rotor model",
307 "Free rotor line model",
308 "Torsionless line model",
309 "Line model",
310 "Free rotor isotropic cone",
311 "Torsionless isotropic cone",
312 "Isotropic cone",
313 "Free rotor pseudo-ellipse",
314 "Torsionless pseudo-ellipse",
315 "Pseudo-ellipse",
316 "Double rotor"
317 ],
318 wiz_combo_data = [
319 "free rotor",
320 "rigid",
321 "rotor",
322 "line, free rotor",
323 "line, torsionless",
324 "line",
325 "iso cone, free rotor",
326 "iso cone, torsionless",
327 "iso cone",
328 "pseudo-ellipse, free rotor",
329 "pseudo-ellipse, torsionless",
330 "pseudo-ellipse",
331 "double rotor"
332 ],
333 wiz_read_only = True,
334 )
335
336 uf.desc.append(Desc_container())
337 uf.desc[-1].add_paragraph("Prior to optimisation, the Frame Order model should be selected. These models consist of three parameter categories:")
338 uf.desc[-1].add_list_element("The average domain position. This includes the parameters ave_pos_alpha, ave_pos_beta, and ave_pos_gamma. These Euler angles rotate the tensors from the arbitrary PDB frame of the moving domain to the average domain position.")
339 uf.desc[-1].add_list_element("The frame order eigenframe. This includes the parameters eigen_alpha, eigen_beta, and eigen_gamma. These Euler angles define the major modes of motion. The cone central axis is defined as the z-axis. The pseudo-elliptic cone x and y-axes are defined as the x and y-axes of the eigenframe.")
340 uf.desc[-1].add_list_element("The cone parameters. These are defined as the tilt-torsion angles cone_theta_x, cone_theta_y, and cone_sigma_max. The cone_theta_x and cone_theta_y parameters define the two cone opening angles of the pseudo-ellipse. The amount of domain torsion is defined as the average domain position, plus and minus cone_sigma_max. The isotropic cones are defined by setting cone_theta_x = cone_theta_y and converting the single parameter into a 2nd rank order parameter.")
341 uf.desc[-1].add_paragraph("The list of available models are:")
342 uf.desc[-1].add_item_list_element("'pseudo-ellipse'", "The pseudo-elliptic cone model. This is the full model consisting of the parameters ave_pos_alpha, ave_pos_beta, ave_pos_gamma, eigen_alpha, eigen_beta, eigen_gamma, cone_theta_x, cone_theta_y, and cone_sigma_max.")
343 uf.desc[-1].add_item_list_element("'pseudo-ellipse, torsionless'", "The pseudo-elliptic cone with the torsion angle cone_sigma_max set to zero.")
344 uf.desc[-1].add_item_list_element("'pseudo-ellipse, free rotor'", "The pseudo-elliptic cone with no torsion angle restriction.")
345 uf.desc[-1].add_item_list_element("'iso cone'", "The isotropic cone model. The cone is defined by a single order parameter s1 which is related to the single cone opening angle cone_theta_x = cone_theta_y. Due to rotational symmetry about the cone axis, the average position alpha Euler angle ave_pos_alpha is dropped from the model. The symmetry also collapses the eigenframe to a single z-axis defined by the parameters axis_theta and axis_phi.")
346 uf.desc[-1].add_item_list_element("'iso cone, torsionless'", "The isotropic cone model with the torsion angle cone_sigma_max set to zero.")
347 uf.desc[-1].add_item_list_element("'iso cone, free rotor'", "The isotropic cone model with no torsion angle restriction.")
348 uf.desc[-1].add_item_list_element("'line'", "The line cone model. This is the pseudo-elliptic cone with one of the cone angles, cone_theta_y, assumed to be statistically negligible. I.e. the cone angle is so small that it cannot be distinguished from noise.")
349 uf.desc[-1].add_item_list_element("'line, torsionless'", "The line cone model with the torsion angle cone_sigma_max set to zero.")
350 uf.desc[-1].add_item_list_element("'line, free rotor'", "The line cone model with no torsion angle restriction.")
351 uf.desc[-1].add_item_list_element("'rotor'", "The only motion is a rotation about the cone axis restricted by the torsion angle cone_sigma_max.")
352 uf.desc[-1].add_item_list_element("'rigid'", "No domain motions.")
353 uf.desc[-1].add_item_list_element("'free rotor'", "The only motion is free rotation about the cone axis.")
354 uf.desc[-1].add_item_list_element("'double rotor'", "Restricted motions about two independent rotor axes.")
355
356 uf.desc.append(Desc_container("Prompt examples"))
357 uf.desc[-1].add_paragraph("To select the isotropic cone model, type:")
358 uf.desc[-1].add_prompt("relax> frame_order.select_model(model='iso cone')")
359 uf.backend = select_model
360 uf.menu_text = "&select_model"
361 uf.gui_icon = "oxygen.actions.list-add"
362 uf.wizard_height_desc = 560
363 uf.wizard_size = (1000, 750)
364 uf.wizard_apply_button = False
365 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
366