Package specific_analyses :: Module api_base
[hide private]
[frames] | no frames]

Source Code for Module specific_analyses.api_base

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2004-2014 Edward d'Auvergne                                   # 
  4  #                                                                             # 
  5  # This file is part of the program relax (http://www.nmr-relax.com).          # 
  6  #                                                                             # 
  7  # This program is free software: you can redistribute it and/or modify        # 
  8  # it under the terms of the GNU General Public License as published by        # 
  9  # the Free Software Foundation, either version 3 of the License, or           # 
 10  # (at your option) any later version.                                         # 
 11  #                                                                             # 
 12  # This program is distributed in the hope that it will be useful,             # 
 13  # but WITHOUT ANY WARRANTY; without even the implied warranty of              # 
 14  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the               # 
 15  # GNU General Public License for more details.                                # 
 16  #                                                                             # 
 17  # You should have received a copy of the GNU General Public License           # 
 18  # along with this program.  If not, see <http://www.gnu.org/licenses/>.       # 
 19  #                                                                             # 
 20  ############################################################################### 
 21   
 22  # Module docstring. 
 23  """The module defining the analysis specific API.""" 
 24   
 25  # relax module imports. 
 26  from lib.errors import RelaxImplementError 
 27   
 28   
29 -class API_base(object):
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 # Class variable for storing the class instance (for the singleton design pattern). 36 instance = None 37
38 - def __new__(self, *args, **kargs):
39 """Replacement function for implementing the singleton design pattern.""" 40 41 # First initialisation. 42 if self.instance is None: 43 # Create a new instance. 44 self.instance = object.__new__(self, *args, **kargs) 45 46 # Already initialised, so return the instance. 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 # Not implemented. 66 raise RelaxImplementError('back_calc_ri')
67 68
69 - def base_data_loop(self):
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 # Not implemented. 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 # Not implemented. 91 raise RelaxImplementError('bmrb_read')
92 93
94 - def bmrb_write(self, file_path, version=None):
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 # Not implemented. 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 # Not implemented. 119 raise RelaxImplementError('calculate')
120 121
122 - def constraint_algorithm(self):
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 # The default. 136 return 'Method of Multipliers'
137 138
139 - def create_mc_data(self, data_id=None):
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 # Not implemented. 149 raise RelaxImplementError('create_mc_data')
150 151
152 - def data_init(self, data_cont, sim=False):
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 # Not implemented. 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 # Return the names. 181 return self._PARAMS.data_names(set=set, scope=scope, error_names=error_names, sim_names=sim_names)
182 183
184 - def data_type(self, param=None):
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 # Return the type. 196 return self._PARAMS.type(param)
197 198
199 - def default_value(self, param):
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 # Return the value. 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 # Not implemented. 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 # Not implemented. 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 # Not implemented. 265 raise RelaxImplementError('eliminate')
266 267
268 - def get_param_names(self, model_info=None):
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 # Not implemented. 278 raise RelaxImplementError('get_param_names')
279 280
281 - def get_param_values(self, model_info=None, sim_index=None):
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 # Not implemented. 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 # Not implemented. 314 raise RelaxImplementError('grid_search')
315 316
317 - def has_errors(self):
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 # Not implemented. 325 raise RelaxImplementError('has_errors')
326 327
328 - def is_spin_param(self, name):
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 # Return the result. 338 return self._PARAMS.is_spin_param(name)
339 340
341 - def map_bounds(self, param, spin_id=None):
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 # Not implemented. 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 # Not implemented. 386 raise RelaxImplementError('minimise')
387 388
389 - def model_desc(self, model_info):
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 # Not implemented. 399 raise RelaxImplementError('model_desc')
400 401
402 - def model_loop(self):
403 """Generator method for looping over the models. 404 405 @return: Information identifying the model. 406 @rtype: anything 407 """ 408 409 # Not implemented. 410 raise RelaxImplementError('model_loop')
411 412
413 - def model_statistics(self, model_info=None, spin_id=None, global_stats=None):
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 # Not implemented. 432 raise RelaxImplementError('model_statistics')
433 434
435 - def model_type(self):
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 # Not implemented. 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 # Not implemented. 464 raise RelaxImplementError('molmol_macro')
465 466
467 - def num_instances(self):
468 """Return the number of instances (depreciated). 469 470 @return: The number of instances. 471 @rtype: int 472 """ 473 474 # Not implemented. 475 raise RelaxImplementError('num_instances')
476 477
478 - def overfit_deselect(self, data_check=True, verbose=True):
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 # Not implemented. 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 # Not implemented. 509 raise RelaxImplementError('pymol_macro')
510 511
512 - def return_conversion_factor(self, param):
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 # Return the factor. 522 return self._PARAMS.conversion_factor(param)
523 524
525 - def return_data(self, data_id=None):
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 # Not implemented. 535 raise RelaxImplementError('return_data')
536 537
538 - def return_data_desc(self, name):
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 # Return the description. 551 return self._PARAMS.description(name)
552 553
554 - def return_error(self, data_id=None):
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 # Not implemented. 564 raise RelaxImplementError('return_error')
565 566
567 - def return_grace_string(self, param):
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 # The string. 580 return self._PARAMS.grace_string(param)
581 582
583 - def return_units(self, param):
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 # Return the name. 593 return self._PARAMS.units(param)
594 595
596 - def return_value(self, spin, param, sim=None, bc=False):
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 # Not implemented. 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 # Not implemented. 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 # Not implemented. 651 raise RelaxImplementError('set_param_values')
652 653
654 - def set_selected_sim(self, model_info, select_sim):
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 # Not implemented. 664 raise RelaxImplementError('set_selected_sim')
665 666
667 - def set_update(self, param, spin):
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 # Not implemented. 677 raise RelaxImplementError('set_update')
678 679
680 - def sim_init_values(self):
681 """Initialise the Monte Carlo parameter values.""" 682 683 # Not implemented. 684 raise RelaxImplementError('sim_init_values')
685 686
687 - def sim_pack_data(self, data_id, sim_data):
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 # Not implemented. 697 raise RelaxImplementError('sim_pack_data')
698 699
700 - def sim_return_chi2(self, model_info, index=None):
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 # Not implemented. 712 raise RelaxImplementError('sim_return_chi2')
713 714
715 - def sim_return_param(self, model_info, index):
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 # Not implemented. 727 raise RelaxImplementError('sim_return_param')
728 729
730 - def sim_return_selected(self, model_info):
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 # Not implemented. 740 raise RelaxImplementError('sim_return_selected')
741 742
743 - def skip_function(self, model_info):
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 # Never skip. 753 return False
754