specific_fns.api

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

38 - def __init__(self):

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

43 44

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

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

62 63

64 - def base_data_loop(self):

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

76 77

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

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

87 88

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

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

100 101

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

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

115 116

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

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

128 129

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

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

141 142

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

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

167 168

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

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

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

186 - def default_value(self, param):

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

200 201

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

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

213 214

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

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

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

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

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

255 256

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

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

268 269

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

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

283 284

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

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

304 305

306 - def has_errors(self):

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

315 316

317 - def is_spin_param(self, name):

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

328 329

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

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

343 344

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

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

376 377

378 - def model_desc(self, model_info):

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

389 390

391 - def model_loop(self):

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

400 401

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

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

422 423

424 - def model_type(self):

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

433 434

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

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

454 455

456 - def num_instances(self):

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

465 466

467 - def overfit_deselect(self):

468 """Deselect models with insufficient data for minimisation.""" 469 470 # Not implemented. 471 raise RelaxImplementError('overfit_deselect')

472 473

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

475 """Create and return an array of PyMOL macros. 476 477 @param data_type: The parameter name or data type. 478 @type data_type: str 479 @keyword style: The PyMOL style. 480 @type style: None or str 481 @keyword colour_start: The starting colour (must be a MOLMOL or X11 name). 482 @type colour_start: str 483 @keyword colour_end: The ending colour (must be a MOLMOL or X11 name). 484 @type colour_end: str 485 @keyword colour_list: The colour list used, either 'molmol' or 'x11'. 486 @type colour_list: str 487 @keyword spin_id: The spin identification string. 488 @type spin_id: str 489 """ 490 491 # Not implemented. 492 raise RelaxImplementError('pymol_macro')

493 494

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

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

506 507

508 - def return_conversion_factor(self, param):

509 """Return the conversion factor. 510 511 @param param: The parameter name. 512 @type param: str 513 @return: A conversion factor of 1.0. 514 @rtype: float 515 """ 516 517 # Return the factor. 518 return self.PARAMS.get_conv_factor(param)

519 520

521 - def return_data(self, spin):

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

532 533

534 - def return_data_desc(self, name):

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

548 549 550 # Empty documentation string. 551 return_data_name_doc = ""

552 - def return_data_name(self, param):

553 """Return a unique identifying string for the given parameter. 554 555 @param param: The parameter name. 556 @type param: str 557 @return: The unique parameter identifying string. 558 @rtype: str 559 """ 560 561 # No parameter. 562 if not self.PARAMS.contains(param): 563 return None 564 565 # Return the name. 566 return param

567 568

569 - def return_error(self, data_id):

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

580 581

582 - def return_grace_string(self, param):

583 """Return the Grace string representation of the parameter. 584 585 This is used for axis labelling. 586 587 588 @param param: The specific analysis parameter. 589 @type param: str 590 @return: The Grace string representation of the parameter. 591 @rtype: str 592 """ 593 594 # The string. 595 return self.PARAMS.get_grace_string(param)

596 597

598 - def return_units(self, param):

599 """Return a string representing the parameters units. 600 601 @param param: The name of the parameter to return the units string for. 602 @type param: str 603 @return: The parameter units string. 604 @rtype: str 605 """ 606 607 # Return the name. 608 return self.PARAMS.get_units(param)

609 610

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

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

631 632 633 # Empty documentation string. 634 set_doc = "" 635 636

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

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

650 651

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

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

667 668

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

670 """Set the simulation selection flag. 671 672 @param model_info: The model information originating from model_loop(). 673 @type model_info: unknown 674 @param select_sim: The selection flag for the simulations. 675 @type select_sim: bool 676 """ 677 678 # Not implemented. 679 raise RelaxImplementError('set_selected_sim')

680 681

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

683 """Update other parameter values. 684 685 @param param: The name of the parameter which has been changed. 686 @type param: str 687 @param spin: The SpinContainer object. 688 @type spin: SpinContainer 689 """ 690 691 # Not implemented. 692 raise RelaxImplementError('set_update')

693 694

695 - def sim_init_values(self):

696 """Initialise the Monte Carlo parameter values.""" 697 698 # Not implemented. 699 raise RelaxImplementError('sim_init_values')

700 701

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

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

713 714

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

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

728 729

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

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

743 744

745 - def sim_return_selected(self, model_info):

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

756 757

758 - def skip_function(self, model_info):

759 """Skip certain data. 760 761 @param model_info: The model index from model_loop(). 762 @type model_info: int 763 @return: True if the data should be skipped, False otherwise. 764 @rtype: bool 765 """ 766 767 # Not implemented. 768 raise RelaxImplementError('skip_function')

769 770

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

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

Source Code for Module specific_fns.api_base