1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24 """Module containing the 'value' user function class."""
25 __docformat__ = 'plaintext'
26
27
28 from doc_string import docs
29 from base_class import User_fn_class, _build_doc
30 import arg_check
31 from generic_fns import diffusion_tensor
32 from generic_fns import value
33 from relax_errors import RelaxError
34 from specific_fns.jw_mapping import Jw_mapping
35 from specific_fns.model_free import Model_free
36 from specific_fns.relax_fit import Relax_fit
37 from specific_fns.n_state_model import N_state_model
38 from specific_fns.noe import Noe
39
40
41 -class Value(User_fn_class):
42 """Class for setting data values."""
43
44 - def copy(self, pipe_from=None, pipe_to=None, param=None):
45
46 if self._exec_info.intro:
47 text = self._exec_info.ps3 + "value.copy("
48 text = text + "pipe_from=" + repr(pipe_from)
49 text = text + ", pipe_to=" + repr(pipe_to)
50 text = text + ", param=" + repr(param) + ")"
51 print(text)
52
53
54 arg_check.is_str(pipe_from, 'pipe from')
55 arg_check.is_str(pipe_to, 'pipe to')
56 arg_check.is_str(param, 'parameter')
57
58
59 value.copy(pipe_from=pipe_from, pipe_to=pipe_to, param=param)
60
61
62 copy._doc_title = "Copy spin specific data values from one data pipe to another."
63 copy._doc_title_short = "Value copying."
64 copy._doc_args = [
65 ["pipe_from", "The name of the pipe to copy from."],
66 ["pipe_to", "The name of the pipe to copy to."],
67 ["param", "The parameter to copy. Only one parameter may be selected."]
68 ]
69 copy._doc_desc = """
70 If this is used to change values of previously minimised parameters, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.
71 """
72 copy._doc_examples = """
73 To copy the CSA values from the data pipe 'm1' to 'm2', type:
74
75 relax> value.copy('m1', 'm2', 'csa')
76 """
77 copy._doc_additional = [
78 docs.regexp.doc,
79 Model_free.set_doc,
80 Model_free.return_data_name_doc,
81 Jw_mapping.set_doc,
82 Jw_mapping.return_data_name_doc,
83 Relax_fit.set_doc,
84 Relax_fit.return_data_name_doc,
85 N_state_model.set_doc,
86 N_state_model.return_data_name_doc
87 ]
88 _build_doc(copy)
89
90
92
93 if self._exec_info.intro:
94 text = self._exec_info.ps3 + "value.display("
95 text = text + "param=" + repr(param) + ")"
96 print(text)
97
98
99 arg_check.is_str(param, 'parameter')
100
101
102 value.display(param=param)
103
104
105 display._doc_title = "Display spin specific data values."
106 display._doc_title_short = "Display values."
107 display._doc_args = [
108 ["param", "The parameter to display. Only one parameter may be selected."]
109 ]
110 display._doc_examples = """
111 To show all CSA values, type:
112
113 relax> value.display('csa')
114 """
115 display._doc_additional = [
116 docs.regexp.doc,
117 Model_free.return_data_name_doc,
118 Jw_mapping.return_data_name_doc,
119 Noe.return_data_name_doc,
120 Relax_fit.return_data_name_doc,
121 N_state_model.return_data_name_doc
122 ]
123 _build_doc(display)
124
125
126 - def read(self, param=None, scaling=1.0, file=None, dir=None, spin_id_col=None, mol_name_col=None, res_num_col=None, res_name_col=None, spin_num_col=None, spin_name_col=None, data_col=None, error_col=None, sep=None, spin_id=None):
127
128 if self._exec_info.intro:
129 text = self._exec_info.ps3 + "value.read("
130 text = text + "param=" + repr(param)
131 text = text + ", scaling=" + repr(scaling)
132 text = text + ", file=" + repr(file)
133 text = text + ", dir=" + repr(dir)
134 text = text + ", spin_id_col=" + repr(spin_id_col)
135 text = text + ", mol_name_col=" + repr(mol_name_col)
136 text = text + ", res_num_col=" + repr(res_num_col)
137 text = text + ", res_name_col=" + repr(res_name_col)
138 text = text + ", spin_num_col=" + repr(spin_num_col)
139 text = text + ", spin_name_col=" + repr(spin_name_col)
140 text = text + ", data_col=" + repr(data_col)
141 text = text + ", error_col=" + repr(error_col)
142 text = text + ", sep=" + repr(sep)
143 text = text + ", spin_id=" + repr(spin_id) + ")"
144 print(text)
145
146
147 arg_check.is_str(param, 'parameter')
148 arg_check.is_float(scaling, 'scaling')
149 arg_check.is_str(file, 'file name')
150 arg_check.is_str(dir, 'directory name', can_be_none=True)
151 arg_check.is_int(spin_id_col, 'spin ID string column', can_be_none=True)
152 arg_check.is_int(mol_name_col, 'molecule name column', can_be_none=True)
153 arg_check.is_int(res_num_col, 'residue number column', can_be_none=True)
154 arg_check.is_int(res_name_col, 'residue name column', can_be_none=True)
155 arg_check.is_int(spin_num_col, 'spin number column', can_be_none=True)
156 arg_check.is_int(spin_name_col, 'spin name column', can_be_none=True)
157 arg_check.is_int(data_col, 'data column', can_be_none=True)
158 arg_check.is_int(error_col, 'error column', can_be_none=True)
159 arg_check.is_str(sep, 'column separator', can_be_none=True)
160 arg_check.is_str(spin_id, 'spin ID string', can_be_none=True)
161
162
163 value.read(param=param, scaling=scaling, file=file, dir=dir, spin_id_col=spin_id_col, mol_name_col=mol_name_col, res_num_col=res_num_col, res_name_col=res_name_col, spin_num_col=spin_num_col, spin_name_col=spin_name_col, data_col=data_col, error_col=error_col, sep=sep, spin_id=spin_id)
164
165
166 read._doc_title = "Read spin specific data values from a file."
167 read._doc_title_short = "Reading values from file."
168 read._doc_args = [
169 ["param", "The parameter. Only one parameter may be selected."],
170 ["scaling", "The factor to scale parameters by."],
171 ["file", "The name of the file containing the values."],
172 ["dir", "The directory where the file is located."],
173 ["spin_id_col", "The spin ID string column (an alternative to the mol, res, and spin name and number columns)."],
174 ["mol_name_col", "The molecule name column (alternative to the spin_id_col)."],
175 ["res_num_col", "The residue number column (alternative to the spin_id_col)."],
176 ["res_name_col", "The residue name column (alternative to the spin_id_col)."],
177 ["spin_num_col", "The spin number column (alternative to the spin_id_col)."],
178 ["spin_name_col", "The spin name column (alternative to the spin_id_col)."],
179 ["data_col", "The RDC data column."],
180 ["error_col", "The experimental error column."],
181 ["sep", "The column separator (the default is white space)."],
182 ["spin_id", "The spin ID string to restrict the loading of data to certain spin subsets."]
183 ]
184 read._doc_desc = """
185 The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the molecule name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin ID string can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
186
187 If this is used to change values of previously minimised parameters, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.
188 """
189 read._doc_examples = """
190 To load 15N CSA values from the file 'csa_values' in the directory 'data', where spins are
191 only identified by residue name and number, type one of the following:
192
193 relax> value.read('csa', 'data/csa_value', spin_id='@N')
194 relax> value.read('csa', 'csa_value', dir='data', spin_id='@N')
195 relax> value.read(param='csa', file='csa_value', dir='data', res_num_col=1, res_name_col=2,
196 data_col=3, error_col=4, spin_id='@N')
197 """
198 read._doc_additional = [
199 docs.regexp.doc,
200 Model_free.set_doc,
201 Model_free.return_data_name_doc,
202 Jw_mapping.set_doc,
203 Jw_mapping.return_data_name_doc,
204 Relax_fit.set_doc,
205 Relax_fit.return_data_name_doc,
206 N_state_model.set_doc,
207 N_state_model.return_data_name_doc
208 ]
209 _build_doc(read)
210
211
212 - def set(self, val=None, param=None, spin_id=None):
213
214 if self._exec_info.intro:
215 text = self._exec_info.ps3 + "value.set("
216 text = text + "val=" + repr(val)
217 text = text + ", param=" + repr(param)
218 text = text + ", spin_id=" + repr(spin_id) + ")"
219 print(text)
220
221
222 arg_check.is_str_or_num_or_str_num_list(val, 'value', can_be_none=True)
223 arg_check.is_str_or_str_list(param, 'parameter', can_be_none=True)
224 arg_check.is_str(spin_id, 'spin identification string', can_be_none=True)
225
226
227 if (isinstance(val, float) or isinstance(val, int)) and param == None:
228 raise RelaxError("Invalid value and parameter argument combination, for details by type 'help(value.set)'")
229
230
231 if isinstance(val, list) and isinstance(param, str):
232 raise RelaxError("Invalid value and parameter argument combination, for details by type 'help(value.set)'")
233
234
235 if isinstance(val, list) and isinstance(param, list) and len(val) != len(param):
236 raise RelaxError("Both the value array and parameter array must be of equal length.")
237
238
239 value.set(val=val, param=param, spin_id=spin_id)
240
241
242 set._doc_title = "Set spin specific data values."
243 set._doc_title_short = "Value setting."
244 set._doc_args = [
245 ["val", "The value(s)."],
246 ["param", "The parameter(s)."],
247 ["spin_id", "The spin identifier."]
248 ]
249 set._doc_desc = """
250 If this function is used to change values of previously minimised results, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset to None.
251
252
253 The val argument can be None, a single value, or an array of values while the parameter argument can be None, a string, or array of strings. The choice of which combination determines the behaviour of this function. The following table describes what occurs in each instance. The Value column refers to the 'val' argument while the Param column refers to the 'param' argument. In these columns, 'None' corresponds to None, '1' corresponds to either a single value or single string, and 'n' corresponds to either an array of values or an array of strings.
254
255 ____________________________________________________________________________________________
256 | | | |
257 | Value | Param | Description |
258 |_______|_______|__________________________________________________________________________|
259 | | | |
260 | None | None | This case is used to set the model parameters prior to minimisation or |
261 | | | calculation. The model parameters are set to the default values. |
262 | | | |
263 | 1 | None | Invalid combination. |
264 | | | |
265 | n | None | This case is used to set the model parameters prior to minimisation or |
266 | | | calculation. The length of the val array must be equal to the number |
267 | | | of model parameters. The parameters will be set to the corresponding |
268 | | | number. |
269 | | | |
270 | None | 1 | The parameter matching the string will be set to the default value. |
271 | | | |
272 | 1 | 1 | The parameter matching the string will be set to the supplied number. |
273 | | | |
274 | n | 1 | Invalid combination. |
275 | | | |
276 | None | n | Each parameter matching the strings will be set to the default values. |
277 | | | |
278 | 1 | n | Each parameter matching the strings will be set to the supplied number. |
279 | | | |
280 | n | n | Each parameter matching the strings will be set to the corresponding |
281 | | | number. Both arrays must be of equal length. |
282 |_______|_______|__________________________________________________________________________|
283
284 """
285 set._doc_examples = """
286 To set the parameter values for the current data pipe to the default values, for all spins,
287 type:
288
289 relax> value.set()
290
291
292 To set the parameter values of residue 10, which is in the current model-free data pipe 'm4'
293 and has the parameters {S2, te, Rex}, the following can be used. Rex term is the value for
294 the first given field strength.
295
296 relax> value.set([0.97, 2.048*1e-9, 0.149], spin_id=':10')
297 relax> value.set(val=[0.97, 2.048*1e-9, 0.149], spin_id=':10')
298
299
300 To set the CSA value of all spins to the default value, type:
301
302 relax> value.set(param='csa')
303
304
305 To set the CSA value of all spins to -172 ppm, type:
306
307 relax> value.set(-172 * 1e-6, 'csa')
308 relax> value.set(val=-172 * 1e-6, param='csa')
309
310
311 To set the NH bond length of all spins to 1.02 Angstroms, type:
312
313 relax> value.set(1.02 * 1e-10, 'r')
314 relax> value.set(val=1.02 * 1e-10, param='r')
315
316
317 To set both the bond length and the CSA value to the default values, type:
318
319 relax> value.set(param=['r', 'csa'])
320
321
322 To set both tf and ts to 100 ps, type:
323
324 relax> value.set(100e-12, ['tf', 'ts'])
325 relax> value.set(val=100e-12, param=['tf', 'ts'])
326
327
328 To set the S2 and te parameter values of residue 126, Ca spins to 0.56 and 13 ps, type:
329
330 relax> value.set([0.56, 13e-12], ['s2', 'te'], ':126@Ca')
331 relax> value.set(val=[0.56, 13e-12], param=['s2', 'te'], spin_id=':126@Ca')
332 relax> value.set(val=[0.56, 13e-12], param=['s2', 'te'], spin_id=':126@Ca')
333 """
334 set._doc_additional = [
335 ["Spin identification", """
336 If the spin ID is left unset, then this will be applied to all spins. If the data is global non-spin specific data, such as diffusion tensor parameters, supplying the spin identifier will terminate the program with an error.
337 """],
338 docs.regexp.doc,
339 Model_free.set_doc,
340 Model_free.return_data_name_doc,
341 Model_free.default_value_doc,
342 Jw_mapping.set_doc,
343 Jw_mapping.return_data_name_doc,
344 Jw_mapping.default_value_doc,
345 diffusion_tensor.__set_prompt_doc__,
346 diffusion_tensor.__return_data_name_prompt_doc__,
347 diffusion_tensor.__default_value_prompt_doc__,
348 Relax_fit.set_doc,
349 Relax_fit.return_data_name_doc,
350 Relax_fit.default_value_doc,
351 N_state_model.set_doc,
352 N_state_model.return_data_name_doc,
353 N_state_model.default_value_doc
354 ]
355 _build_doc(set)
356
357
358 - def write(self, param=None, file=None, dir=None, bc=False, force=False):
359
360 if self._exec_info.intro:
361 text = self._exec_info.ps3 + "value.write("
362 text = text + "param=" + repr(param)
363 text = text + ", file=" + repr(file)
364 text = text + ", dir=" + repr(dir)
365 text = text + ", bc=" + repr(bc)
366 text = text + ", force=" + repr(force) + ")"
367 print(text)
368
369
370 arg_check.is_str(param, 'parameter')
371 arg_check.is_str(file, 'file name')
372 arg_check.is_str(dir, 'directory name', can_be_none=True)
373 arg_check.is_bool(bc, 'back calculated value flag')
374 arg_check.is_bool(force, 'force flag')
375
376
377 value.write(param=param, file=file, dir=dir, bc=bc, force=force)
378
379
380 write._doc_title = "Write spin specific data values to a file."
381 write._doc_title_short = "Value writing."
382 write._doc_args = [
383 ["param", "The parameter."],
384 ["file", "The name of the file."],
385 ["dir", "The directory name."],
386 ["bc", "A flag which if True will cause the back calculated values to be written to file rather than the actual data."],
387 ["force", "A flag which, if set to True, will cause the file to be overwritten."]
388 ]
389 write._doc_desc = """
390 The values corresponding to the given parameter will be written to file.
391 """
392 write._doc_examples = """
393 To write the CSA values to the file 'csa.txt', type one of:
394
395 relax> value.write('csa', 'csa.txt')
396 relax> value.write(param='csa', file='csa.txt')
397
398
399 To write the NOE values to the file 'noe', type one of:
400
401 relax> value.write('noe', 'noe.out')
402 relax> value.write(param='noe', file='noe.out')
403 relax> value.write(param='noe', file='noe.out')
404 relax> value.write(param='noe', file='noe.out', force=True)
405 """
406 write._doc_additional = [
407 docs.regexp.doc,
408 Model_free.return_data_name_doc,
409 Jw_mapping.return_data_name_doc,
410 Noe.return_data_name_doc,
411 Relax_fit.return_data_name_doc,
412 N_state_model.return_data_name_doc
413 ]
414 _build_doc(write)
415