specific_fns.api

35 """Base class defining the specific_fns API. 36 37 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. 38 """ 39 40 # Empty documentation strings. 41 default_value_doc = "" 42 eliminate_doc = "" 43 return_data_name_doc = "" 44 set_doc = "" 45 write_doc = "" 46 47

48 - def __init__(self):

49 """Set up the specific objects.""" 50 51 # Class variables. 52 self.PARAMS = Param_list()

53 54

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

56 """Back-calculation of relaxation data. 57 58 @keyword spin_index: The global spin index. 59 @type spin_index: int 60 @keyword ri_id: The relaxation data ID string. 61 @type ri_id: str 62 @keyword ri_type: The relaxation data type. 63 @type ri_type: str 64 @keyword frq: The field strength. 65 @type frq: float 66 @return: The back calculated relaxation data value corresponding to the index. 67 @rtype: float 68 """ 69 70 # Not implemented. 71 raise RelaxImplementError('back_calc_ri')

72 73

74 - def base_data_loop(self):

75 """Generator method for looping over the base data of the specific analysis type. 76 77 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. 78 79 80 @return: Information concerning the base data of the analysis. 81 @rtype: anything 82 """ 83 84 # Not implemented. 85 raise RelaxImplementError('base_data_loop')

86 87

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

89 """Prototype method for reading the data from a BMRB NMR-STAR formatted file. 90 91 @param file_path: The full file path. 92 @type file_path: str 93 """ 94 95 # Not implemented. 96 raise RelaxImplementError('bmrb_read')

97 98

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

100 """Prototype method for writing the data to a BMRB NMR-STAR formatted file. 101 102 @param file_path: The full file path. 103 @type file_path: str 104 @keyword version: The BMRB NMR-STAR dictionary format to output to. 105 @type version: str 106 """ 107 108 # Not implemented. 109 raise RelaxImplementError('bmrb_write')

110 111

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

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

125 126

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

128 """Create the Monte Carlo data. 129 130 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method. 131 @type data_id: anything 132 @return: The Monte Carlo simulation data. 133 @rtype: list of floats 134 """ 135 136 # Not implemented. 137 raise RelaxImplementError('create_mc_data')

138 139

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

141 """Initialise the data structures. 142 143 @param data_cont: The data container. 144 @type data_cont: instance 145 @keyword sim: The Monte Carlo simulation flag, which if true will initialise the simulation data structure. 146 @type sim: bool 147 """ 148 149 # Not implemented. 150 raise RelaxImplementError('data_init')

151 152

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

154 """Return a list of names of data structures. 155 156 @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. 157 @type set: str 158 @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. 159 @type scope: str or None 160 @keyword error_names: A flag which if True will add the error object names as well. 161 @type error_names: bool 162 @keyword sim_names: A flag which if True will add the Monte Carlo simulation object names as well. 163 @type sim_names: bool 164 @return: The list of object names. 165 @rtype: list of str 166 """ 167 168 # Initialise. 169 names = [] 170 171 # Loop over the parameters. 172 for name in self.PARAMS.loop(set=set, scope=scope, error_names=error_names, sim_names=sim_names): 173 names.append(name) 174 175 # Return the names. 176 return names

177 178

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

180 """Return the type of data that the parameter should be. 181 182 This basic method will first search for a global parameter and, if not found, then a spin parameter. 183 184 @keyword param: The parameter name. 185 @type param: list of str 186 @return: The type of the parameter. I.e. the special Python type objects of int, float, str, bool, [str], {bool}, etc. 187 @rtype: any type 188 """ 189 190 # Return the type. 191 return self.PARAMS.get_type(param)

192 193

194 - def default_value(self, param):

195 """Return the default parameter values. 196 197 This basic method will first search for a global parameter and, if not found, then a spin parameter. 198 199 200 @param param: The specific analysis parameter. 201 @type param: str 202 @return: The default value. 203 @rtype: float 204 """ 205 206 # Return the value. 207 return self.PARAMS.get_default(param)

208 209

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

211 """Deselect models or simulations. 212 213 @param model_info: The model index from model_info(). 214 @type model_info: int 215 @keyword sim_index: The optional Monte Carlo simulation index. If None, then models will be deselected, otherwise the given simulation will. 216 @type sim_index: None or int 217 """ 218 219 # Not implemented. 220 raise RelaxImplementError('deselect')

221 222

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

224 """Duplicate the data specific to a single model. 225 226 @keyword pipe_from: The data pipe to copy the data from. 227 @type pipe_from: str 228 @keyword pipe_to: The data pipe to copy the data to. 229 @type pipe_to: str 230 @keyword model_info: The model index from model_info(). 231 @type model_info: int 232 @keyword global_stats: The global statistics flag. 233 @type global_stats: bool 234 @keyword verbose: A flag which if True will cause info to be printed out. 235 @type verbose: bool 236 """ 237 238 # Not implemented. 239 raise RelaxImplementError('duplicate_data')

240 241

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

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

261 262

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

264 """Return a vector of parameter names. 265 266 @keyword model_info: The model index from model_info(). 267 @type model_info: int 268 @return: The vector of parameter names. 269 @rtype: list of str 270 """ 271 272 # Not implemented. 273 raise RelaxImplementError('get_param_names')

274 275

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

277 """Return a vector of parameter values. 278 279 @keyword model_info: The model index from model_info(). 280 @type model_info: int 281 @keyword sim_index: The optional Monte Carlo simulation index. 282 @type sim_index: int 283 @return: The vector of parameter values. 284 @rtype: list of str 285 """ 286 287 # Not implemented. 288 raise RelaxImplementError('get_param_values')

289 290

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

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

310 311

312 - def has_errors(self):

313 """Test if errors exist for the current data pipe. 314 315 @return: The answer to the question of whether errors exist. 316 @rtype: bool 317 """ 318 319 # Not implemented. 320 raise RelaxImplementError('has_errors')

321 322

323 - def is_spin_param(self, name):

324 """Determine whether the given parameter is spin specific. 325 326 @param name: The name of the parameter. 327 @type name: str 328 @return: True if the parameter is spin specific, False otherwise. 329 @rtype: bool 330 """ 331 332 # Not implemented. 333 raise RelaxImplementError('is_spin_param')

334 335

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

337 """Create bounds for the OpenDX mapping function. 338 339 @param param: The name of the parameter to return the lower and upper bounds of. 340 @type param: str 341 @param spin_id: The spin identification string. 342 @type spin_id: None or str 343 @return: The upper and lower bounds of the parameter. 344 @rtype: list of float 345 """ 346 347 # Not implemented. 348 raise RelaxImplementError('map_bounds')

349 350

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

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

382 383

384 - def model_desc(self, model_info):

385 """Return a description of the model. 386 387 @param model_info: The model index from model_info(). 388 @type model_info: int 389 @return: The model description. 390 @rtype: str 391 """ 392 393 # Not implemented. 394 raise RelaxImplementError('model_desc')

395 396

397 - def model_loop(self):

398 """Generator method for looping over the models. 399 400 @return: Information identifying the model. 401 @rtype: anything 402 """ 403 404 # Not implemented. 405 raise RelaxImplementError('model_loop')

406 407

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

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

428 429

430 - def model_type(self):

431 """Return the type of the model, either being 'local' or 'global'. 432 433 @return: The model type, one of 'local' or 'global'. 434 @rtype: str 435 """ 436 437 # Not implemented. 438 raise RelaxImplementError('model_type')

439 440

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

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

460 461

462 - def num_instances(self):

463 """Return the number of instances (depreciated). 464 465 @return: The number of instances. 466 @rtype: int 467 """ 468 469 # Not implemented. 470 raise RelaxImplementError('num_instances')

471 472

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

474 """Deselect models with insufficient data for minimisation. 475 476 @keyword data_check: A flag to signal if the presence of base data is to be checked for. 477 @type data_check: bool 478 @keyword verbose: A flag which if True will allow printouts. 479 @type verbose: bool 480 """ 481 482 # Not implemented. 483 raise RelaxImplementError('overfit_deselect')

484 485

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

487 """Create and return an array of PyMOL macros. 488 489 @param data_type: The parameter name or data type. 490 @type data_type: str 491 @keyword style: The PyMOL style. 492 @type style: None or str 493 @keyword colour_start: The starting colour (must be a MOLMOL or X11 name). 494 @type colour_start: str 495 @keyword colour_end: The ending colour (must be a MOLMOL or X11 name). 496 @type colour_end: str 497 @keyword colour_list: The colour list used, either 'molmol' or 'x11'. 498 @type colour_list: str 499 @keyword spin_id: The spin identification string. 500 @type spin_id: str 501 """ 502 503 # Not implemented. 504 raise RelaxImplementError('pymol_macro')

505 506

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

508 """Read the columnar formatted results file. 509 510 @param file_data: The processed results file data. 511 @type file_data: list of lists of str 512 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity. 513 @type verbosity: int 514 """ 515 516 # Not implemented. 517 raise RelaxImplementError('read_columnar_results')

518 519

520 - def return_conversion_factor(self, param):

521 """Return the conversion factor. 522 523 @param param: The parameter name. 524 @type param: str 525 @return: A conversion factor of 1.0. 526 @rtype: float 527 """ 528 529 # Return the factor. 530 return self.PARAMS.get_conv_factor(param)

531 532

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

534 """Return the data points used in optimisation. 535 536 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method. 537 @type data_id: anything 538 @return: The array of data values. 539 @rtype: list of float 540 """ 541 542 # Not implemented. 543 raise RelaxImplementError('return_data')

544 545

546 - def return_data_desc(self, name):

547 """Return a description of the parameter. 548 549 This basic method will first search for a global parameter and, if not found, then a spin parameter. 550 551 552 @param name: The name or description of the parameter. 553 @type name: str 554 @return: The object description, or None. 555 @rtype: str or None 556 """ 557 558 # Return the description. 559 return self.PARAMS.get_desc(name)

560 561

562 - def return_data_name(self, param):

563 """Return a unique identifying string for the given parameter. 564 565 @param param: The parameter name. 566 @type param: str 567 @return: The unique parameter identifying string. 568 @rtype: str 569 """ 570 571 # No parameter. 572 if not self.PARAMS.contains(param): 573 return None 574 575 # Return the name. 576 return param

577 578

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

580 """Return the error points corresponding to the data points used in optimisation. 581 582 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method. 583 @type data_id: anything 584 @return: The array of data error values. 585 @rtype: list of float 586 """ 587 588 # Not implemented. 589 raise RelaxImplementError('return_error')

590 591

592 - def return_grace_string(self, param):

593 """Return the Grace string representation of the parameter. 594 595 This is used for axis labelling. 596 597 598 @param param: The specific analysis parameter. 599 @type param: str 600 @return: The Grace string representation of the parameter. 601 @rtype: str 602 """ 603 604 # The string. 605 return self.PARAMS.get_grace_string(param)

606 607

608 - def return_units(self, param):

609 """Return a string representing the parameters units. 610 611 @param param: The name of the parameter to return the units string for. 612 @type param: str 613 @return: The parameter units string. 614 @rtype: str 615 """ 616 617 # Return the name. 618 return self.PARAMS.get_units(param)

619 620

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

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

641 642

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

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

656 657

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

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

673 674

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

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

686 687

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

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

699 700

701 - def sim_init_values(self):

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

706 707

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

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

719 720

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

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

734 735

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

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

749 750

751 - def sim_return_selected(self, model_info):

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

762 763

764 - def skip_function(self, model_info):

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

775 776

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

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

Source Code for Module specific_fns.api_base