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.setup import frame_order_obj
35 from user_functions.data import Uf_info; uf_info = Uf_info()
36 from user_functions.objects import Desc_container
37
38
39
40 uf_class = uf_info.add_class('frame_order')
41 uf_class.title = "Class containing the user functions of the Frame Order theories."
42 uf_class.menu_text = "&frame_order"
43 uf_class.gui_icon = "relax.frame_order"
44
45
46
47 uf = uf_info.add_uf('frame_order.average_position')
48 uf.title = "Define the mechanics of the average domain position."
49 uf.title_short = "Average domain position mechanics."
50 uf.add_keyarg(
51 name = "pivot",
52 default = "com",
53 py_type = "str",
54 desc_short = "average position pivot",
55 desc = "The type of pivot to use for the rotation to the average domain position. This can be one of 'com' or 'motional'.",
56 wiz_element_type = "combo",
57 wiz_combo_choices = [
58 "Centre of Mass (CoM)",
59 "Motional pivot"
60 ],
61 wiz_combo_data = [
62 "com",
63 "motional"
64 ],
65 wiz_read_only = True
66 )
67 uf.add_keyarg(
68 name = "translation",
69 default = False,
70 py_type = "bool",
71 desc_short = "translation flag",
72 desc = "A flag specifying if the average domain position should be allowed to translate during optimisation. If False, then translation can be disabled."
73 )
74
75 uf.desc.append(Desc_container())
76 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.")
77 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.")
78 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.")
79
80 uf.desc.append(Desc_container("Prompt examples"))
81 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:")
82 uf.desc[-1].add_prompt("relax> frame_order.translate('com', True)")
83 uf.desc[-1].add_prompt("relax> frame_order.translate(translation=True)")
84 uf.desc[-1].add_prompt("relax> frame_order.translate(pivot='com', translation=True)")
85 uf.desc[-1].add_paragraph("To use the motional pivot as the average domain rotational pivot while disallowing translation of, type one of:")
86 uf.desc[-1].add_prompt("relax> frame_order.translate('motional')")
87 uf.desc[-1].add_prompt("relax> frame_order.translate('motional', False)")
88 uf.desc[-1].add_prompt("relax> frame_order.translate(pivot='motional', translation=False)")
89 uf.backend = frame_order_obj._average_position
90 uf.menu_text = "&average_position"
91 uf.wizard_height_desc = 450
92 uf.wizard_size = (1000, 750)
93 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
94
95
96
97 uf = uf_info.add_uf('frame_order.pdb_model')
98 uf.title = "Create a PDB file representation of the frame order dynamics."
99 uf.title_short = "Frame order dynamics PDB representation."
100 uf.add_keyarg(
101 name = "ave_pos_file",
102 default = "ave_pos.pdb",
103 py_type = "str",
104 arg_type = "file sel",
105 desc_short = "average structure file name",
106 desc = "The name of the 3D structure PDB file for the molecular structure with the moving domains shifted to the average position.",
107 wiz_filesel_wildcard = "PDB files (*.pdb)|*.pdb;*.PDB",
108 wiz_filesel_style = FD_SAVE
109 )
110 uf.add_keyarg(
111 name = "rep_file",
112 default = "frame_order.pdb",
113 py_type = "str",
114 arg_type = "file sel",
115 desc_short = "PDB representation file name",
116 desc = "The name of the PDB file for the geometric object representation of the frame order dynamics.",
117 wiz_filesel_wildcard = "PDB files (*.pdb)|*.pdb;*.PDB",
118 wiz_filesel_style = FD_SAVE
119 )
120 uf.add_keyarg(
121 name = "dist_file",
122 default = "domain_distribution.pdb",
123 py_type = "str",
124 arg_type = "file sel",
125 desc_short = "distribution file name",
126 desc = "The name of the file which will contain multiple models spanning the full dynamics distribution of the frame order model.",
127 wiz_filesel_wildcard = "PDB files (*.pdb)|*.pdb;*.PDB",
128 wiz_filesel_style = FD_SAVE
129 )
130 uf.add_keyarg(
131 name = "dir",
132 py_type = "str",
133 arg_type = "dir",
134 desc_short = "directory name",
135 desc = "The directory where the file is to be located.",
136 can_be_none = True
137 )
138 uf.add_keyarg(
139 name = "size",
140 default = 30.0,
141 py_type = "num",
142 desc_short = "geometric object size",
143 desc = "The size of the geometric object in Angstroms."
144 )
145 uf.add_keyarg(
146 name = "inc",
147 default = 36,
148 py_type = "int",
149 desc_short = "increment number",
150 desc = "The number of increments used to create the geometric object.",
151 wiz_element_type = "spin"
152 )
153 uf.add_keyarg(
154 name = "force",
155 default = False,
156 py_type = "bool",
157 desc_short = "force flag",
158 desc = "A flag which, if set to True, will overwrite the any pre-existing files."
159 )
160
161 uf.desc.append(Desc_container())
162 uf.desc[-1].add_paragraph("This function creates a PDB file containing an artificial geometric structure representing the Frame Order cone models.")
163 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.")
164 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.")
165 uf.backend = frame_order_obj._pdb_model
166 uf.menu_text = "pdb_&model"
167 uf.gui_icon = "oxygen.actions.document-save"
168 uf.wizard_height_desc = 400
169 uf.wizard_size = (1000, 750)
170 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
171
172
173
174 uf = uf_info.add_uf('frame_order.pivot')
175 uf.title = "Set the pivot point for the two body motion in the structural coordinate system."
176 uf.title_short = "Pivot point setting."
177 uf.add_keyarg(
178 name = "pivot",
179 py_type = "num_list",
180 dim = 3,
181 desc_short = "pivot point",
182 desc = "The pivot point for the motion (e.g. the position between the 2 domains in PDB coordinates)."
183 )
184 uf.add_keyarg(
185 name = "fix",
186 py_type = "bool",
187 desc_short = "fixed flag",
188 desc = "A flag specifying if the pivot point should be fixed during optimisation."
189 )
190
191 uf.desc.append(Desc_container())
192 uf.desc[-1].add_paragraph("This will set the pivot point 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.")
193
194 uf.desc.append(Desc_container("Prompt examples"))
195 uf.desc[-1].add_paragraph("To set the pivot point, type one of:")
196 uf.desc[-1].add_prompt("relax> frame_order.pivot([12.067, 14.313, -3.2675])")
197 uf.desc[-1].add_prompt("relax> frame_order.pivot(pivot=[12.067, 14.313, -3.2675])")
198 uf.backend = frame_order_obj._pivot
199 uf.menu_text = "&pivot"
200 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
201
202
203
204 uf = uf_info.add_uf('frame_order.num_int_pts')
205 uf.title = "Set the number of integration points used in the quasi-random Sobol' sequence during optimisation."
206 uf.title_short = "Number of integration points."
207 uf.add_keyarg(
208 name = "num",
209 default = 200000,
210 min = 3,
211 max = 10000000,
212 py_type = "int",
213 desc_short = "number of points",
214 desc = "The number of integration points to use in the Sobol' sequence during optimisation.",
215 wiz_element_type = "spin"
216 )
217
218 uf.desc.append(Desc_container())
219 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.")
220 uf.backend = frame_order_obj._num_int_pts
221 uf.menu_text = "&num_int_pts"
222 uf.gui_icon = "oxygen.actions.edit-rename"
223 uf.wizard_size = (900, 500)
224 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
225
226
227
228 uf = uf_info.add_uf('frame_order.quad_int')
229 uf.title = "Turn the high precision quadratic integration on or off."
230 uf.title_short = "Quadratic integration."
231 uf.add_keyarg(
232 name = "flag",
233 default = False,
234 py_type = "bool",
235 desc_short = "flag",
236 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."
237 )
238
239 uf.desc.append(Desc_container())
240 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.")
241 uf.backend = frame_order_obj._quad_int
242 uf.menu_text = "&quad_int"
243 uf.gui_icon = "oxygen.actions.edit-rename"
244 uf.wizard_size = (900, 500)
245 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
246
247
248
249 uf = uf_info.add_uf('frame_order.ref_domain')
250 uf.title = "Set the reference domain for the '2-domain' Frame Order theories."
251 uf.title_short = "Reference domain setting."
252 uf.add_keyarg(
253 name = "ref",
254 py_type = "str",
255 desc_short = "reference frame",
256 desc = "The domain which will act as the frame of reference. This is only valid for the '2-domain' Frame Order theories."
257 )
258
259 uf.desc.append(Desc_container())
260 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.")
261
262 uf.desc.append(Desc_container("Prompt examples"))
263 uf.desc[-1].add_paragraph("To set up the isotropic cone frame order model with 'centre' domain being the frame of reference, type:")
264 uf.desc[-1].add_prompt("relax> frame_order.ref_domain(ref='centre')")
265 uf.backend = frame_order_obj._ref_domain
266 uf.menu_text = "&ref_domain"
267 uf.gui_icon = "oxygen.actions.edit-rename"
268 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
269
270
271
272 uf = uf_info.add_uf('frame_order.select_model')
273 uf.title = "Select and set up the Frame Order model."
274 uf.title_short = "Model choice."
275 uf.add_keyarg(
276 name = "model",
277 py_type = "str",
278 desc_short = "Frame Order model",
279 desc = "The name of the preset Frame Order model.",
280 wiz_element_type = "combo",
281 wiz_combo_choices = [
282 "Free rotor model",
283 "Rigid model",
284 "Rotor model",
285 "Free rotor line model",
286 "Torsionless line model",
287 "Line model",
288 "Free rotor isotropic cone",
289 "Torsionless isotropic cone",
290 "Isotropic cone",
291 "Free rotor pseudo-ellipse",
292 "Torsionless pseudo-ellipse",
293 "Pseudo-ellipse"
294 ],
295 wiz_combo_data = [
296 "free rotor",
297 "rigid",
298 "rotor",
299 "line, free rotor",
300 "line, torsionless",
301 "line",
302 "iso cone, free rotor",
303 "iso cone, torsionless",
304 "iso cone",
305 "pseudo-ellipse, free rotor",
306 "pseudo-ellipse, torsionless",
307 "pseudo-ellipse"
308 ],
309 wiz_read_only = True,
310 )
311
312 uf.desc.append(Desc_container())
313 uf.desc[-1].add_paragraph("Prior to optimisation, the Frame Order model should be selected. These models consist of three parameter categories:")
314 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.")
315 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.")
316 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.")
317 uf.desc[-1].add_paragraph("The list of available models are:")
318 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.")
319 uf.desc[-1].add_item_list_element("'pseudo-ellipse, torsionless'", "The pseudo-elliptic cone with the torsion angle cone_sigma_max set to zero.")
320 uf.desc[-1].add_item_list_element("'pseudo-ellipse, free rotor'", "The pseudo-elliptic cone with no torsion angle restriction.")
321 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.")
322 uf.desc[-1].add_item_list_element("'iso cone, torsionless'", "The isotropic cone model with the torsion angle cone_sigma_max set to zero.")
323 uf.desc[-1].add_item_list_element("'iso cone, free rotor'", "The isotropic cone model with no torsion angle restriction.")
324 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.")
325 uf.desc[-1].add_item_list_element("'line, torsionless'", "The line cone model with the torsion angle cone_sigma_max set to zero.")
326 uf.desc[-1].add_item_list_element("'line, free rotor'", "The line cone model with no torsion angle restriction.")
327 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.")
328 uf.desc[-1].add_item_list_element("'rigid'", "No domain motions.")
329 uf.desc[-1].add_item_list_element("'free rotor'", "The only motion is free rotation about the cone axis.")
330
331 uf.desc.append(Desc_container("Prompt examples"))
332 uf.desc[-1].add_paragraph("To select the isotropic cone model, type:")
333 uf.desc[-1].add_prompt("relax> frame_order.select_model(model='iso cone')")
334 uf.backend = frame_order_obj._select_model
335 uf.menu_text = "&select_model"
336 uf.gui_icon = "oxygen.actions.list-add"
337 uf.wizard_height_desc = 560
338 uf.wizard_size = (1000, 750)
339 uf.wizard_apply_button = False
340 uf.wizard_image = WIZARD_IMAGE_PATH + 'frame_order.png'
341