specific_analyses.api

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 # Empty documentation strings. 37 default_value_doc = "" 38 eliminate_doc = "" 39 return_data_name_doc = "" 40 set_doc = "" 41 write_doc = "" 42 43

44 - def __init__(self):

45 """Set up the specific objects.""" 46 47 # Class variables. 48 self.PARAMS = Param_list()

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 # Not implemented. 67 raise RelaxImplementError('back_calc_ri')

68 69

70 - def base_data_loop(self):

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 # Not implemented. 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 # Not implemented. 92 raise RelaxImplementError('bmrb_read')

93 94

95 - def bmrb_write(self, file_path, version=None):

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 # Not implemented. 105 raise RelaxImplementError('bmrb_write')

106 107

108 - def calculate(self, spin_id=None, verbosity=1, sim_index=None):

109 """Calculate the chi-squared value. 110 111 @keyword spin_id: The spin identification string. 112 @type spin_id: None or str 113 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity. 114 @type verbosity: int 115 @keyword sim_index: The optional MC simulation index. 116 @type sim_index: None or int 117 """ 118 119 # Not implemented. 120 raise RelaxImplementError('calculate')

121 122

123 - def constraint_algorithm(self):

124 """Return the optimisation constraint algorithm, defaulting to the Method of Multipliers. 125 126 This can return one of: 127 128 - 'Method of Multipliers', 129 - 'Log barrier'. 130 131 132 @return: The constraint algorithm to use (one of 'Method of Multipliers' or 'Log barrier'). 133 @rtype: str 134 """ 135 136 # The default. 137 return 'Method of Multipliers'

138 139

140 - def create_mc_data(self, data_id=None):

141 """Create the Monte Carlo data. 142 143 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method. 144 @type data_id: anything 145 @return: The Monte Carlo simulation data. 146 @rtype: list of floats 147 """ 148 149 # Not implemented. 150 raise RelaxImplementError('create_mc_data')

151 152

153 - def data_init(self, data_cont, sim=False):

154 """Initialise the data structures. 155 156 @param data_cont: The data container. 157 @type data_cont: instance 158 @keyword sim: The Monte Carlo simulation flag, which if true will initialise the simulation data structure. 159 @type sim: bool 160 """ 161 162 # Not implemented. 163 raise RelaxImplementError('data_init')

164 165

166 - def data_names(self, set='all', scope=None, error_names=False, sim_names=False):

167 """Return a list of names of data structures. 168 169 @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. 170 @type set: str 171 @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. 172 @type scope: str or None 173 @keyword error_names: A flag which if True will add the error object names as well. 174 @type error_names: bool 175 @keyword sim_names: A flag which if True will add the Monte Carlo simulation object names as well. 176 @type sim_names: bool 177 @return: The list of object names. 178 @rtype: list of str 179 """ 180 181 # Initialise. 182 names = [] 183 184 # Loop over the parameters. 185 for name in self.PARAMS.loop(set=set, scope=scope, error_names=error_names, sim_names=sim_names): 186 names.append(name) 187 188 # Return the names. 189 return names

190 191

192 - def data_type(self, param=None):

193 """Return the type of data that the parameter should be. 194 195 This basic method will first search for a global parameter and, if not found, then a spin parameter. 196 197 @keyword param: The parameter name. 198 @type param: list of str 199 @return: The type of the parameter. I.e. the special Python type objects of int, float, str, bool, [str], {bool}, etc. 200 @rtype: any type 201 """ 202 203 # Return the type. 204 return self.PARAMS.get_type(param)

205 206

207 - def default_value(self, param):

208 """Return the default parameter values. 209 210 This basic method will first search for a global parameter and, if not found, then a spin parameter. 211 212 213 @param param: The specific analysis parameter. 214 @type param: str 215 @return: The default value. 216 @rtype: float 217 """ 218 219 # Return the value. 220 return self.PARAMS.get_default(param)

221 222

223 - def deselect(self, model_info, sim_index=None):

224 """Deselect models or simulations. 225 226 @param model_info: The model index from model_info(). 227 @type model_info: int 228 @keyword sim_index: The optional Monte Carlo simulation index. If None, then models will be deselected, otherwise the given simulation will. 229 @type sim_index: None or int 230 """ 231 232 # Not implemented. 233 raise RelaxImplementError('deselect')

234 235

236 - def duplicate_data(self, pipe_from=None, pipe_to=None, model_info=None, global_stats=False, verbose=True):

237 """Duplicate the data specific to a single model. 238 239 @keyword pipe_from: The data pipe to copy the data from. 240 @type pipe_from: str 241 @keyword pipe_to: The data pipe to copy the data to. 242 @type pipe_to: str 243 @keyword model_info: The model index from model_info(). 244 @type model_info: int 245 @keyword global_stats: The global statistics flag. 246 @type global_stats: bool 247 @keyword verbose: A flag which if True will cause info to be printed out. 248 @type verbose: bool 249 """ 250 251 # Not implemented. 252 raise RelaxImplementError('duplicate_data')

253 254

255 - def eliminate(self, name, value, model_info, args, sim=None):

256 """Model elimination method. 257 258 @param name: The parameter name. 259 @type name: str 260 @param value: The parameter value. 261 @type value: float 262 @param model_info: The model index from model_info(). 263 @type model_info: int 264 @param args: The elimination constant overrides. 265 @type args: None or tuple of float 266 @keyword sim: The Monte Carlo simulation index. 267 @type sim: int 268 @return: True if the model is to be eliminated, False otherwise. 269 @rtype: bool 270 """ 271 272 # Not implemented. 273 raise RelaxImplementError('eliminate')

274 275

276 - def get_param_names(self, model_info=None):

277 """Return a vector of parameter names. 278 279 @keyword model_info: The model index from model_info(). 280 @type model_info: int 281 @return: The vector of parameter names. 282 @rtype: list of str 283 """ 284 285 # Not implemented. 286 raise RelaxImplementError('get_param_names')

287 288

289 - def get_param_values(self, model_info=None, sim_index=None):

290 """Return a vector of parameter values. 291 292 @keyword model_info: The model index from model_info(). 293 @type model_info: int 294 @keyword sim_index: The optional Monte Carlo simulation index. 295 @type sim_index: int 296 @return: The vector of parameter values. 297 @rtype: list of str 298 """ 299 300 # Not implemented. 301 raise RelaxImplementError('get_param_values')

302 303

304 - def grid_search(self, lower=None, upper=None, inc=None, constraints=True, verbosity=1, sim_index=None):

305 """Grid search method. 306 307 @keyword lower: The lower bounds of the grid search which must be equal to the number of parameters in the model. 308 @type lower: array of numbers 309 @keyword upper: The upper bounds of the grid search which must be equal to the number of parameters in the model. 310 @type upper: array of numbers 311 @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. 312 @type inc: array of int 313 @keyword constraints: If True, constraints are applied during the grid search (eliminating parts of the grid). If False, no constraints are used. 314 @type constraints: bool 315 @keyword verbosity: A flag specifying the amount of information to print. The higher the value, the greater the verbosity. 316 @type verbosity: int 317 @keyword sim_index: The index of the simulation to apply the grid search to. If None, the normal model is optimised. 318 @type sim_index: int 319 """ 320 321 # Not implemented. 322 raise RelaxImplementError('grid_search')

323 324

325 - def has_errors(self):

326 """Test if errors exist for the current data pipe. 327 328 @return: The answer to the question of whether errors exist. 329 @rtype: bool 330 """ 331 332 # Not implemented. 333 raise RelaxImplementError('has_errors')

334 335

336 - def is_spin_param(self, name):

337 """Determine whether the given parameter is spin specific. 338 339 @param name: The name of the parameter. 340 @type name: str 341 @return: True if the parameter is spin specific, False otherwise. 342 @rtype: bool 343 """ 344 345 # Not implemented. 346 raise RelaxImplementError('is_spin_param')

347 348

349 - def map_bounds(self, param, spin_id=None):

350 """Create bounds for the OpenDX mapping function. 351 352 @param param: The name of the parameter to return the lower and upper bounds of. 353 @type param: str 354 @param spin_id: The spin identification string. 355 @type spin_id: None or str 356 @return: The upper and lower bounds of the parameter. 357 @rtype: list of float 358 """ 359 360 # Not implemented. 361 raise RelaxImplementError('map_bounds')

362 363

364 - 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):

365 """Minimisation method. 366 367 @keyword min_algor: The minimisation algorithm to use. 368 @type min_algor: str 369 @keyword min_options: An array of options to be used by the minimisation algorithm. 370 @type min_options: array of str 371 @keyword func_tol: The function tolerance which, when reached, terminates optimisation. Setting this to None turns of the check. 372 @type func_tol: None or float 373 @keyword grad_tol: The gradient tolerance which, when reached, terminates optimisation. Setting this to None turns of the check. 374 @type grad_tol: None or float 375 @keyword max_iterations: The maximum number of iterations for the algorithm. 376 @type max_iterations: int 377 @keyword constraints: If True, constraints are used during optimisation. 378 @type constraints: bool 379 @keyword scaling: If True, diagonal scaling is enabled during optimisation to allow the problem to be better conditioned. 380 @type scaling: bool 381 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity. 382 @type verbosity: int 383 @keyword sim_index: The index of the simulation to optimise. This should be None if normal optimisation is desired. 384 @type sim_index: None or int 385 @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. 386 @type lower: array of numbers 387 @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. 388 @type upper: array of numbers 389 @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. 390 @type inc: array of int 391 """ 392 393 # Not implemented. 394 raise RelaxImplementError('minimise')

395 396

397 - def model_desc(self, model_info):

398 """Return a description of the model. 399 400 @param model_info: The model index from model_info(). 401 @type model_info: int 402 @return: The model description. 403 @rtype: str 404 """ 405 406 # Not implemented. 407 raise RelaxImplementError('model_desc')

408 409

410 - def model_loop(self):

411 """Generator method for looping over the models. 412 413 @return: Information identifying the model. 414 @rtype: anything 415 """ 416 417 # Not implemented. 418 raise RelaxImplementError('model_loop')

419 420

421 - def model_statistics(self, model_info=None, spin_id=None, global_stats=None):

422 """Return the k, n, and chi2 model statistics. 423 424 k - number of parameters. 425 n - number of data points. 426 chi2 - the chi-squared value. 427 428 429 @keyword model_info: The model index from model_info(). 430 @type model_info: None or int 431 @keyword spin_id: The spin identification string. This is ignored in the N-state model. 432 @type spin_id: None or str 433 @keyword global_stats: A parameter which determines if global or local statistics are returned. For the N-state model, this argument is ignored. 434 @type global_stats: None or bool 435 @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). 436 @rtype: tuple of (int, int, float) 437 """ 438 439 # Not implemented. 440 raise RelaxImplementError('model_statistics')

441 442

443 - def model_type(self):

444 """Return the type of the model, either being 'local' or 'global'. 445 446 @return: The model type, one of 'local' or 'global'. 447 @rtype: str 448 """ 449 450 # Not implemented. 451 raise RelaxImplementError('model_type')

452 453

454 - def molmol_macro(self, data_type, style=None, colour_start=None, colour_end=None, colour_list=None, spin_id=None):

455 """Create and return an array of Molmol macros. 456 457 @param data_type: The parameter name or data type. 458 @type data_type: str 459 @keyword style: The Molmol style. 460 @type style: None or str 461 @keyword colour_start: The starting colour (must be a MOLMOL or X11 name). 462 @type colour_start: str 463 @keyword colour_end: The ending colour (must be a MOLMOL or X11 name). 464 @type colour_end: str 465 @keyword colour_list: The colour list used, either 'molmol' or 'x11'. 466 @type colour_list: str 467 @keyword spin_id: The spin identification string. 468 @type spin_id: str 469 """ 470 471 # Not implemented. 472 raise RelaxImplementError('molmol_macro')

473 474

475 - def num_instances(self):

476 """Return the number of instances (depreciated). 477 478 @return: The number of instances. 479 @rtype: int 480 """ 481 482 # Not implemented. 483 raise RelaxImplementError('num_instances')

484 485

486 - def overfit_deselect(self, data_check=True, verbose=True):

487 """Deselect models with insufficient data for minimisation. 488 489 @keyword data_check: A flag to signal if the presence of base data is to be checked for. 490 @type data_check: bool 491 @keyword verbose: A flag which if True will allow printouts. 492 @type verbose: bool 493 """ 494 495 # Not implemented. 496 raise RelaxImplementError('overfit_deselect')

497 498

499 - def pymol_macro(self, data_type, style=None, colour_start=None, colour_end=None, colour_list=None, spin_id=None):

500 """Create and return an array of PyMOL macros. 501 502 @param data_type: The parameter name or data type. 503 @type data_type: str 504 @keyword style: The PyMOL style. 505 @type style: None or str 506 @keyword colour_start: The starting colour (must be a MOLMOL or X11 name). 507 @type colour_start: str 508 @keyword colour_end: The ending colour (must be a MOLMOL or X11 name). 509 @type colour_end: str 510 @keyword colour_list: The colour list used, either 'molmol' or 'x11'. 511 @type colour_list: str 512 @keyword spin_id: The spin identification string. 513 @type spin_id: str 514 """ 515 516 # Not implemented. 517 raise RelaxImplementError('pymol_macro')

518 519

520 - def read_columnar_results(self, file_data, verbosity=1):

521 """Read the columnar formatted results file. 522 523 @param file_data: The processed results file data. 524 @type file_data: list of lists of str 525 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity. 526 @type verbosity: int 527 """ 528 529 # Not implemented. 530 raise RelaxImplementError('read_columnar_results')

531 532

533 - def return_conversion_factor(self, param):

534 """Return the conversion factor. 535 536 @param param: The parameter name. 537 @type param: str 538 @return: A conversion factor of 1.0. 539 @rtype: float 540 """ 541 542 # Return the factor. 543 return self.PARAMS.get_conv_factor(param)

544 545

546 - def return_data(self, data_id=None):

547 """Return the data points used in optimisation. 548 549 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method. 550 @type data_id: anything 551 @return: The array of data values. 552 @rtype: list of float 553 """ 554 555 # Not implemented. 556 raise RelaxImplementError('return_data')

557 558

559 - def return_data_desc(self, name):

560 """Return a description of the parameter. 561 562 This basic method will first search for a global parameter and, if not found, then a spin parameter. 563 564 565 @param name: The name or description of the parameter. 566 @type name: str 567 @return: The object description, or None. 568 @rtype: str or None 569 """ 570 571 # Return the description. 572 return self.PARAMS.get_desc(name)

573 574

575 - def return_data_name(self, param):

576 """Return a unique identifying string for the given parameter. 577 578 @param param: The parameter name. 579 @type param: str 580 @return: The unique parameter identifying string. 581 @rtype: str 582 """ 583 584 # No parameter. 585 if not self.PARAMS.contains(param): 586 return None 587 588 # Return the name. 589 return param

590 591

592 - def return_error(self, data_id=None):

593 """Return the error points corresponding to the data points used in optimisation. 594 595 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method. 596 @type data_id: anything 597 @return: The array of data error values. 598 @rtype: list of float 599 """ 600 601 # Not implemented. 602 raise RelaxImplementError('return_error')

603 604

605 - def return_grace_string(self, param):

606 """Return the Grace string representation of the parameter. 607 608 This is used for axis labelling. 609 610 611 @param param: The specific analysis parameter. 612 @type param: str 613 @return: The Grace string representation of the parameter. 614 @rtype: str 615 """ 616 617 # The string. 618 return self.PARAMS.get_grace_string(param)

619 620

621 - def return_units(self, param):

622 """Return a string representing the parameters units. 623 624 @param param: The name of the parameter to return the units string for. 625 @type param: str 626 @return: The parameter units string. 627 @rtype: str 628 """ 629 630 # Return the name. 631 return self.PARAMS.get_units(param)

632 633

634 - def return_value(self, spin, param, sim=None, bc=False):

635 """Return the value and error corresponding to the parameter. 636 637 If sim is set to an integer, return the value of the simulation and None. 638 639 640 @param spin: The SpinContainer object. 641 @type spin: SpinContainer 642 @param param: The name of the parameter to return values for. 643 @type param: str 644 @keyword sim: The Monte Carlo simulation index. 645 @type sim: None or int 646 @keyword bc: The back-calculated data flag. If True, then the back-calculated data will be returned rather than the actual data. 647 @type bc: bool 648 @return: The value and error corresponding to 649 @rtype: tuple of length 2 of floats or None 650 """ 651 652 # Not implemented. 653 raise RelaxImplementError('return_value')

654 655

656 - def set_error(self, model_info, index, error):

657 """Set the model parameter errors. 658 659 @param model_info: The model information originating from model_loop(). 660 @type model_info: unknown 661 @param index: The index of the parameter to set the errors for. 662 @type index: int 663 @param error: The error value. 664 @type error: float 665 """ 666 667 # Not implemented. 668 raise RelaxImplementError('set_error')

669 670

671 - def set_param_values(self, param=None, value=None, spin_id=None, error=False, force=True):

672 """Set the model parameter values. 673 674 @keyword param: The parameter name list. 675 @type param: list of str 676 @keyword value: The parameter value list. 677 @type value: list 678 @keyword spin_id: The spin identification string, only used for spin specific parameters. 679 @type spin_id: None or str 680 @keyword error: A flag which if True will allow the parameter errors to be set instead of the values. 681 @type error: bool 682 @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. 683 @type force: bool 684 """ 685 686 # Not implemented. 687 raise RelaxImplementError('set_param_values')

688 689

690 - def set_selected_sim(self, model_info, select_sim):

691 """Set the simulation selection flag. 692 693 @param model_info: The model information originating from model_loop(). 694 @type model_info: unknown 695 @param select_sim: The selection flag for the simulations. 696 @type select_sim: bool 697 """ 698 699 # Not implemented. 700 raise RelaxImplementError('set_selected_sim')

701 702

703 - def set_update(self, param, spin):

704 """Update other parameter values. 705 706 @param param: The name of the parameter which has been changed. 707 @type param: str 708 @param spin: The SpinContainer object. 709 @type spin: SpinContainer 710 """ 711 712 # Not implemented. 713 raise RelaxImplementError('set_update')

714 715

716 - def sim_init_values(self):

717 """Initialise the Monte Carlo parameter values.""" 718 719 # Not implemented. 720 raise RelaxImplementError('sim_init_values')

721 722

723 - def sim_pack_data(self, data_id, sim_data):

724 """Pack the Monte Carlo simulation data. 725 726 @param data_id: The data identification information, as yielded by the base_data_loop() generator method. 727 @type data_id: anything 728 @param sim_data: The Monte Carlo simulation data. 729 @type sim_data: list of float 730 """ 731 732 # Not implemented. 733 raise RelaxImplementError('sim_pack_data')

734 735

736 - def sim_return_chi2(self, model_info, index=None):

737 """Return the simulation chi-squared values. 738 739 @param model_info: The model information originating from model_loop(). 740 @type model_info: unknown 741 @keyword index: The optional simulation index. 742 @type index: int 743 @return: The list of simulation chi-squared values. If the index is supplied, only a single value will be returned. 744 @rtype: list of float or float 745 """ 746 747 # Not implemented. 748 raise RelaxImplementError('sim_return_chi2')

749 750

751 - def sim_return_param(self, model_info, index):

752 """Return the array of simulation parameter values. 753 754 @param model_info: The model information originating from model_loop(). 755 @type model_info: unknown 756 @param index: The index of the parameter to return the array of values for. 757 @type index: int 758 @return: The array of simulation parameter values. 759 @rtype: list of float 760 """ 761 762 # Not implemented. 763 raise RelaxImplementError('sim_return_param')

764 765

766 - def sim_return_selected(self, model_info):

767 """Return the array of selected simulation flags for the spin. 768 769 @param model_info: The model information originating from model_loop(). 770 @type model_info: unknown 771 @return: The array of selected simulation flags. 772 @rtype: list of int 773 """ 774 775 # Not implemented. 776 raise RelaxImplementError('sim_return_selected')

777 778

779 - def skip_function(self, model_info):

780 """Skip certain data. 781 782 @param model_info: The model index from model_loop(). 783 @type model_info: int 784 @return: True if the data should be skipped, False otherwise. 785 @rtype: bool 786 """ 787 788 # Never skip. 789 return False

790 791

792 - def test_grid_ops(self, lower=None, upper=None, inc=None, n=None):

793 """Test that the grid search options are reasonable. 794 795 @param lower: The lower bounds of the grid search which must be equal to the number of parameters in the model. 796 @type lower: array of numbers 797 @param upper: The upper bounds of the grid search which must be equal to the number of parameters in the model. 798 @type upper: array of numbers 799 @param 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. 800 @type inc: array of int 801 @param n: The number of parameters in the model. 802 @type n: int 803 """ 804 805 # Not implemented. 806 raise RelaxImplementError('test_grid_ops')

Source Code for Module specific_analyses.api_base