specific_fns.api

32 """Base class defining the specific_fns API. 33 34 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. 35 """ 36

37 - def __init__(self):

38 """Set up the specific objects.""" 39 40 # Class variables. 41 self.PARAMS = Param_list()

42 43

44 - def back_calc_ri(self, spin_index=None, ri_id=None, ri_type=None, frq=None):

45 """Back-calculation of relaxation data. 46 47 @keyword spin_index: The global spin index. 48 @type spin_index: int 49 @keyword ri_id: The relaxation data ID string. 50 @type ri_id: str 51 @keyword ri_type: The relaxation data type. 52 @type ri_type: str 53 @keyword frq: The field strength. 54 @type frq: float 55 @return: The back calculated relaxation data value corresponding to the index. 56 @rtype: float 57 """ 58 59 # Not implemented. 60 raise RelaxImplementError('back_calc_ri')

61 62

63 - def base_data_loop(self):

64 """Generator method for looping over the base data of the specific analysis type. 65 66 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. 67 68 69 @return: Information concerning the base data of the analysis. 70 @rtype: anything 71 """ 72 73 # Not implemented. 74 raise RelaxImplementError('base_data_loop')

75 76

77 - def bmrb_read(self, file_path, version=None, sample_conditions=None):

78 """Prototype method for reading the data from a BMRB NMR-STAR formatted file. 79 80 @param file_path: The full file path. 81 @type file_path: str 82 """ 83 84 # Not implemented. 85 raise RelaxImplementError('bmrb_read')

86 87

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

89 """Prototype method for writing the data to a BMRB NMR-STAR formatted file. 90 91 @param file_path: The full file path. 92 @type file_path: str 93 @keyword version: The BMRB NMR-STAR dictionary format to output to. 94 @type version: str 95 """ 96 97 # Not implemented. 98 raise RelaxImplementError('bmrb_write')

99 100

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

102 """Calculate the chi-squared value. 103 104 @keyword spin_id: The spin identification string. 105 @type spin_id: None or str 106 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity. 107 @type verbosity: int 108 @keyword sim_index: The optional MC simulation index. 109 @type sim_index: None or int 110 """ 111 112 # Not implemented. 113 raise RelaxImplementError('calculate')

114 115

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

117 """Create the Monte Carlo data. 118 119 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method. 120 @type data_id: str 121 @return: The Monte Carlo simulation data. 122 @rtype: list of floats 123 """ 124 125 # Not implemented. 126 raise RelaxImplementError('create_mc_data')

127 128

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

130 """Initialise the data structures. 131 132 @param data_cont: The data container. 133 @type data_cont: instance 134 @keyword sim: The Monte Carlo simulation flag, which if true will initialise the simulation data structure. 135 @type sim: bool 136 """ 137 138 # Not implemented. 139 raise RelaxImplementError('data_init')

140 141

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

143 """Return a list of names of data structures. 144 145 @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. 146 @type set: str 147 @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. 148 @type scope: str or None 149 @keyword error_names: A flag which if True will add the error object names as well. 150 @type error_names: bool 151 @keyword sim_names: A flag which if True will add the Monte Carlo simulation object names as well. 152 @type sim_names: bool 153 @return: The list of object names. 154 @rtype: list of str 155 """ 156 157 # Initialise. 158 names = [] 159 160 # Loop over the parameters. 161 for name in self.PARAMS.loop(set=set, scope=scope, error_names=error_names, sim_names=sim_names): 162 names.append(name) 163 164 # Return the names. 165 return names

166 167

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

169 """Return the type of data that the parameter should be. 170 171 This basic method will first search for a global parameter and, if not found, then a spin parameter. 172 173 @keyword param: The parameter name. 174 @type param: list of str 175 @return: The type of the parameter. I.e. the special Python type objects of int, float, str, bool, [str], {bool}, etc. 176 @rtype: any type 177 """ 178 179 # Return the type. 180 return self.PARAMS.get_type(param)

181 182 183 # Empty documentation string. 184 default_value_doc = ""

185 - def default_value(self, param):

186 """Return the default parameter values. 187 188 This basic method will first search for a global parameter and, if not found, then a spin parameter. 189 190 191 @param param: The specific analysis parameter. 192 @type param: str 193 @return: The default value. 194 @rtype: float 195 """ 196 197 # Return the value. 198 return self.PARAMS.get_default(param)

199 200

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

202 """Deselect models or simulations. 203 204 @param model_info: The model index from model_info(). 205 @type model_info: int 206 @keyword sim_index: The optional Monte Carlo simulation index. If None, then models will be deselected, otherwise the given simulation will. 207 @type sim_index: None or int 208 """ 209 210 # Not implemented. 211 raise RelaxImplementError('deselect')

212 213

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

215 """Duplicate the data specific to a single model. 216 217 @keyword pipe_from: The data pipe to copy the data from. 218 @type pipe_from: str 219 @keyword pipe_to: The data pipe to copy the data to. 220 @type pipe_to: str 221 @keyword model_info: The model index from model_info(). 222 @type model_info: int 223 @keyword global_stats: The global statistics flag. 224 @type global_stats: bool 225 @keyword verbose: A flag which if True will cause info to be printed out. 226 @type verbose: bool 227 """ 228 229 # Not implemented. 230 raise RelaxImplementError('duplicate_data')

231 232 233 # Empty documentation string. 234 eliminate_doc = ""

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

236 """Model elimination method. 237 238 @param name: The parameter name. 239 @type name: str 240 @param value: The parameter value. 241 @type value: float 242 @param model_info: The model index from model_info(). 243 @type model_info: int 244 @param args: The elimination constant overrides. 245 @type args: None or tuple of float 246 @keyword sim: The Monte Carlo simulation index. 247 @type sim: int 248 @return: True if the model is to be eliminated, False otherwise. 249 @rtype: bool 250 """ 251 252 # Not implemented. 253 raise RelaxImplementError('eliminate')

254 255

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

257 """Return a vector of parameter names. 258 259 @keyword model_info: The model index from model_info(). 260 @type model_info: int 261 @return: The vector of parameter names. 262 @rtype: list of str 263 """ 264 265 # Not implemented. 266 raise RelaxImplementError('get_param_names')

267 268

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

270 """Return a vector of parameter values. 271 272 @keyword model_info: The model index from model_info(). 273 @type model_info: int 274 @keyword sim_index: The optional Monte Carlo simulation index. 275 @type sim_index: int 276 @return: The vector of parameter values. 277 @rtype: list of str 278 """ 279 280 # Not implemented. 281 raise RelaxImplementError('get_param_values')

282 283

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

285 """Grid search method. 286 287 @keyword lower: The lower bounds of the grid search which must be equal to the number of parameters in the model. 288 @type lower: array of numbers 289 @keyword upper: The upper bounds of the grid search which must be equal to the number of parameters in the model. 290 @type upper: array of numbers 291 @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. 292 @type inc: array of int 293 @keyword constraints: If True, constraints are applied during the grid search (eliminating parts of the grid). If False, no constraints are used. 294 @type constraints: bool 295 @keyword verbosity: A flag specifying the amount of information to print. The higher the value, the greater the verbosity. 296 @type verbosity: int 297 @keyword sim_index: The index of the simulation to apply the grid search to. If None, the normal model is optimised. 298 @type sim_index: int 299 """ 300 301 # Not implemented. 302 raise RelaxImplementError('grid_search')

303 304

305 - def has_errors(self):

306 """Test if errors exist for the current data pipe. 307 308 @return: The answer to the question of whether errors exist. 309 @rtype: bool 310 """ 311 312 # Not implemented. 313 raise RelaxImplementError('has_errors')

314 315

316 - def is_spin_param(self, name):

317 """Determine whether the given parameter is spin specific. 318 319 @param name: The name of the parameter. 320 @type name: str 321 @return: True if the parameter is spin specific, False otherwise. 322 @rtype: bool 323 """ 324 325 # Not implemented. 326 raise RelaxImplementError('is_spin_param')

327 328

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

330 """Create bounds for the OpenDX mapping function. 331 332 @param param: The name of the parameter to return the lower and upper bounds of. 333 @type param: str 334 @param spin_id: The spin identification string. 335 @type spin_id: None or str 336 @return: The upper and lower bounds of the parameter. 337 @rtype: list of float 338 """ 339 340 # Not implemented. 341 raise RelaxImplementError('map_bounds')

342 343

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

345 """Minimisation method. 346 347 @keyword min_algor: The minimisation algorithm to use. 348 @type min_algor: str 349 @keyword min_options: An array of options to be used by the minimisation algorithm. 350 @type min_options: array of str 351 @keyword func_tol: The function tolerance which, when reached, terminates optimisation. Setting this to None turns of the check. 352 @type func_tol: None or float 353 @keyword grad_tol: The gradient tolerance which, when reached, terminates optimisation. Setting this to None turns of the check. 354 @type grad_tol: None or float 355 @keyword max_iterations: The maximum number of iterations for the algorithm. 356 @type max_iterations: int 357 @keyword constraints: If True, constraints are used during optimisation. 358 @type constraints: bool 359 @keyword scaling: If True, diagonal scaling is enabled during optimisation to allow the problem to be better conditioned. 360 @type scaling: bool 361 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity. 362 @type verbosity: int 363 @keyword sim_index: The index of the simulation to optimise. This should be None if normal optimisation is desired. 364 @type sim_index: None or int 365 @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. 366 @type lower: array of numbers 367 @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. 368 @type upper: array of numbers 369 @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. 370 @type inc: array of int 371 """ 372 373 # Not implemented. 374 raise RelaxImplementError('minimise')

375 376

377 - def model_desc(self, model_info):

378 """Return a description of the model. 379 380 @param model_info: The model index from model_info(). 381 @type model_info: int 382 @return: The model description. 383 @rtype: str 384 """ 385 386 # Not implemented. 387 raise RelaxImplementError('model_desc')

388 389

390 - def model_loop(self):

391 """Generator method for looping over the models. 392 393 @return: Information identifying the model. 394 @rtype: anything 395 """ 396 397 # Not implemented. 398 raise RelaxImplementError('model_loop')

399 400

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

402 """Return the k, n, and chi2 model statistics. 403 404 k - number of parameters. 405 n - number of data points. 406 chi2 - the chi-squared value. 407 408 409 @keyword model_info: The model index from model_info(). 410 @type model_info: None or int 411 @keyword spin_id: The spin identification string. This is ignored in the N-state model. 412 @type spin_id: None or str 413 @keyword global_stats: A parameter which determines if global or local statistics are returned. For the N-state model, this argument is ignored. 414 @type global_stats: None or bool 415 @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). 416 @rtype: tuple of (int, int, float) 417 """ 418 419 # Not implemented. 420 raise RelaxImplementError('model_statistics')

421 422

423 - def model_type(self):

424 """Return the type of the model, either being 'local' or 'global'. 425 426 @return: The model type, one of 'local' or 'global'. 427 @rtype: str 428 """ 429 430 # Not implemented. 431 raise RelaxImplementError('model_type')

432 433

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

435 """Create and return an array of Molmol macros. 436 437 @param data_type: The parameter name or data type. 438 @type data_type: str 439 @keyword style: The Molmol style. 440 @type style: None or str 441 @keyword colour_start: The starting colour (must be a MOLMOL or X11 name). 442 @type colour_start: str 443 @keyword colour_end: The ending colour (must be a MOLMOL or X11 name). 444 @type colour_end: str 445 @keyword colour_list: The colour list used, either 'molmol' or 'x11'. 446 @type colour_list: str 447 @keyword spin_id: The spin identification string. 448 @type spin_id: str 449 """ 450 451 # Not implemented. 452 raise RelaxImplementError('molmol_macro')

453 454

455 - def num_instances(self):

456 """Return the number of instances (depreciated). 457 458 @return: The number of instances. 459 @rtype: int 460 """ 461 462 # Not implemented. 463 raise RelaxImplementError('num_instances')

464 465

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

467 """Deselect models with insufficient data for minimisation. 468 469 @keyword data_check: A flag to signal if the presence of base data is to be checked for. 470 @type data_check: bool 471 @keyword verbose: A flag which if True will allow printouts. 472 @type verbose: bool 473 """ 474 475 # Not implemented. 476 raise RelaxImplementError('overfit_deselect')

477 478

479 - def pymol_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 PyMOL macros. 481 482 @param data_type: The parameter name or data type. 483 @type data_type: str 484 @keyword style: The PyMOL 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 # Not implemented. 497 raise RelaxImplementError('pymol_macro')

498 499

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

501 """Read the columnar formatted results file. 502 503 @param file_data: The processed results file data. 504 @type file_data: list of lists of str 505 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity. 506 @type verbosity: int 507 """ 508 509 # Not implemented. 510 raise RelaxImplementError('read_columnar_results')

511 512

513 - def return_conversion_factor(self, param):

514 """Return the conversion factor. 515 516 @param param: The parameter name. 517 @type param: str 518 @return: A conversion factor of 1.0. 519 @rtype: float 520 """ 521 522 # Return the factor. 523 return self.PARAMS.get_conv_factor(param)

524 525

526 - def return_data(self, spin):

527 """Return the data points used in optimisation. 528 529 @param spin: The SpinContainer object. 530 @type spin: SpinContainer instance 531 @return: The array of relaxation data values. 532 @rtype: list of float 533 """ 534 535 # Not implemented. 536 raise RelaxImplementError('return_data')

537 538

539 - def return_data_desc(self, name):

540 """Return a description of the parameter. 541 542 This basic method will first search for a global parameter and, if not found, then a spin parameter. 543 544 545 @param name: The name or description of the parameter. 546 @type name: str 547 @return: The object description, or None. 548 @rtype: str or None 549 """ 550 551 # Return the description. 552 return self.PARAMS.get_desc(name)

553 554 555 # Empty documentation string. 556 return_data_name_doc = ""

557 - def return_data_name(self, param):

558 """Return a unique identifying string for the given parameter. 559 560 @param param: The parameter name. 561 @type param: str 562 @return: The unique parameter identifying string. 563 @rtype: str 564 """ 565 566 # No parameter. 567 if not self.PARAMS.contains(param): 568 return None 569 570 # Return the name. 571 return param

572 573

574 - def return_error(self, data_id):

575 """Return the error points corresponding to the data points used in optimisation. 576 577 @param data_id: The data identification information, as yielded by the base_data_loop() generator method. 578 @type data_id: str 579 @return: The array of relaxation data error values. 580 @rtype: list of float 581 """ 582 583 # Not implemented. 584 raise RelaxImplementError('return_error')

585 586

587 - def return_grace_string(self, param):

588 """Return the Grace string representation of the parameter. 589 590 This is used for axis labelling. 591 592 593 @param param: The specific analysis parameter. 594 @type param: str 595 @return: The Grace string representation of the parameter. 596 @rtype: str 597 """ 598 599 # The string. 600 return self.PARAMS.get_grace_string(param)

601 602

603 - def return_units(self, param):

604 """Return a string representing the parameters units. 605 606 @param param: The name of the parameter to return the units string for. 607 @type param: str 608 @return: The parameter units string. 609 @rtype: str 610 """ 611 612 # Return the name. 613 return self.PARAMS.get_units(param)

614 615

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

617 """Return the value and error corresponding to the parameter. 618 619 If sim is set to an integer, return the value of the simulation and None. 620 621 622 @param spin: The SpinContainer object. 623 @type spin: SpinContainer 624 @param param: The name of the parameter to return values for. 625 @type param: str 626 @keyword sim: The Monte Carlo simulation index. 627 @type sim: None or int 628 @keyword bc: The back-calculated data flag. If True, then the back-calculated data will be returned rather than the actual data. 629 @type bc: bool 630 @return: The value and error corresponding to 631 @rtype: tuple of length 2 of floats or None 632 """ 633 634 # Not implemented. 635 raise RelaxImplementError('return_value')

636 637 638 # Empty documentation string. 639 set_doc = "" 640 641

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

643 """Set the model parameter errors. 644 645 @param model_info: The model information originating from model_loop(). 646 @type model_info: unknown 647 @param index: The index of the parameter to set the errors for. 648 @type index: int 649 @param error: The error value. 650 @type error: float 651 """ 652 653 # Not implemented. 654 raise RelaxImplementError('set_error')

655 656

657 - def set_param_values(self, param=None, value=None, spin_id=None, force=True):

658 """Set the model parameter values. 659 660 @keyword param: The parameter name list. 661 @type param: list of str 662 @keyword value: The parameter value list. 663 @type value: list 664 @keyword spin_id: The spin identification string, only used for spin specific parameters. 665 @type spin_id: None or str 666 @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. 667 @type force: bool 668 """ 669 670 # Not implemented. 671 raise RelaxImplementError('set_param_values')

672 673

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

675 """Set the simulation selection flag. 676 677 @param model_info: The model information originating from model_loop(). 678 @type model_info: unknown 679 @param select_sim: The selection flag for the simulations. 680 @type select_sim: bool 681 """ 682 683 # Not implemented. 684 raise RelaxImplementError('set_selected_sim')

685 686

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

688 """Update other parameter values. 689 690 @param param: The name of the parameter which has been changed. 691 @type param: str 692 @param spin: The SpinContainer object. 693 @type spin: SpinContainer 694 """ 695 696 # Not implemented. 697 raise RelaxImplementError('set_update')

698 699

700 - def sim_init_values(self):

701 """Initialise the Monte Carlo parameter values.""" 702 703 # Not implemented. 704 raise RelaxImplementError('sim_init_values')

705 706

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

708 """Pack the Monte Carlo simulation data. 709 710 @param data_id: The data identification information, as yielded by the base_data_loop() generator method. 711 @type data_id: str 712 @param sim_data: The Monte Carlo simulation data. 713 @type sim_data: list of float 714 """ 715 716 # Not implemented. 717 raise RelaxImplementError('sim_pack_data')

718 719

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

721 """Return the simulation chi-squared values. 722 723 @param model_info: The model information originating from model_loop(). 724 @type model_info: unknown 725 @keyword index: The optional simulation index. 726 @type index: int 727 @return: The list of simulation chi-squared values. If the index is supplied, only a single value will be returned. 728 @rtype: list of float or float 729 """ 730 731 # Not implemented. 732 raise RelaxImplementError('sim_return_chi2')

733 734

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

736 """Return the array of simulation parameter values. 737 738 @param model_info: The model information originating from model_loop(). 739 @type model_info: unknown 740 @param index: The index of the parameter to return the array of values for. 741 @type index: int 742 @return: The array of simulation parameter values. 743 @rtype: list of float 744 """ 745 746 # Not implemented. 747 raise RelaxImplementError('sim_return_param')

748 749

750 - def sim_return_selected(self, model_info):

751 """Return the array of selected simulation flags for the spin. 752 753 @param model_info: The model information originating from model_loop(). 754 @type model_info: unknown 755 @return: The array of selected simulation flags. 756 @rtype: list of int 757 """ 758 759 # Not implemented. 760 raise RelaxImplementError('sim_return_selected')

761 762

763 - def skip_function(self, model_info):

764 """Skip certain data. 765 766 @param model_info: The model index from model_loop(). 767 @type model_info: int 768 @return: True if the data should be skipped, False otherwise. 769 @rtype: bool 770 """ 771 772 # Never skip. 773 return False

774 775

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

777 """Test that the grid search options are reasonable. 778 779 @param lower: The lower bounds of the grid search which must be equal to the number of parameters in the model. 780 @type lower: array of numbers 781 @param upper: The upper bounds of the grid search which must be equal to the number of parameters in the model. 782 @type upper: array of numbers 783 @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. 784 @type inc: array of int 785 @param n: The number of parameters in the model. 786 @type n: int 787 """ 788 789 # Not implemented. 790 raise RelaxImplementError('test_grid_ops')

Source Code for Module specific_fns.api_base