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, scaling_matrix=None, verbosity=1, sim_index=None):
108 """Calculate the chi-squared value.
109
110 @keyword spin_id: The spin ID string.
111 @type spin_id: None or str
112 @keyword scaling_matrix: The per-model list of diagonal and square scaling matrices.
113 @type scaling_matrix: list of numpy rank-2, float64 array or list of None
114 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
115 @type verbosity: int
116 @keyword sim_index: The optional MC simulation index.
117 @type sim_index: None or int
118 """
119
120
121 raise RelaxImplementError('calculate')
122
123
125 """Return the optimisation constraint algorithm, defaulting to the Method of Multipliers.
126
127 This can return one of:
128
129 - 'Method of Multipliers',
130 - 'Log barrier'.
131
132
133 @return: The constraint algorithm to use (one of 'Method of Multipliers' or 'Log barrier').
134 @rtype: str
135 """
136
137
138 return 'Method of Multipliers'
139
140
142 """Return the Jacobian and weights required for parameter errors via the covariance matrix.
143
144 @keyword model_info: The model information from model_loop().
145 @type model_info: unknown
146 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
147 @type verbosity: int
148 @return: The Jacobian and weight matrices for the given model.
149 @rtype: numpy rank-2 array, numpy rank-2 array
150 """
151
152
153 raise RelaxImplementError('covariance_matrix')
154
155
157 """Create the Monte Carlo data.
158
159 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method.
160 @type data_id: anything
161 @return: The Monte Carlo simulation data.
162 @rtype: list of floats
163 """
164
165
166 raise RelaxImplementError('create_mc_data')
167
168
170 """Initialise the data structures.
171
172 @param data: The data from the base_data_loop() method.
173 @type data: unknown
174 @keyword sim: The Monte Carlo simulation flag, which if true will initialise the simulation data structure.
175 @type sim: bool
176 """
177
178
179 raise RelaxImplementError('data_init')
180
181
182 - def data_names(self, set='all', scope=None, error_names=False, sim_names=False):
183 """Return a list of names of data structures.
184
185 @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.
186 @type set: str
187 @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.
188 @type scope: str or None
189 @keyword error_names: A flag which if True will add the error object names as well.
190 @type error_names: bool
191 @keyword sim_names: A flag which if True will add the Monte Carlo simulation object names as well.
192 @type sim_names: bool
193 @return: The list of object names.
194 @rtype: list of str
195 """
196
197
198 return self._PARAMS.data_names(set=set, scope=scope, error_names=error_names, sim_names=sim_names)
199
200
202 """Return the type of data that the parameter should be.
203
204 This basic method will first search for a global parameter and, if not found, then a spin parameter.
205
206 @keyword param: The parameter name.
207 @type param: list of str
208 @return: The type of the parameter. I.e. the special Python type objects of int, float, str, bool, [str], {bool}, etc.
209 @rtype: any type
210 """
211
212
213 return self._PARAMS.type(param)
214
215
217 """Return the default parameter values.
218
219 This basic method will first search for a global parameter and, if not found, then a spin parameter.
220
221
222 @param param: The specific analysis parameter.
223 @type param: str
224 @return: The default value.
225 @rtype: float
226 """
227
228
229 return self._PARAMS.default_value(param)
230
231
232 - def deselect(self, sim_index=None, model_info=None):
233 """Deselect models or simulations.
234
235 @keyword sim_index: The optional Monte Carlo simulation index. If None, then models will be deselected, otherwise the given simulation will.
236 @type sim_index: None or int
237 @keyword model_info: The model information from model_loop().
238 @type model_info: unknown
239 """
240
241
242 raise RelaxImplementError('deselect')
243
244
245 - def duplicate_data(self, pipe_from=None, pipe_to=None, model_info=None, global_stats=False, verbose=True):
246 """Duplicate the data specific to a single model.
247
248 @keyword pipe_from: The data pipe to copy the data from.
249 @type pipe_from: str
250 @keyword pipe_to: The data pipe to copy the data to.
251 @type pipe_to: str
252 @keyword model_info: The model information from model_loop().
253 @type model_info: unknown
254 @keyword global_stats: The global statistics flag.
255 @type global_stats: bool
256 @keyword verbose: A flag which if True will cause info to be printed out.
257 @type verbose: bool
258 """
259
260
261 raise RelaxImplementError('duplicate_data')
262
263
264 - def eliminate(self, name, value, args, sim=None, model_info=None):
265 """Model elimination method.
266
267 @param name: The parameter name.
268 @type name: str
269 @param value: The parameter value.
270 @type value: float
271 @param args: The elimination constant overrides.
272 @type args: None or tuple of float
273 @keyword sim: The Monte Carlo simulation index.
274 @type sim: int
275 @keyword model_info: The model information from model_loop().
276 @type model_info: unknown
277 @return: True if the model is to be eliminated, False otherwise.
278 @rtype: bool
279 """
280
281
282 raise RelaxImplementError('eliminate')
283
284
286 """Return the data container for the model.
287
288 @keyword model_info: The model information from model_loop().
289 @type model_info: unknown
290 @return: The data container corresponding to the model.
291 @rtype: class instance
292 """
293
294
295 raise RelaxImplementError('get_model_container')
296
297
299 """Return a vector of parameter names.
300
301 @keyword model_info: The model information from model_loop().
302 @type model_info: unknown
303 @return: The vector of parameter names.
304 @rtype: list of str
305 """
306
307
308 raise RelaxImplementError('get_param_names')
309
310
312 """Return a vector of parameter values.
313
314 @keyword model_info: The model information from model_loop().
315 @type model_info: unknown
316 @keyword sim_index: The optional Monte Carlo simulation index.
317 @type sim_index: int
318 @return: The vector of parameter values.
319 @rtype: list of str
320 """
321
322
323 raise RelaxImplementError('get_param_values')
324
325
326 - def grid_search(self, lower=None, upper=None, inc=None, scaling_matrix=None, constraints=True, verbosity=1, sim_index=None):
327 """Grid search method.
328
329 @keyword lower: The per-model lower bounds of the grid search which must be equal to the number of parameters in the model.
330 @type lower: list of lists of floats
331 @keyword upper: The per-model upper bounds of the grid search which must be equal to the number of parameters in the model.
332 @type upper: list of lists of floats
333 @keyword inc: The per-model 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.
334 @type inc: list of lists of int
335 @keyword scaling_matrix: The per-model list of diagonal and square scaling matrices.
336 @type scaling_matrix: list of numpy rank-2, float64 array or list of None
337 @keyword constraints: If True, constraints are applied during the grid search (eliminating parts of the grid). If False, no constraints are used.
338 @type constraints: bool
339 @keyword verbosity: A flag specifying the amount of information to print. The higher the value, the greater the verbosity.
340 @type verbosity: int
341 @keyword sim_index: The index of the simulation to apply the grid search to. If None, the normal model is optimised.
342 @type sim_index: int
343 """
344
345
346 raise RelaxImplementError('grid_search')
347
348
350 """Test if errors exist for the current data pipe.
351
352 @return: The answer to the question of whether errors exist.
353 @rtype: bool
354 """
355
356
357 raise RelaxImplementError('has_errors')
358
359
361 """Determine whether the given parameter is spin specific.
362
363 @param name: The name of the parameter.
364 @type name: str
365 @return: True if the parameter is spin specific, False otherwise.
366 @rtype: bool
367 """
368
369
370 return self._PARAMS.is_spin_param(name)
371
372
374 """Create bounds for the OpenDX mapping function.
375
376 @param param: The name of the parameter to return the lower and upper bounds of.
377 @type param: str
378 @param spin_id: The spin identification string.
379 @type spin_id: None or str
380 @return: The upper and lower bounds of the parameter.
381 @rtype: list of float
382 """
383
384
385 raise RelaxImplementError('map_bounds')
386
387
388 - def minimise(self, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=False, scaling_matrix=None, verbosity=0, sim_index=None, lower=None, upper=None, inc=None):
389 """Minimisation method.
390
391 @keyword min_algor: The minimisation algorithm to use.
392 @type min_algor: str
393 @keyword min_options: An array of options to be used by the minimisation algorithm.
394 @type min_options: array of str
395 @keyword func_tol: The function tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
396 @type func_tol: None or float
397 @keyword grad_tol: The gradient tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
398 @type grad_tol: None or float
399 @keyword max_iterations: The maximum number of iterations for the algorithm.
400 @type max_iterations: int
401 @keyword constraints: If True, constraints are used during optimisation.
402 @type constraints: bool
403 @keyword scaling_matrix: The per-model list of diagonal and square scaling matrices.
404 @type scaling_matrix: list of numpy rank-2, float64 array or list of None
405 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
406 @type verbosity: int
407 @keyword sim_index: The index of the simulation to optimise. This should be None if normal optimisation is desired.
408 @type sim_index: None or int
409 @keyword lower: The per-model 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.
410 @type lower: list of lists of float
411 @keyword upper: The per-model 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.
412 @type upper: list of lists of float
413 @keyword inc: The per-model 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.
414 @type inc: list of lists of int
415 """
416
417
418 raise RelaxImplementError('minimise')
419
420
422 """Return a description of the model.
423
424 @keyword model_info: The model information from model_loop().
425 @type model_info: unknown
426 @return: The model description.
427 @rtype: str
428 """
429
430
431 raise RelaxImplementError('model_desc')
432
433
435 """Generator method for looping over the models.
436
437 @return: Information identifying the model.
438 @rtype: anything
439 """
440
441
442 raise RelaxImplementError('model_loop')
443
444
446 """Return the k, n, and chi2 model statistics.
447
448 k - number of parameters.
449 n - number of data points.
450 chi2 - the chi-squared value.
451
452
453 @keyword model_info: The model information from model_loop().
454 @type model_info: unknown
455 @keyword spin_id: The spin ID string to override the model_info argument. This is ignored in the N-state model.
456 @type spin_id: None or str
457 @keyword global_stats: A parameter which determines if global or local statistics are returned. For the N-state model, this argument is ignored.
458 @type global_stats: None or bool
459 @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).
460 @rtype: tuple of (int, int, float)
461 """
462
463
464 raise RelaxImplementError('model_statistics')
465
466
468 """Return the type of the model, either being 'local' or 'global'.
469
470 @return: The model type, one of 'local' or 'global'.
471 @rtype: str
472 """
473
474
475 raise RelaxImplementError('model_type')
476
477
478 - def molmol_macro(self, data_type, style=None, colour_start=None, colour_end=None, colour_list=None, spin_id=None):
479 """Create and return an array of Molmol macros.
480
481 @param data_type: The parameter name or data type.
482 @type data_type: str
483 @keyword style: The Molmol style.
484 @type style: None or str
485 @keyword colour_start: The starting colour (must be a MOLMOL or X11 name).
486 @type colour_start: str
487 @keyword colour_end: The ending colour (must be a MOLMOL or X11 name).
488 @type colour_end: str
489 @keyword colour_list: The colour list used, either 'molmol' or 'x11'.
490 @type colour_list: str
491 @keyword spin_id: The spin identification string.
492 @type spin_id: str
493 """
494
495
496 raise RelaxImplementError('molmol_macro')
497
498
500 """Return the number of instances (depreciated).
501
502 @return: The number of instances.
503 @rtype: int
504 """
505
506
507 raise RelaxImplementError('num_instances')
508
509
511 """Deselect models with insufficient data for minimisation.
512
513 @keyword data_check: A flag to signal if the presence of base data is to be checked for.
514 @type data_check: bool
515 @keyword verbose: A flag which if True will allow printouts.
516 @type verbose: bool
517 """
518
519
520 raise RelaxImplementError('overfit_deselect')
521
522
524 """Print out the model title.
525
526 @keyword prefix: The starting text of the title. This should be printed out first, followed by the model information text.
527 @type prefix: str
528 @keyword model_info: The model information from model_loop().
529 @type model_info: unknown
530 """
531
532
533 raise RelaxImplementError('print_model_title')
534
535
536 - def pymol_macro(self, data_type, style=None, colour_start=None, colour_end=None, colour_list=None, spin_id=None):
537 """Create and return an array of PyMOL macros.
538
539 @param data_type: The parameter name or data type.
540 @type data_type: str
541 @keyword style: The PyMOL style.
542 @type style: None or str
543 @keyword colour_start: The starting colour (must be a MOLMOL or X11 name).
544 @type colour_start: str
545 @keyword colour_end: The ending colour (must be a MOLMOL or X11 name).
546 @type colour_end: str
547 @keyword colour_list: The colour list used, either 'molmol' or 'x11'.
548 @type colour_list: str
549 @keyword spin_id: The spin identification string.
550 @type spin_id: str
551 """
552
553
554 raise RelaxImplementError('pymol_macro')
555
556
558 """Return the conversion factor.
559
560 @param param: The parameter name.
561 @type param: str
562 @return: A conversion factor of 1.0.
563 @rtype: float
564 """
565
566
567 return self._PARAMS.conversion_factor(param)
568
569
571 """Return the data points used in optimisation.
572
573 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method.
574 @type data_id: anything
575 @return: The array of data values.
576 @rtype: list of float
577 """
578
579
580 raise RelaxImplementError('return_data')
581
582
584 """Return a description of the parameter.
585
586 This basic method will first search for a global parameter and, if not found, then a spin parameter.
587
588
589 @param name: The name or description of the parameter.
590 @type name: str
591 @return: The object description, or None.
592 @rtype: str or None
593 """
594
595
596 return self._PARAMS.description(name)
597
598
600 """Return the error points corresponding to the data points used in optimisation.
601
602 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method.
603 @type data_id: anything
604 @return: The array of data error values.
605 @rtype: list of float
606 """
607
608
609 raise RelaxImplementError('return_error')
610
611
613 """Return the error points corresponding to the overall gauss distribution described by the STD_fit of the goodness of fit, where STD_fit = sqrt(chi2/(N-p)).
614
615 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method.
616 @type data_id: anything
617 @return: The array of data error values.
618 @rtype: list of float
619 """
620
621
622 raise RelaxImplementError('return_error_red_chi2')
623
624
626 """Return the Grace string representation of the parameter.
627
628 This is used for axis labelling.
629
630
631 @param param: The specific analysis parameter.
632 @type param: str
633 @return: The Grace string representation of the parameter.
634 @rtype: str
635 """
636
637
638 return self._PARAMS.grace_string(param)
639
640
642 """Return a string representing the parameters units.
643
644 @param param: The name of the parameter to return the units string for.
645 @type param: str
646 @return: The parameter units string.
647 @rtype: str
648 """
649
650
651 return self._PARAMS.units(param)
652
653
655 """Return the value and error corresponding to the parameter.
656
657 If sim is set to an integer, return the value of the simulation and None.
658
659
660 @param spin: The SpinContainer object.
661 @type spin: SpinContainer
662 @param param: The name of the parameter to return values for.
663 @type param: str
664 @keyword sim: The Monte Carlo simulation index.
665 @type sim: None or int
666 @keyword bc: The back-calculated data flag. If True, then the back-calculated data will be returned rather than the actual data.
667 @type bc: bool
668 @return: The value and error corresponding to
669 @rtype: tuple of length 2 of floats or None
670 """
671
672
673 raise RelaxImplementError('return_value')
674
675
676 - def set_error(self, index, error, model_info=None):
677 """Set the model parameter errors.
678
679 @param index: The index of the parameter to set the errors for.
680 @type index: int
681 @param error: The error value.
682 @type error: float
683 @keyword model_info: The model information from model_loop().
684 @type model_info: unknown
685 """
686
687
688 raise RelaxImplementError('set_error')
689
690
691 - def set_param_values(self, param=None, value=None, index=None, spin_id=None, error=False, force=True):
692 """Set the model parameter values.
693
694 @keyword param: The parameter name list.
695 @type param: list of str
696 @keyword value: The parameter value list.
697 @type value: list
698 @keyword index: The index for parameters which are of the list-type. This is ignored for all other types.
699 @type index: None or int
700 @keyword spin_id: The spin identification string, only used for spin specific parameters.
701 @type spin_id: None or str
702 @keyword error: A flag which if True will allow the parameter errors to be set instead of the values.
703 @type error: bool
704 @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.
705 @type force: bool
706 """
707
708
709 raise RelaxImplementError('set_param_values')
710
711
713 """Set the simulation selection flag.
714
715 @param select_sim: The selection flag for the simulations.
716 @type select_sim: bool
717 @keyword model_info: The model information from model_loop().
718 @type model_info: unknown
719 """
720
721
722 raise RelaxImplementError('set_selected_sim')
723
724
726 """Update other parameter values.
727
728 @param param: The name of the parameter which has been changed.
729 @type param: str
730 @param spin: The SpinContainer object.
731 @type spin: SpinContainer
732 """
733
734
735 raise RelaxImplementError('set_update')
736
737
739 """Initialise the Monte Carlo parameter values."""
740
741
742 raise RelaxImplementError('sim_init_values')
743
744
746 """Pack the Monte Carlo simulation data.
747
748 @param data_id: The data identification information, as yielded by the base_data_loop() generator method.
749 @type data_id: anything
750 @param sim_data: The Monte Carlo simulation data.
751 @type sim_data: list of float
752 """
753
754
755 raise RelaxImplementError('sim_pack_data')
756
757
759 """Return the simulation chi-squared values.
760
761 @keyword index: The optional simulation index.
762 @type index: int
763 @keyword model_info: The model information from model_loop().
764 @type model_info: unknown
765 @return: The list of simulation chi-squared values. If the index is supplied, only a single value will be returned.
766 @rtype: list of float or float
767 """
768
769
770 raise RelaxImplementError('sim_return_chi2')
771
772
774 """Return the array of simulation parameter values.
775
776 @param index: The index of the parameter to return the array of values for.
777 @type index: int
778 @keyword model_info: The model information from model_loop().
779 @type model_info: unknown
780 @return: The array of simulation parameter values.
781 @rtype: list of float
782 """
783
784
785 raise RelaxImplementError('sim_return_param')
786
787
789 """Return the array of selected simulation flags for the spin.
790
791 @keyword model_info: The model information from model_loop().
792 @type model_info: unknown
793 @return: The array of selected simulation flags.
794 @rtype: list of int
795 """
796
797
798 raise RelaxImplementError('sim_return_selected')
799
800
802 """Skip certain data.
803
804 @keyword model_info: The model information from model_loop().
805 @type model_info: unknown
806 @return: True if the data should be skipped, False otherwise.
807 @rtype: bool
808 """
809
810
811 return False
812