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 # Class variables. 39 SPIN_PARAMS = Param_list() 40 GLOBAL_PARAMS = Param_list() 41 42 # Add some spin specific objects. 43 SPIN_PARAMS.add('select', desc='The spin selection flag') 44 SPIN_PARAMS.add('fixed', desc='The fixed flag') 45 SPIN_PARAMS.add('chi2', desc='Chi-squared value') 46 SPIN_PARAMS.add('iter', desc='Optimisation iterations') 47 SPIN_PARAMS.add('f_count', desc='Number of function calls') 48 SPIN_PARAMS.add('g_count', desc='Number of gradient calls') 49 SPIN_PARAMS.add('h_count', desc='Number of Hessian calls') 50 SPIN_PARAMS.add('warning', desc='Optimisation warning') 51 52 # Add some global objects. 53 GLOBAL_PARAMS.add('chi2', desc='Chi-squared value') 54 GLOBAL_PARAMS.add('iter', desc='Optimisation iterations') 55 GLOBAL_PARAMS.add('f_count', desc='Number of function calls') 56 GLOBAL_PARAMS.add('g_count', desc='Number of gradient calls') 57 GLOBAL_PARAMS.add('h_count', desc='Number of Hessian calls') 58 GLOBAL_PARAMS.add('warning', desc='Optimisation warning') 59 60

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

62 """Back-calculation of relaxation data. 63 64 @keyword spin_index: The global spin index. 65 @type spin_index: int 66 @keyword ri_id: The relaxation data ID string. 67 @type ri_id: str 68 @keyword ri_type: The relaxation data type. 69 @type ri_type: str 70 @keyword frq: The field strength. 71 @type frq: float 72 @return: The back calculated relaxation data value corresponding to the index. 73 @rtype: float 74 """ 75 76 # Not implemented. 77 raise RelaxImplementError

78 79

80 - def base_data_loop(self):

81 """Generator method for looping over the base data of the specific analysis type. 82 83 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. 84 85 86 @return: Information concerning the base data of the analysis. 87 @rtype: anything 88 """ 89 90 # Not implemented. 91 raise RelaxImplementError

92 93

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

95 """Prototype method for reading the data from a BMRB NMR-STAR formatted file. 96 97 @param file_path: The full file path. 98 @type file_path: str 99 """ 100 101 # Not implemented. 102 raise RelaxImplementError

103 104

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

106 """Prototype method for writing the data to a BMRB NMR-STAR formatted file. 107 108 @param file_path: The full file path. 109 @type file_path: str 110 @keyword version: The BMRB NMR-STAR dictionary format to output to. 111 @type version: str 112 """ 113 114 # Not implemented. 115 raise RelaxImplementError

116 117

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

119 """Calculate the chi-squared value. 120 121 @keyword spin_id: The spin identification string. 122 @type spin_id: None or str 123 @keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity. 124 @type verbosity: int 125 @keyword sim_index: The optional MC simulation index. 126 @type sim_index: None or int 127 """ 128 129 # Not implemented. 130 raise RelaxImplementError

131 132

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

134 """Create the Monte Carlo data. 135 136 @keyword data_id: The data identification information, as yielded by the base_data_loop() generator method. 137 @type data_id: str 138 @return: The Monte Carlo simulation data. 139 @rtype: list of floats 140 """ 141 142 # Not implemented. 143 raise RelaxImplementError

144 145

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

147 """Initialise the data structures. 148 149 @param data_cont: The data container. 150 @type data_cont: instance 151 @keyword sim: The Monte Carlo simulation flag, which if true will initialise the simulation data structure. 152 @type sim: bool 153 """ 154 155 # Not implemented. 156 raise RelaxImplementError

157 158

159 - def data_names(self, set='all', error_names=False, sim_names=False):

160 """Return a list of names of data structures. 161 162 @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. 163 @type set: str 164 @keyword error_names: A flag which if True will add the error object names as well. 165 @type error_names: bool 166 @keyword sim_names: A flag which if True will add the Monte Carlo simulation object names as well. 167 @type sim_names: bool 168 @return: The list of object names. 169 @rtype: list of str 170 """ 171 172 # Not implemented. 173 raise RelaxImplementError

174 175

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

177 """Return the type of data that the parameter should be. 178 179 @keyword param: The parameter name. 180 @type param: list of str 181 @return: The type of the parameter. I.e. the special Python type objects of int, float, str, bool, [str], {bool}, etc. 182 @rtype: any type 183 """ 184 185 # Not implemented. 186 raise RelaxImplementError

187 188 189 # Empty documentation string. 190 default_value_doc = ""

191 - def default_value(self, param):

192 """Return the default parameter values. 193 194 @param param: The specific analysis parameter. 195 @type param: str 196 @return: The default value. 197 @rtype: float 198 """ 199 200 # Not implemented. 201 raise RelaxImplementError

202 203

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

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

215 216

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

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

234 235 236 # Empty documentation string. 237 eliminate_doc = ""

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

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

257 258

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

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

270 271

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

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

285 286

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

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

306 307

308 - def has_errors(self):

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

317 318

319 - def is_spin_param(self, name):

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

330 331

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

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

345 346

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

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

378 379

380 - def model_desc(self, model_info):

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

391 392

393 - def model_loop(self):

394 """Generator method for looping over the models. 395 396 @return: Information identifying the model. 397 @rtype: anything 398 """ 399 400 # Not implemented. 401 raise RelaxImplementError

402 403

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

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

424 425

426 - def model_type(self):

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

435 436

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

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

456 457

458 - def num_instances(self):

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

467 468

469 - def overfit_deselect(self):

470 """Deselect models with insufficient data for minimisation.""" 471 472 # Not implemented. 473 raise RelaxImplementError

474 475

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

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

495 496

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

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

508 509

510 - def return_conversion_factor(self, param):

511 """Return the conversion factor. 512 513 @param param: The parameter name. 514 @type param: str 515 @return: A conversion factor of 1.0. 516 @rtype: float 517 """ 518 519 # Not implemented. 520 raise RelaxImplementError

521 522

523 - def return_data(self, spin):

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

534 535

536 - def return_data_desc(self, name):

537 """Return a description of the parameter. 538 539 @param name: The name or description of the parameter. 540 @type name: str 541 @return: The object description, or None. 542 @rtype: str or None 543 """ 544 545 # Not implemented. 546 raise RelaxImplementError

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

551 - def return_data_name(self, param):

552 """Return a unique identifying string for the given parameter. 553 554 @param param: The parameter name. 555 @type param: str 556 @return: The unique parameter identifying string. 557 @rtype: str 558 """ 559 560 # Not implemented. 561 raise RelaxImplementError

562 563

564 - def return_error(self, data_id):

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

575 576

577 - def return_grace_string(self, param):

578 """Return the Grace string representation of the parameter. 579 580 This is used for axis labelling. 581 582 583 @param param: The specific analysis parameter. 584 @type param: str 585 @return: The Grace string representation of the parameter. 586 @rtype: str 587 """ 588 589 # Not implemented. 590 raise RelaxImplementError

591 592

593 - def return_units(self, param):

594 """Return a string representing the parameters units. 595 596 @param param: The name of the parameter to return the units string for. 597 @type param: str 598 @return: The parameter units string. 599 @rtype: str 600 """ 601 602 # Not implemented. 603 raise RelaxImplementError

604 605

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

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

626 627 628 # Empty documentation string. 629 set_doc = "" 630 631

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

633 """Set the model parameter errors. 634 635 @param model_info: The model information originating from model_loop(). 636 @type model_info: unknown 637 @param index: The index of the parameter to set the errors for. 638 @type index: int 639 @param error: The error value. 640 @type error: float 641 """ 642 643 # Not implemented. 644 raise RelaxImplementError

645 646

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

648 """Set the model parameter values. 649 650 @keyword param: The parameter name list. 651 @type param: list of str 652 @keyword value: The parameter value list. 653 @type value: list 654 @keyword spin_id: The spin identification string, only used for spin specific parameters. 655 @type spin_id: None or str 656 @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. 657 @type force: bool 658 """ 659 660 # Not implemented. 661 raise RelaxImplementError

662 663

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

665 """Set the simulation selection flag. 666 667 @param model_info: The model information originating from model_loop(). 668 @type model_info: unknown 669 @param select_sim: The selection flag for the simulations. 670 @type select_sim: bool 671 """ 672 673 # Not implemented. 674 raise RelaxImplementError

675 676

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

678 """Update other parameter values. 679 680 @param param: The name of the parameter which has been changed. 681 @type param: str 682 @param spin: The SpinContainer object. 683 @type spin: SpinContainer 684 """ 685 686 # Not implemented. 687 raise RelaxImplementError

688 689

690 - def sim_init_values(self):

691 """Initialise the Monte Carlo parameter values.""" 692 693 # Not implemented. 694 raise RelaxImplementError

695 696

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

698 """Pack the Monte Carlo simulation data. 699 700 @param data_id: The data identification information, as yielded by the base_data_loop() generator method. 701 @type data_id: str 702 @param sim_data: The Monte Carlo simulation data. 703 @type sim_data: list of float 704 """ 705 706 # Not implemented. 707 raise RelaxImplementError

708 709

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

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

723 724

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

726 """Return the array of simulation parameter values. 727 728 @param model_info: The model information originating from model_loop(). 729 @type model_info: unknown 730 @param index: The index of the parameter to return the array of values for. 731 @type index: int 732 @return: The array of simulation parameter values. 733 @rtype: list of float 734 """ 735 736 # Not implemented. 737 raise RelaxImplementError

738 739

740 - def sim_return_selected(self, model_info):

741 """Return the array of selected simulation flags for the spin. 742 743 @param model_info: The model information originating from model_loop(). 744 @type model_info: unknown 745 @return: The array of selected simulation flags. 746 @rtype: list of int 747 """ 748 749 # Not implemented. 750 raise RelaxImplementError

751 752

753 - def skip_function(self, model_info):

754 """Skip certain data. 755 756 @param model_info: The model index from model_loop(). 757 @type model_info: int 758 @return: True if the data should be skipped, False otherwise. 759 @rtype: bool 760 """ 761 762 # Not implemented. 763 raise RelaxImplementError

764 765

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

767 """Test that the grid search options are reasonable. 768 769 @param lower: The lower bounds of the grid search which must be equal to the number of parameters in the model. 770 @type lower: array of numbers 771 @param upper: The upper bounds of the grid search which must be equal to the number of parameters in the model. 772 @type upper: array of numbers 773 @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. 774 @type inc: array of int 775 @param n: The number of parameters in the model. 776 @type n: int 777 """ 778 779 # Not implemented. 780 raise RelaxImplementError

Source Code for Module specific_fns.api_base