1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 """The dipole_pair user function definitions."""
24
25
26 import dep_check
27 from os import sep
28 if dep_check.wx_module:
29 from wx import FD_OPEN
30 else:
31 FD_OPEN = -1
32
33
34 from generic_fns import pipes, dipole_pair
35 from graphics import WIZARD_IMAGE_PATH
36 from physical_constants import NH_BOND_LENGTH
37 from user_functions.data import Uf_info; uf_info = Uf_info()
38 from user_functions.objects import Desc_container
39
40
41
42 uf_class = uf_info.add_class('dipole_pair')
43 uf_class.title = "Class for manipulating magnetic dipole-dipole interactions."
44 uf_class.menu_text = "&dipole_pair"
45 uf_class.gui_icon = "relax.dipole_pair"
46
47
48
49 uf = uf_info.add_uf('dipole_pair.define')
50 uf.title = "Define the pairs of spins involved in magnetic dipole-dipole interactions."
51 uf.title_short = "Magnetic dipole-dipole interaction setup."
52 uf.add_keyarg(
53 name = "spin_id1",
54 default = "@N",
55 py_type = "str",
56 arg_type = "spin ID",
57 desc_short = "first spin ID string",
58 desc = "The spin identification string for the first spin of the dipole pair."
59 )
60 uf.add_keyarg(
61 name = "spin_id2",
62 default = "@H",
63 py_type = "str",
64 arg_type = "spin ID",
65 desc_short = "second spin ID string",
66 desc = "The spin identification string for the second spin of the dipole pair."
67 )
68 uf.add_keyarg(
69 name = "direct_bond",
70 default = True,
71 py_type = "bool",
72 desc_short = "directly bonded atoms flag",
73 desc = "This is a flag which if True means that the two spins are directly bonded. This flag is useful to simply the set up of the main heteronuclear relaxation mechanism or one-bond residual dipolar couplings."
74 )
75
76 uf.desc.append(Desc_container())
77 uf.desc[-1].add_paragraph("To analyse relaxation or residual dipolar coupling (RDC) data, pairs of spins which are coupled via the magnetic dipole-dipole interaction need to be specified. This must proceed the use of the other user functions in this class. An interatomic data object will be created, if not already present, and this will be used to store all subsequently loaded dipole-dipole interaction information.")
78 uf.desc[-1].add_paragraph("For analyses which use relaxation data, specifying the dipole-dipole interaction will indicate that there is a dipolar relaxation mechanism operating between the two spins. Note that for model-free analyses or reduced spectral density mapping, only a single relaxation mechanism can be handled. For RDC dependent analyses, this indicates that a residual dipolar coupling is expected between the two spins.")
79
80 uf.desc.append(Desc_container("Prompt examples"))
81 uf.desc[-1].add_paragraph("To define the protein 15N heteronuclear relaxation mechanism for a model-free analysis, type one of the following:")
82 uf.desc[-1].add_prompt("relax> dipole_pair.define('@N', '@H', True)")
83 uf.desc[-1].add_prompt("relax> dipole_pair.define(spin_id1='@N', spin_id2='@H', direct_bond=True)")
84 uf.backend = dipole_pair.define
85 uf.menu_text = "&define"
86 uf.gui_icon = "oxygen.actions.list-add-relax-blue"
87 uf.wizard_height_desc = 350
88 uf.wizard_size = (900, 700)
89 uf.wizard_image = WIZARD_IMAGE_PATH + 'dipole_pair' + sep + 'NH_dipole_pair.png'
90
91
92
93 uf = uf_info.add_uf('dipole_pair.read_dist')
94 uf.title = "Load the r^-3 averaged distances for the magnetic dipole-dipole interactions from a file."
95 uf.title_short = "Magnetic dipole-dipole distance loading."
96 uf.add_keyarg(
97 name = "file",
98 py_type = "str",
99 arg_type = "file sel",
100 desc_short = "file name",
101 desc = "The name of the file containing the averaged distance data.",
102 wiz_filesel_style = FD_OPEN
103 )
104 uf.add_keyarg(
105 name = "dir",
106 py_type = "str",
107 arg_type = "dir",
108 desc_short = "directory name",
109 desc = "The directory where the file is located.",
110 can_be_none = True
111 )
112 uf.add_keyarg(
113 name = "unit",
114 default = "meter",
115 py_type = "str",
116 desc_short = "distance unit",
117 desc = "The unit of distance (the default is 'meter').",
118 wiz_element_type = "combo",
119 wiz_combo_choices = ["meter", "Angstrom"],
120 wiz_read_only = True
121 )
122 uf.add_keyarg(
123 name = "spin_id1_col",
124 default = 1,
125 py_type = "int",
126 min = 1,
127 desc_short = "first spin ID column",
128 desc = "The spin ID string column for the first spin."
129 )
130 uf.add_keyarg(
131 name = "spin_id2_col",
132 default = 2,
133 py_type = "int",
134 min = 1,
135 desc_short = "second spin ID column",
136 desc = "The spin ID string column for the second spin."
137 )
138 uf.add_keyarg(
139 name = "data_col",
140 default = 3,
141 py_type = "int",
142 min = 1,
143 desc_short = "data column",
144 desc = "The averaged distance data column."
145 )
146 uf.add_keyarg(
147 name = "sep",
148 py_type = "str",
149 desc_short = "column separator",
150 desc = "The column separator (the default is white space).",
151 wiz_element_type = "combo",
152 wiz_combo_choices = ["white space", ",", ";", ":"],
153 wiz_combo_data = [None, ",", ";", ":"],
154 wiz_read_only = False,
155 can_be_none = True
156 )
157
158 uf.desc.append(Desc_container())
159 uf.desc[-1].add_paragraph("As the magnetic dipole-dipole interaction is averaged in NMR over the interatomic distance to the inverse third power, the interatomic distances within a 3D structural file are of no use for defining the interaction. Therefore these average distances must be explicitly defined. The default measurement unit is 'meter' but this can be changed to 'Angstrom'.")
160 uf.desc[-1].add_paragraph("This user function allows these r^-3 averaged interatomic distances to be read from a file. This is useful in the case when the dipole-dipole distances vary, replacing the need to call the dipole_pair.set_dist user function many times. The format of the file should be columnar, with the two spin ID strings in two separate columns and the averaged distances in any other.")
161
162 uf.desc.append(Desc_container("Prompt examples"))
163 uf.desc[-1].add_paragraph("To load the distances in meters from the fifth column of the 'distances' file, and where the spin IDs are in the first and second columns, type one of the following:")
164 uf.desc[-1].add_prompt("relax> dipole_pair.read_dist('distances', 1, 2, 5)")
165 uf.desc[-1].add_prompt("relax> dipole_pair.read_dist(file='distances', unit='meter', spin_id1_col=1, spin_id2_col=2, data_col=5)")
166 uf.backend = dipole_pair.read_dist
167 uf.menu_text = "&read_dist"
168 uf.gui_icon = "oxygen.actions.document-open"
169 uf.wizard_height_desc = 350
170 uf.wizard_size = (900, 700)
171 uf.wizard_image = WIZARD_IMAGE_PATH + 'dipole_pair' + sep + 'NH_dipole_pair.png'
172
173
174
175 uf = uf_info.add_uf('dipole_pair.set_dist')
176 uf.title = "Set the r^-3 averaged distances for the magnetic dipole-dipole interactions."
177 uf.title_short = "Magnetic dipole-dipole distance setup."
178 uf.add_keyarg(
179 name = "spin_id1",
180 default = "@N",
181 py_type = "str",
182 arg_type = "spin ID",
183 desc_short = "first spin ID string",
184 desc = "The spin identification string for the first spin of the dipole pair."
185 )
186 uf.add_keyarg(
187 name = "spin_id2",
188 default = "@H",
189 py_type = "str",
190 arg_type = "spin ID",
191 desc_short = "second spin ID string",
192 desc = "The spin identification string for the second spin of the dipole pair."
193 )
194 uf.add_keyarg(
195 name = "ave_dist",
196 default = NH_BOND_LENGTH,
197 py_type = "float",
198 desc_short = "averaged interatomic distance",
199 desc = "The r^-3 averaged distance between the two spins to be used in the magnetic dipole constant, defaulting to meters."
200 )
201 uf.add_keyarg(
202 name = "unit",
203 default = "meter",
204 py_type = "str",
205 desc_short = "distance unit",
206 desc = "The unit of distance (the default is 'meter').",
207 wiz_element_type = "combo",
208 wiz_combo_choices = ["meter", "Angstrom"],
209 wiz_read_only = True
210 )
211
212 uf.desc.append(Desc_container())
213 uf.desc[-1].add_paragraph("As the magnetic dipole-dipole interaction is averaged in NMR over the interatomic distance to the inverse third power, the interatomic distances within a 3D structural file are of no use for defining the interaction. Therefore these average distances must be explicitly supplied. This user function allows these distances to be set up. The default measurement unit is 'meter' but this can be changed to 'Angstrom'.")
214
215 uf.desc.append(Desc_container("Prompt examples"))
216 uf.desc[-1].add_paragraph("To set the N-H distance for protein the 15N heteronuclear relaxation mechanism to 1.02 Angstrom, type one of the following:")
217 uf.desc[-1].add_prompt("relax> dipole_pair.set_dist('@N', '@H', 1.02 * 1e-10)")
218 uf.desc[-1].add_prompt("relax> dipole_pair.set_dist(spin_id1='@N', spin_id2='@H', ave_dist=1.02 * 1e-10, unit='meter')")
219 uf.desc[-1].add_prompt("relax> dipole_pair.set_dist(spin_id1='@N', spin_id2='@H', ave_dist=1.02, unit='Angstrom')")
220 uf.backend = dipole_pair.set_dist
221 uf.menu_text = "&set_dist"
222 uf.gui_icon = "oxygen.actions.edit-rename"
223 uf.wizard_height_desc = 350
224 uf.wizard_size = (900, 700)
225 uf.wizard_image = WIZARD_IMAGE_PATH + 'dipole_pair' + sep + 'NH_dipole_pair.png'
226
227
228
229 uf = uf_info.add_uf('dipole_pair.unit_vectors')
230 uf.title = "Calculate the unit vectors between the magnetic dipole-dipole interactions."
231 uf.title_short = "Magnetic dipole-dipole unit vector calculation."
232 uf.add_keyarg(
233 name = "ave",
234 default = True,
235 py_type = "bool",
236 desc_short = "average vector flag",
237 desc = "A flag which if True will cause the bond vectors from all models to be averaged. If vectors from only one model is extracted, this will have no effect."
238 )
239
240 uf.desc.append(Desc_container())
241 uf.desc[-1].add_paragraph("For an orientational dependent analysis, such as model-free analysis with the spheroidal and ellipsoidal global diffusion tensors or any analysis using RDCs, the unit vectors between the two dipoles must be calculated prior to starting the analysis. For the unit vector extraction, the two interacting spins should already possess positional information and the dipole-dipole interaction should already be defined via the dipole_pair.define user function. This information will be used to calculate unit vectors between the two spins. Without positional information, no vectors can be calculated and an orientational dependent analysis will not be possible.")
242 uf.desc[-1].add_paragraph("The number of unit vectors per interaction will be defined by the number of positions each spin possesses together with the averaging flag. If both spins have N and M positions loaded, the number of positions for both must match (N=M). In this case, as well as when one spin has N positions and the other a single position, then N unit vectors will be calculated. This is unless the averaging flag is set in which case an averaged vector of unit length will be calculated.")
243
244 uf.desc.append(Desc_container("Prompt examples"))
245 uf.desc[-1].add_paragraph("To calculate the unit vectors prior to a model-free analysis, type one of the following:")
246 uf.desc[-1].add_prompt("relax> dipole_pair.unit_vectors(True)")
247 uf.desc[-1].add_prompt("relax> dipole_pair.unit_vectors(ave=True)")
248 uf.backend = dipole_pair.unit_vectors
249 uf.menu_text = "&unit_vectors"
250 uf.wizard_height_desc = 400
251 uf.wizard_size = (900, 600)
252 uf.wizard_image = WIZARD_IMAGE_PATH + 'dipole_pair' + sep + 'NH_dipole_pair.png'
253