1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 """The module defining the analysis specific API."""
24
25
26 from lib.errors import RelaxImplementError
27
28
30 """Base class defining the specific_analyses API.
31
32 All the methods here are prototype methods. To identify that the method is not available for certain analysis types, if called a RelaxImplementError is raised if called.
33 """
34
35
36 instance = None
37
39 """Replacement function for implementing the singleton design pattern."""
40
41
42 if self.instance is None:
43
44 self.instance = object.__new__(self, *args, **kargs)
45
46
47 return self.instance
48
49
50 - def back_calc_ri(self, spin_index=None, ri_id=None, ri_type=None, frq=None):
51 """Back-calculation of relaxation data.
52
53 @keyword spin_index: The global spin index.
54 @type spin_index: int
55 @keyword ri_id: The relaxation data ID string.
56 @type ri_id: str
57 @keyword ri_type: The relaxation data type.
58 @type ri_type: str
59 @keyword frq: The field strength.
60 @type frq: float
61 @return: The back calculated relaxation data value corresponding to the index.
62 @rtype: float
63 """
64
65
66 raise RelaxImplementError('back_calc_ri')
67
68
70 """Generator method for looping over the base data of the specific analysis type.
71
72 Specific implementations of this generator method are free to yield any type of data. The data which is yielded is then passed into API methods such as return_data(), return_error(), create_mc_data(), pack_sim_data(), etc., so these methods should handle the data thrown at them. If multiple data is yielded, this is caught as a tuple and passed into the dependent methods as a tuple.
73
74
75 @return: Information concerning the base data of the analysis.
76 @rtype: anything
77 """
78
79
80 raise RelaxImplementError('base_data_loop')
81
82
83 - def bmrb_read(self, file_path, version=None, sample_conditions=None):
84 """Prototype method for reading the data from a BMRB NMR-STAR formatted file.
85
86 @param file_path: The full file path.
87 @type file_path: str
88 """
89
90
91 raise RelaxImplementError('bmrb_read')
92
93
95 """Prototype method for writing the data to a BMRB NMR-STAR formatted file.
96
97 @param file_path: The full file path.
98 @type file_path: str
99 @keyword version: The BMRB NMR-STAR dictionary format to output to.
100 @type version: str
101 """
102
103
104 raise RelaxImplementError('bmrb_write')
105
106
107 - def calculate(self, spin_id=None, verbosity=1, sim_index=None):
108 """Calculate the chi-squared value.
109
110 @keyword spin_id: The spin identification string.
111 @type spin_id: None or str
112 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
113 @type verbosity: int
114 @keyword sim_index: The optional MC simulation index.
115 @type sim_index: None or int
116 """
117
118
119 raise RelaxImplementError('calculate')
120
121
123 """Return the optimisation constraint algorithm, defaulting to the Method of Multipliers.
124
125 This can return one of:
126
127 - 'Method of Multipliers',
128 - 'Log barrier'.
129
130
131 @return: The constraint algorithm to use (one of 'Method of Multipliers' or 'Log barrier').
132 @rtype: str
133 """
134
135
136 return 'Method of Multipliers'
137
138
140 """Create the Monte Carlo data.
141
142 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method.
143 @type data_id: anything
144 @return: The Monte Carlo simulation data.
145 @rtype: list of floats
146 """
147
148
149 raise RelaxImplementError('create_mc_data')
150
151
153 """Initialise the data structures.
154
155 @param data_cont: The data container.
156 @type data_cont: instance
157 @keyword sim: The Monte Carlo simulation flag, which if true will initialise the simulation data structure.
158 @type sim: bool
159 """
160
161
162 raise RelaxImplementError('data_init')
163
164
165 - def data_names(self, set='all', scope=None, error_names=False, sim_names=False):
166 """Return a list of names of data structures.
167
168 @keyword set: The set of object names to return. This can be set to 'all' for all names, to 'generic' for generic object names, 'params' for analysis specific parameter names, or to 'min' for minimisation specific object names.
169 @type set: str
170 @keyword scope: The scope of the parameter to return. If not set, then all will be returned. If set to 'global' or 'spin', then only the parameters within that scope will be returned.
171 @type scope: str or None
172 @keyword error_names: A flag which if True will add the error object names as well.
173 @type error_names: bool
174 @keyword sim_names: A flag which if True will add the Monte Carlo simulation object names as well.
175 @type sim_names: bool
176 @return: The list of object names.
177 @rtype: list of str
178 """
179
180
181 return self._PARAMS.data_names(set=set, scope=scope, error_names=error_names, sim_names=sim_names)
182
183
185 """Return the type of data that the parameter should be.
186
187 This basic method will first search for a global parameter and, if not found, then a spin parameter.
188
189 @keyword param: The parameter name.
190 @type param: list of str
191 @return: The type of the parameter. I.e. the special Python type objects of int, float, str, bool, [str], {bool}, etc.
192 @rtype: any type
193 """
194
195
196 return self._PARAMS.type(param)
197
198
200 """Return the default parameter values.
201
202 This basic method will first search for a global parameter and, if not found, then a spin parameter.
203
204
205 @param param: The specific analysis parameter.
206 @type param: str
207 @return: The default value.
208 @rtype: float
209 """
210
211
212 return self._PARAMS.default_value(param)
213
214
215 - def deselect(self, model_info, sim_index=None):
216 """Deselect models or simulations.
217
218 @param model_info: The model index from model_info().
219 @type model_info: int
220 @keyword sim_index: The optional Monte Carlo simulation index. If None, then models will be deselected, otherwise the given simulation will.
221 @type sim_index: None or int
222 """
223
224
225 raise RelaxImplementError('deselect')
226
227
228 - def duplicate_data(self, pipe_from=None, pipe_to=None, model_info=None, global_stats=False, verbose=True):
229 """Duplicate the data specific to a single model.
230
231 @keyword pipe_from: The data pipe to copy the data from.
232 @type pipe_from: str
233 @keyword pipe_to: The data pipe to copy the data to.
234 @type pipe_to: str
235 @keyword model_info: The model index from model_info().
236 @type model_info: int
237 @keyword global_stats: The global statistics flag.
238 @type global_stats: bool
239 @keyword verbose: A flag which if True will cause info to be printed out.
240 @type verbose: bool
241 """
242
243
244 raise RelaxImplementError('duplicate_data')
245
246
247 - def eliminate(self, name, value, model_info, args, sim=None):
248 """Model elimination method.
249
250 @param name: The parameter name.
251 @type name: str
252 @param value: The parameter value.
253 @type value: float
254 @param model_info: The model index from model_info().
255 @type model_info: int
256 @param args: The elimination constant overrides.
257 @type args: None or tuple of float
258 @keyword sim: The Monte Carlo simulation index.
259 @type sim: int
260 @return: True if the model is to be eliminated, False otherwise.
261 @rtype: bool
262 """
263
264
265 raise RelaxImplementError('eliminate')
266
267
269 """Return a vector of parameter names.
270
271 @keyword model_info: The model index from model_info().
272 @type model_info: int
273 @return: The vector of parameter names.
274 @rtype: list of str
275 """
276
277
278 raise RelaxImplementError('get_param_names')
279
280
282 """Return a vector of parameter values.
283
284 @keyword model_info: The model index from model_info().
285 @type model_info: int
286 @keyword sim_index: The optional Monte Carlo simulation index.
287 @type sim_index: int
288 @return: The vector of parameter values.
289 @rtype: list of str
290 """
291
292
293 raise RelaxImplementError('get_param_values')
294
295
296 - def grid_search(self, lower=None, upper=None, inc=None, constraints=True, verbosity=1, sim_index=None):
297 """Grid search method.
298
299 @keyword lower: The lower bounds of the grid search which must be equal to the number of parameters in the model.
300 @type lower: array of numbers
301 @keyword upper: The upper bounds of the grid search which must be equal to the number of parameters in the model.
302 @type upper: array of numbers
303 @keyword inc: The increments for each dimension of the space for the grid search. The number of elements in the array must equal to the number of parameters in the model.
304 @type inc: array of int
305 @keyword constraints: If True, constraints are applied during the grid search (eliminating parts of the grid). If False, no constraints are used.
306 @type constraints: bool
307 @keyword verbosity: A flag specifying the amount of information to print. The higher the value, the greater the verbosity.
308 @type verbosity: int
309 @keyword sim_index: The index of the simulation to apply the grid search to. If None, the normal model is optimised.
310 @type sim_index: int
311 """
312
313
314 raise RelaxImplementError('grid_search')
315
316
318 """Test if errors exist for the current data pipe.
319
320 @return: The answer to the question of whether errors exist.
321 @rtype: bool
322 """
323
324
325 raise RelaxImplementError('has_errors')
326
327
329 """Determine whether the given parameter is spin specific.
330
331 @param name: The name of the parameter.
332 @type name: str
333 @return: True if the parameter is spin specific, False otherwise.
334 @rtype: bool
335 """
336
337
338 return self._PARAMS.is_spin_param(name)
339
340
342 """Create bounds for the OpenDX mapping function.
343
344 @param param: The name of the parameter to return the lower and upper bounds of.
345 @type param: str
346 @param spin_id: The spin identification string.
347 @type spin_id: None or str
348 @return: The upper and lower bounds of the parameter.
349 @rtype: list of float
350 """
351
352
353 raise RelaxImplementError('map_bounds')
354
355
356 - def minimise(self, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=False, scaling=True, verbosity=0, sim_index=None, lower=None, upper=None, inc=None):
357 """Minimisation method.
358
359 @keyword min_algor: The minimisation algorithm to use.
360 @type min_algor: str
361 @keyword min_options: An array of options to be used by the minimisation algorithm.
362 @type min_options: array of str
363 @keyword func_tol: The function tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
364 @type func_tol: None or float
365 @keyword grad_tol: The gradient tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
366 @type grad_tol: None or float
367 @keyword max_iterations: The maximum number of iterations for the algorithm.
368 @type max_iterations: int
369 @keyword constraints: If True, constraints are used during optimisation.
370 @type constraints: bool
371 @keyword scaling: If True, diagonal scaling is enabled during optimisation to allow the problem to be better conditioned.
372 @type scaling: bool
373 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
374 @type verbosity: int
375 @keyword sim_index: The index of the simulation to optimise. This should be None if normal optimisation is desired.
376 @type sim_index: None or int
377 @keyword lower: The lower bounds of the grid search which must be equal to the number of parameters in the model. This optional argument is only used when doing a grid search.
378 @type lower: array of numbers
379 @keyword upper: The upper bounds of the grid search which must be equal to the number of parameters in the model. This optional argument is only used when doing a grid search.
380 @type upper: array of numbers
381 @keyword inc: The increments for each dimension of the space for the grid search. The number of elements in the array must equal to the number of parameters in the model. This argument is only used when doing a grid search.
382 @type inc: array of int
383 """
384
385
386 raise RelaxImplementError('minimise')
387
388
390 """Return a description of the model.
391
392 @param model_info: The model index from model_info().
393 @type model_info: int
394 @return: The model description.
395 @rtype: str
396 """
397
398
399 raise RelaxImplementError('model_desc')
400
401
403 """Generator method for looping over the models.
404
405 @return: Information identifying the model.
406 @rtype: anything
407 """
408
409
410 raise RelaxImplementError('model_loop')
411
412
414 """Return the k, n, and chi2 model statistics.
415
416 k - number of parameters.
417 n - number of data points.
418 chi2 - the chi-squared value.
419
420
421 @keyword model_info: The model information originating from model_loop().
422 @type model_info: unknown
423 @keyword spin_id: The spin ID string to override the model_info argument. This is ignored in the N-state model.
424 @type spin_id: None or str
425 @keyword global_stats: A parameter which determines if global or local statistics are returned. For the N-state model, this argument is ignored.
426 @type global_stats: None or bool
427 @return: The optimisation statistics, in tuple format, of the number of parameters (k), the number of data points (n), and the chi-squared value (chi2).
428 @rtype: tuple of (int, int, float)
429 """
430
431
432 raise RelaxImplementError('model_statistics')
433
434
436 """Return the type of the model, either being 'local' or 'global'.
437
438 @return: The model type, one of 'local' or 'global'.
439 @rtype: str
440 """
441
442
443 raise RelaxImplementError('model_type')
444
445
446 - def molmol_macro(self, data_type, style=None, colour_start=None, colour_end=None, colour_list=None, spin_id=None):
447 """Create and return an array of Molmol macros.
448
449 @param data_type: The parameter name or data type.
450 @type data_type: str
451 @keyword style: The Molmol style.
452 @type style: None or str
453 @keyword colour_start: The starting colour (must be a MOLMOL or X11 name).
454 @type colour_start: str
455 @keyword colour_end: The ending colour (must be a MOLMOL or X11 name).
456 @type colour_end: str
457 @keyword colour_list: The colour list used, either 'molmol' or 'x11'.
458 @type colour_list: str
459 @keyword spin_id: The spin identification string.
460 @type spin_id: str
461 """
462
463
464 raise RelaxImplementError('molmol_macro')
465
466
468 """Return the number of instances (depreciated).
469
470 @return: The number of instances.
471 @rtype: int
472 """
473
474
475 raise RelaxImplementError('num_instances')
476
477
479 """Deselect models with insufficient data for minimisation.
480
481 @keyword data_check: A flag to signal if the presence of base data is to be checked for.
482 @type data_check: bool
483 @keyword verbose: A flag which if True will allow printouts.
484 @type verbose: bool
485 """
486
487
488 raise RelaxImplementError('overfit_deselect')
489
490
491 - def pymol_macro(self, data_type, style=None, colour_start=None, colour_end=None, colour_list=None, spin_id=None):
492 """Create and return an array of PyMOL macros.
493
494 @param data_type: The parameter name or data type.
495 @type data_type: str
496 @keyword style: The PyMOL style.
497 @type style: None or str
498 @keyword colour_start: The starting colour (must be a MOLMOL or X11 name).
499 @type colour_start: str
500 @keyword colour_end: The ending colour (must be a MOLMOL or X11 name).
501 @type colour_end: str
502 @keyword colour_list: The colour list used, either 'molmol' or 'x11'.
503 @type colour_list: str
504 @keyword spin_id: The spin identification string.
505 @type spin_id: str
506 """
507
508
509 raise RelaxImplementError('pymol_macro')
510
511
513 """Return the conversion factor.
514
515 @param param: The parameter name.
516 @type param: str
517 @return: A conversion factor of 1.0.
518 @rtype: float
519 """
520
521
522 return self._PARAMS.conversion_factor(param)
523
524
526 """Return the data points used in optimisation.
527
528 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method.
529 @type data_id: anything
530 @return: The array of data values.
531 @rtype: list of float
532 """
533
534
535 raise RelaxImplementError('return_data')
536
537
539 """Return a description of the parameter.
540
541 This basic method will first search for a global parameter and, if not found, then a spin parameter.
542
543
544 @param name: The name or description of the parameter.
545 @type name: str
546 @return: The object description, or None.
547 @rtype: str or None
548 """
549
550
551 return self._PARAMS.description(name)
552
553
555 """Return the error points corresponding to the data points used in optimisation.
556
557 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method.
558 @type data_id: anything
559 @return: The array of data error values.
560 @rtype: list of float
561 """
562
563
564 raise RelaxImplementError('return_error')
565
566
568 """Return the Grace string representation of the parameter.
569
570 This is used for axis labelling.
571
572
573 @param param: The specific analysis parameter.
574 @type param: str
575 @return: The Grace string representation of the parameter.
576 @rtype: str
577 """
578
579
580 return self._PARAMS.grace_string(param)
581
582
584 """Return a string representing the parameters units.
585
586 @param param: The name of the parameter to return the units string for.
587 @type param: str
588 @return: The parameter units string.
589 @rtype: str
590 """
591
592
593 return self._PARAMS.units(param)
594
595
597 """Return the value and error corresponding to the parameter.
598
599 If sim is set to an integer, return the value of the simulation and None.
600
601
602 @param spin: The SpinContainer object.
603 @type spin: SpinContainer
604 @param param: The name of the parameter to return values for.
605 @type param: str
606 @keyword sim: The Monte Carlo simulation index.
607 @type sim: None or int
608 @keyword bc: The back-calculated data flag. If True, then the back-calculated data will be returned rather than the actual data.
609 @type bc: bool
610 @return: The value and error corresponding to
611 @rtype: tuple of length 2 of floats or None
612 """
613
614
615 raise RelaxImplementError('return_value')
616
617
618 - def set_error(self, model_info, index, error):
619 """Set the model parameter errors.
620
621 @param model_info: The model information originating from model_loop().
622 @type model_info: unknown
623 @param index: The index of the parameter to set the errors for.
624 @type index: int
625 @param error: The error value.
626 @type error: float
627 """
628
629
630 raise RelaxImplementError('set_error')
631
632
633 - def set_param_values(self, param=None, value=None, index=None, spin_id=None, error=False, force=True):
634 """Set the model parameter values.
635
636 @keyword param: The parameter name list.
637 @type param: list of str
638 @keyword value: The parameter value list.
639 @type value: list
640 @keyword index: The index for parameters which are of the list-type. This is ignored for all other types.
641 @type index: None or int
642 @keyword spin_id: The spin identification string, only used for spin specific parameters.
643 @type spin_id: None or str
644 @keyword error: A flag which if True will allow the parameter errors to be set instead of the values.
645 @type error: bool
646 @keyword force: A flag which if True will cause current values to be overwritten. If False, a RelaxError will raised if the parameter value is already set.
647 @type force: bool
648 """
649
650
651 raise RelaxImplementError('set_param_values')
652
653
655 """Set the simulation selection flag.
656
657 @param model_info: The model information originating from model_loop().
658 @type model_info: unknown
659 @param select_sim: The selection flag for the simulations.
660 @type select_sim: bool
661 """
662
663
664 raise RelaxImplementError('set_selected_sim')
665
666
668 """Update other parameter values.
669
670 @param param: The name of the parameter which has been changed.
671 @type param: str
672 @param spin: The SpinContainer object.
673 @type spin: SpinContainer
674 """
675
676
677 raise RelaxImplementError('set_update')
678
679
681 """Initialise the Monte Carlo parameter values."""
682
683
684 raise RelaxImplementError('sim_init_values')
685
686
688 """Pack the Monte Carlo simulation data.
689
690 @param data_id: The data identification information, as yielded by the base_data_loop() generator method.
691 @type data_id: anything
692 @param sim_data: The Monte Carlo simulation data.
693 @type sim_data: list of float
694 """
695
696
697 raise RelaxImplementError('sim_pack_data')
698
699
701 """Return the simulation chi-squared values.
702
703 @param model_info: The model information originating from model_loop().
704 @type model_info: unknown
705 @keyword index: The optional simulation index.
706 @type index: int
707 @return: The list of simulation chi-squared values. If the index is supplied, only a single value will be returned.
708 @rtype: list of float or float
709 """
710
711
712 raise RelaxImplementError('sim_return_chi2')
713
714
716 """Return the array of simulation parameter values.
717
718 @param model_info: The model information originating from model_loop().
719 @type model_info: unknown
720 @param index: The index of the parameter to return the array of values for.
721 @type index: int
722 @return: The array of simulation parameter values.
723 @rtype: list of float
724 """
725
726
727 raise RelaxImplementError('sim_return_param')
728
729
731 """Return the array of selected simulation flags for the spin.
732
733 @param model_info: The model information originating from model_loop().
734 @type model_info: unknown
735 @return: The array of selected simulation flags.
736 @rtype: list of int
737 """
738
739
740 raise RelaxImplementError('sim_return_selected')
741
742
744 """Skip certain data.
745
746 @param model_info: The model index from model_loop().
747 @type model_info: int
748 @return: True if the data should be skipped, False otherwise.
749 @rtype: bool
750 """
751
752
753 return False
754