1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25 """The model-free analysis user functions."""
26
27
28 from re import match
29
30
31 from lib.errors import RelaxError, RelaxFuncSetupError, RelaxNoSequenceError, RelaxTensorError
32 from pipe_control import pipes
33 from pipe_control.mol_res_spin import exists_mol_res_spin_data, spin_loop
34 from pipe_control.pipes import check_pipe
35 import specific_analyses
36 from specific_analyses.model_free.api import Model_free
37 from specific_analyses.model_free.model import model_map
38 from user_functions.data import Uf_tables; uf_tables = Uf_tables()
39 from user_functions.objects import Desc_container
40
41
42 api_model_free = Model_free()
43
44
45
46 classic_style_doc = Desc_container("Model-free classic style")
47 classic_style_doc.add_paragraph("Creator: Edward d'Auvergne")
48 classic_style_doc.add_paragraph("Argument string: \"classic\"")
49 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.")
50 classic_style_doc.add_paragraph("Supported data types:")
51 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.")
52 table.add_headings(["Data type", "String", "Description"])
53 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'."])
54 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."])
55 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."])
56 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."])
57 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."])
58 table.add_row(["te.", "'te'", "The correlation time, te. The default colour gradient starts at 'turquoise' and ends at 'blue'."])
59 table.add_row(["tf.", "'tf'", "The correlation time, tf. The default colour gradient is the same as that of te."])
60 table.add_row(["ts.", "'ts'", "The correlation time, ts. The default colour gradient starts at 'blue' and ends at 'black'."])
61 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."])
62 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."])
63 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'."])
64 classic_style_doc.add_table(table.label)
65
66
67 eliminate_doc = []
68 eliminate_doc.append(Desc_container("Local tm model elimination rule"))
69 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:")
70 eliminate_doc[-1].add_verbatim(" tm >= c")
71 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.")
72 eliminate_doc.append(Desc_container("Internal correlation times {te, tf, ts} model elimination rules"))
73 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:")
74 eliminate_doc[-1].add_verbatim(" te, tf, ts >= c . tm.")
75 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.")
76 eliminate_doc.append(Desc_container("Arguments"))
77 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).")
78
79
80 -def create_model(model=None, equation=None, params=None, spin_id=None):
81 """Function for creating a custom model-free model.
82
83 @param model: The name of the model.
84 @type model: str
85 @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}.
86 @type equation: str
87 @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'.
88 @type params: list of str
89 @param spin_id: The spin identification string.
90 @type spin_id: str
91 """
92
93
94 check_pipe()
95
96
97 function_type = pipes.get_type()
98 if function_type != 'mf':
99 raise RelaxFuncSetupError(specific_analyses.get_string(function_type))
100
101
102 if not exists_mol_res_spin_data():
103 raise RelaxNoSequenceError
104
105
106 valid_types = ['mf_orig', 'mf_ext', 'mf_ext2']
107 if not equation in valid_types:
108 raise RelaxError("The model-free equation type argument " + repr(equation) + " is invalid and should be one of " + repr(valid_types) + ".")
109
110
111 s2, te, s2f, tf, s2s, ts, rex, csa, r = 0, 0, 0, 0, 0, 0, 0, 0, 0
112 for i in range(len(params)):
113
114 invalid_param = 0
115
116
117 if params[i] == 's2':
118
119 if s2:
120 invalid_param = 1
121 s2 = 1
122
123
124 s2s_flag = 0
125 for j in range(len(params)):
126 if params[j] == 's2s':
127 s2s_flag = 1
128 if s2s_flag:
129 invalid_param = 1
130
131
132 elif params[i] == 'te':
133
134 if equation == 'mf_ext' or te:
135 invalid_param = 1
136 te = 1
137
138
139 s2_flag = 0
140 for j in range(len(params)):
141 if params[j] == 's2':
142 s2_flag = 1
143 if not s2_flag:
144 invalid_param = 1
145
146
147 elif params[i] == 's2f':
148
149 if equation == 'mf_orig' or s2f:
150 invalid_param = 1
151 s2f = 1
152
153
154 elif params[i] == 's2s':
155
156 if equation == 'mf_orig' or s2s:
157 invalid_param = 1
158 s2s = 1
159
160
161 elif params[i] == 'tf':
162
163 if equation == 'mf_orig' or tf:
164 invalid_param = 1
165 tf = 1
166
167
168 s2f_flag = 0
169 for j in range(len(params)):
170 if params[j] == 's2f':
171 s2f_flag = 1
172 if not s2f_flag:
173 invalid_param = 1
174
175
176 elif params[i] == 'ts':
177
178 if equation == 'mf_orig' or ts:
179 invalid_param = 1
180 ts = 1
181
182
183 flag = 0
184 for j in range(len(params)):
185 if params[j] == 's2' or params[j] == 's2f':
186 flag = 1
187 if not flag:
188 invalid_param = 1
189
190
191 elif params[i] == 'rex':
192 if rex:
193 invalid_param = 1
194 rex = 1
195
196
197 elif params[i] == 'r':
198 if r:
199 invalid_param = 1
200 r = 1
201
202
203 elif params[i] == 'csa':
204 if csa:
205 invalid_param = 1
206 csa = 1
207
208
209 else:
210 raise RelaxError("The parameter " + params[i] + " is not supported.")
211
212
213 if invalid_param:
214 raise RelaxError("The parameter array " + repr(params) + " contains an invalid combination of parameters.")
215
216
217 model_setup(model, equation, params, spin_id)
218
219
248
249
250 -def model_setup(model=None, equation=None, params=None, spin_id=None):
251 """Function for updating various data structures depending on the model selected.
252
253 @param model: The name of the model.
254 @type model: str
255 @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}.
256 @type equation: str
257 @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'.
258 @type params: list of str
259 @param spin_id: The spin identification string.
260 @type spin_id: str
261 """
262
263
264 if params:
265 for param in params:
266 if param == 'local_tm' and hasattr(pipes.get_pipe(), 'diff_tensor'):
267 raise RelaxTensorError('diffusion')
268
269
270 for spin, spin_id in spin_loop(spin_id, return_id=True):
271
272 api_model_free.data_init(spin_id)
273
274
275 spin.model = model
276 spin.equation = equation
277 spin.params = params
278
279
334
335
362