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