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