1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 """The model-free analysis user functions."""
24
25
26 from re import match
27
28
29 from lib.errors import RelaxError, RelaxFuncSetupError, RelaxNoSequenceError, RelaxTensorError
30 from pipe_control import pipes
31 from pipe_control.mol_res_spin import exists_mol_res_spin_data, spin_loop
32 import specific_analyses
33 from specific_analyses.model_free.api import Model_free
34 from specific_analyses.model_free.model import model_map
35 from user_functions.data import Uf_tables; uf_tables = Uf_tables()
36 from user_functions.objects import Desc_container
37
38
39 api_model_free = Model_free()
40
41
42
43 classic_style_doc = Desc_container("Model-free classic style")
44 classic_style_doc.add_paragraph("Creator: Edward d'Auvergne")
45 classic_style_doc.add_paragraph("Argument string: \"classic\"")
46 classic_style_doc.add_paragraph("Description: The classic style draws the backbone of a protein in a cylindrical bond style. Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured. Deselected residues are shown as black lines.")
47 classic_style_doc.add_paragraph("Supported data types:")
48 table = uf_tables.add_table(label="table: model-free macro classic style", caption="The model-free classic style for mapping model spin specific data onto 3D molecular structures using either PyMOL or Molmol.", caption_short="The model-free classic style for PyMOL and Molmol data mapping.")
49 table.add_headings(["Data type", "String", "Description"])
50 table.add_row(["S2.", "'s2'", "The standard model-free order parameter, equal to S2f.S2s for the two timescale models. The default colour gradient starts at 'yellow' and ends at 'red'."])
51 table.add_row(["S2f.", "'s2f'", "The order parameter of the faster of two internal motions. Residues which are described by model-free models m1 to m4, the single timescale models, are illustrated as white neon bonds. The default colour gradient is the same as that for the S2 data type."])
52 table.add_row(["S2s.", "'s2s'", "The order parameter of the slower of two internal motions. This functions exactly as S2f except that S2s is plotted instead."])
53 table.add_row(["Amplitude of fast motions.", "'amp_fast'", "Model independent display of the amplite of fast motions. For residues described by model-free models m5 to m8, the value plotted is that of S2f. However, for residues described by models m1 to m4, what is shown is dependent on the timescale of the motions. This is because these single timescale models can, at times, be perfect approximations to the more complex two timescale models. Hence if te is less than 200 ps, S2 is plotted. Otherwise the peptide bond is coloured white. The default colour gradient is the same as that for S2."])
54 table.add_row(["Amplitude of slow motions.", "'amp_slow'", "Model independent display of the amplite of slow motions, arbitrarily defined as motions slower than 200 ps. For residues described by model-free models m5 to m8, the order parameter S2 is plotted if ts > 200 ps. For models m1 to m4, S2 is plotted if te > 200 ps. The default colour gradient is the same as that for S2."])
55 table.add_row(["te.", "'te'", "The correlation time, te. The default colour gradient starts at 'turquoise' and ends at 'blue'."])
56 table.add_row(["tf.", "'tf'", "The correlation time, tf. The default colour gradient is the same as that of te."])
57 table.add_row(["ts.", "'ts'", "The correlation time, ts. The default colour gradient starts at 'blue' and ends at 'black'."])
58 table.add_row(["Timescale of fast motions", "'time_fast'", "Model independent display of the timescale of fast motions. For models m5 to m8, only the parameter tf is plotted. For models m2 and m4, the parameter te is plotted only if it is less than 200 ps. All other residues are assumed to have a correlation time of zero. The default colour gradient is the same as that of te."])
59 table.add_row(["Timescale of slow motions", "'time_slow'", "Model independent display of the timescale of slow motions. For models m5 to m8, only the parameter ts is plotted. For models m2 and m4, the parameter te is plotted only if it is greater than 200 ps. All other residues are coloured white. The default colour gradient is the same as that of ts."])
60 table.add_row(["Chemical exchange", "'rex'", "The chemical exchange, Rex. Residues which experience no chemical exchange are coloured white. The default colour gradient starts at 'yellow' and finishes at 'red'."])
61 classic_style_doc.add_table(table.label)
62
63
64 eliminate_doc = []
65 eliminate_doc.append(Desc_container("Local tm model elimination rule"))
66 eliminate_doc[-1].add_paragraph("The local tm, in some cases, may exceed the value expected for a global correlation time. Generally the tm value will be stuck at the upper limit defined for the parameter. These models are eliminated using the rule:")
67 eliminate_doc[-1].add_verbatim(" tm >= c")
68 eliminate_doc[-1].add_paragraph("The default value of c is 50 ns, although this can be overridden by supplying the value (in seconds) as the first element of the args tuple.")
69 eliminate_doc.append(Desc_container("Internal correlation times {te, tf, ts} model elimination rules"))
70 eliminate_doc[-1].add_paragraph("These parameters may experience the same problem as the local tm in that the model fails and the parameter value is stuck at the upper limit. These parameters are constrained using the formula (te, tf, ts <= 2tm). These failed models are eliminated using the rule:")
71 eliminate_doc[-1].add_verbatim(" te, tf, ts >= c . tm.")
72 eliminate_doc[-1].add_paragraph("The default value of c is 1.5. Because of round-off errors and the constraint algorithm, setting c to 2 will result in no models being eliminated as the minimised parameters will always be less than 2tm. The value can be changed by supplying the value as the second element of the tuple.")
73 eliminate_doc.append(Desc_container("Arguments"))
74 eliminate_doc[-1].add_paragraph("The 'args' argument must be a tuple of length 2, the elements of which must be numbers. For example, to eliminate models which have a local tm value greater than 25 ns and models with internal correlation times greater than 1.5 times tm, set 'args' to (25 * 1e-9, 1.5).")
75
76
77 -def create_model(model=None, equation=None, params=None, spin_id=None):
78 """Function for creating a custom model-free model.
79
80 @param model: The name of the model.
81 @type model: str
82 @param equation: The equation type to use. The 3 allowed types are: 'mf_orig' for the original model-free equations with parameters {s2, te}; 'mf_ext' for the extended model-free equations with parameters {s2f, tf, s2, ts}; and 'mf_ext2' for the extended model-free equations with parameters {s2f, tf, s2s, ts}.
83 @type equation: str
84 @param params: A list of the parameters to include in the model. The allowed parameter names includes those for the equation type as well as chemical exchange 'rex', the bond length 'r', and the chemical shift anisotropy 'csa'.
85 @type params: list of str
86 @param spin_id: The spin identification string.
87 @type spin_id: str
88 """
89
90
91 pipes.test()
92
93
94 function_type = pipes.get_type()
95 if function_type != 'mf':
96 raise RelaxFuncSetupError(specific_analyses.get_string(function_type))
97
98
99 if not exists_mol_res_spin_data():
100 raise RelaxNoSequenceError
101
102
103 valid_types = ['mf_orig', 'mf_ext', 'mf_ext2']
104 if not equation in valid_types:
105 raise RelaxError("The model-free equation type argument " + repr(equation) + " is invalid and should be one of " + repr(valid_types) + ".")
106
107
108 s2, te, s2f, tf, s2s, ts, rex, csa, r = 0, 0, 0, 0, 0, 0, 0, 0, 0
109 for i in range(len(params)):
110
111 invalid_param = 0
112
113
114 if params[i] == 's2':
115
116 if s2:
117 invalid_param = 1
118 s2 = 1
119
120
121 s2s_flag = 0
122 for j in range(len(params)):
123 if params[j] == 's2s':
124 s2s_flag = 1
125 if s2s_flag:
126 invalid_param = 1
127
128
129 elif params[i] == 'te':
130
131 if equation == 'mf_ext' or te:
132 invalid_param = 1
133 te = 1
134
135
136 s2_flag = 0
137 for j in range(len(params)):
138 if params[j] == 's2':
139 s2_flag = 1
140 if not s2_flag:
141 invalid_param = 1
142
143
144 elif params[i] == 's2f':
145
146 if equation == 'mf_orig' or s2f:
147 invalid_param = 1
148 s2f = 1
149
150
151 elif params[i] == 's2s':
152
153 if equation == 'mf_orig' or s2s:
154 invalid_param = 1
155 s2s = 1
156
157
158 elif params[i] == 'tf':
159
160 if equation == 'mf_orig' or tf:
161 invalid_param = 1
162 tf = 1
163
164
165 s2f_flag = 0
166 for j in range(len(params)):
167 if params[j] == 's2f':
168 s2f_flag = 1
169 if not s2f_flag:
170 invalid_param = 1
171
172
173 elif params[i] == 'ts':
174
175 if equation == 'mf_orig' or ts:
176 invalid_param = 1
177 ts = 1
178
179
180 flag = 0
181 for j in range(len(params)):
182 if params[j] == 's2' or params[j] == 's2f':
183 flag = 1
184 if not flag:
185 invalid_param = 1
186
187
188 elif params[i] == 'rex':
189 if rex:
190 invalid_param = 1
191 rex = 1
192
193
194 elif params[i] == 'r':
195 if r:
196 invalid_param = 1
197 r = 1
198
199
200 elif params[i] == 'csa':
201 if csa:
202 invalid_param = 1
203 csa = 1
204
205
206 else:
207 raise RelaxError("The parameter " + params[i] + " is not supported.")
208
209
210 if invalid_param:
211 raise RelaxError("The parameter array " + repr(params) + " contains an invalid combination of parameters.")
212
213
214 model_setup(model, equation, params, spin_id)
215
216
245
246
247 -def model_setup(model=None, equation=None, params=None, spin_id=None):
248 """Function for updating various data structures depending on the model selected.
249
250 @param model: The name of the model.
251 @type model: str
252 @param equation: The equation type to use. The 3 allowed types are: 'mf_orig' for the original model-free equations with parameters {s2, te}; 'mf_ext' for the extended model-free equations with parameters {s2f, tf, s2, ts}; and 'mf_ext2' for the extended model-free equations with parameters {s2f, tf, s2s, ts}.
253 @type equation: str
254 @param params: A list of the parameters to include in the model. The allowed parameter names includes those for the equation type as well as chemical exchange 'rex', the bond length 'r', and the chemical shift anisotropy 'csa'.
255 @type params: list of str
256 @param spin_id: The spin identification string.
257 @type spin_id: str
258 """
259
260
261 if params:
262 for param in params:
263 if param == 'local_tm' and hasattr(pipes.get_pipe(), 'diff_tensor'):
264 raise RelaxTensorError('diffusion')
265
266
267 for spin in spin_loop(spin_id):
268
269 api_model_free.data_init(spin)
270
271
272 spin.model = model
273 spin.equation = equation
274 spin.params = params
275
276
331
332
359