specific_analyses.parameter

78 """A special object for handling global and spin parameters.""" 79

80 - def __init__(self, spin_data=True):

81 """Set up the class. 82 83 @keyword spin_data: A flag which if True indicates that the specific analysis operates with spins. 84 @type spin_data: bool 85 """ 86 87 # Store the flags. 88 self.spin_data = spin_data 89 90 # Initialise the lists and dictionaries for the parameter info. 91 self._names = [] 92 self._scope = {} 93 self._string = {} 94 self._defaults = {} 95 self._units = {} 96 self._desc = {} 97 self._py_types = {} 98 self._conv_factor = {} 99 self._grace_string = {} 100 self._grace_units = {} 101 self._grid_lower = {} 102 self._grid_upper = {} 103 self._set = {} 104 self._err = {} 105 self._scaling = {} 106 self._sim = {} 107 108 # Add some spin specific objects. 109 if self.spin_data: 110 self._add( 111 'select', 112 scope = 'spin', 113 desc = 'The spin selection flag', 114 py_type = bool, 115 sim = True 116 ) 117 self._add( 118 'fixed', 119 scope = 'spin', 120 desc = 'The fixed flag', 121 py_type = bool 122 ) 123 124 # Default user function documentation. 125 self._uf_title = "Parameters" 126 self._uf_table_caption = "Parameters" 127 self._uf_docs = {} 128 129 # Set the initialised flag. 130 self._initialised = True

131 132

133 - def __new__(cls, *args, **kargs):

134 """Replacement function for implementing the singleton design pattern.""" 135 136 # First initialisation. 137 if cls._instance is None: 138 # Create a new instance. 139 cls._instance = object.__new__(cls, *args, **kargs) 140 141 # Add an initialisation flag. 142 cls._instance._initialised = False 143 144 # Already initialised, so return the instance. 145 return cls._instance

146 147

148 - def _add(self, name, scope=None, string=None, default=None, units=None, desc=None, py_type=None, set='all', conv_factor=None, scaling=1.0, grid_lower=None, grid_upper=None, grace_string=None, grace_units=None, err=False, sim=False):

149 """Add a parameter to the list. 150 151 @param name: The name of the parameter. This will be used as the variable name. 152 @type name: str 153 @keyword scope: The parameter scope. This can be set to 'global' for parameters located within the global scope of the current data pipe. Or set to 'spin' for spin specific parameters. Alternatively the value 'both' indicates that there are both global and specific versions of this parameter. 154 @type scope: str 155 @keyword string: The string representation of the parameter. 156 @type string: None or str 157 @keyword default: The default value of the parameter. 158 @type default: anything 159 @keyword units: A string representing the parameters units. 160 @type units: None or str 161 @keyword desc: The text description of the parameter. 162 @type desc: None or str 163 @keyword py_type: The Python type that this parameter should be. 164 @type py_type: Python type object 165 @keyword set: The set of object names. This can be set to 'all' for all names, to 'fixed' for parameter of the model which are permanently fixed, to 'params' for parameter of the model which are optimised or calculated, or to 'min' for minimisation specific object names. 166 @type set: str 167 @keyword conv_factor: The factor of conversion between different parameter units. 168 @type conv_factor: None, float or func 169 @keyword scaling: The diagonal scaling factor for optimisation. 170 @type scaling: float or function 171 @keyword grid_lower: The lower bound for the grid search. 172 @type grid_lower: int or function 173 @keyword grid_upper: The upper bound for the grid search. 174 @type grid_upper: int or function 175 @keyword grace_string: The string used for the axes in Grace plots of the data. 176 @type grace_string: None or str 177 @keyword grace_units: A Grace string representing the parameters units. 178 @type grace_units: None or str 179 @keyword err: A flag which if True indicates that the parameter name + '_err' error data structure can exist. 180 @type err: bool 181 @keyword sim: A flag which if True indicates that the parameter name + '_sim' Monte Carlo simulation data structure can exist. 182 @type sim: bool 183 """ 184 185 # Checks. 186 if scope == None: 187 raise RelaxError("The parameter scope must be set.") 188 if py_type == None: 189 raise RelaxError("The parameter type must be set.") 190 allowed_sets = ['all', 'fixed', 'params', 'min'] 191 if set not in allowed_sets: 192 raise RelaxError("The parameter set '%s' must be one of %s." % (set, allowed_sets)) 193 194 # Add the values. 195 self._names.append(name) 196 self._scope[name] = scope 197 self._defaults[name] = default 198 self._units[name] = units 199 self._desc[name] = desc 200 self._py_types[name] = py_type 201 self._set[name] = set 202 self._conv_factor[name] = conv_factor 203 self._err[name] = err 204 self._sim[name] = sim 205 self._grid_lower[name] = grid_lower 206 self._grid_upper[name] = grid_upper 207 self._scaling[name] = scaling 208 209 # The parameter string. 210 if string: 211 self._string[name] = string 212 else: 213 self._string[name] = name 214 215 # The Grace strings. 216 self._grace_string[name] = name 217 if grace_string: 218 self._grace_string[name] = grace_string 219 self._grace_units[name] = units 220 if grace_units: 221 self._grace_units[name] = grace_units

222 223

224 - def _add_align_data(self):

225 """Add the PCS and RDC data.""" 226 227 # Add the data. 228 self._add( 229 'pcs', 230 scope = 'spin', 231 grace_string = 'Pseudo-contact shift', 232 units = 'ppm', 233 desc = 'The pseudo-contact shift (PCS)', 234 py_type = float 235 ) 236 self._add( 237 'rdc', 238 scope = 'spin', 239 grace_string = 'Residual dipolar coupling', 240 units = 'Hz', 241 desc = 'The residual dipolar coupling (RDC)', 242 py_type = float 243 )

244 245

246 - def _add_align_tensor(self):

247 """Add the alignment tensor parameters.""" 248 249 # Add the parameters. 250 self._add( 251 'Axx', 252 scope = 'global', 253 desc = 'The Axx component of the alignment tensor', 254 py_type = float, 255 set = 'params', 256 grid_lower = -1e-3, 257 grid_upper = 1e-3, 258 grace_string = '\\qA\\sxx\\N', 259 err = True, 260 sim = True 261 ) 262 self._add( 263 'Ayy', 264 scope = 'global', 265 desc = 'The Ayy component of the alignment tensor', 266 py_type = float, 267 set = 'params', 268 grid_lower = -1e-3, 269 grid_upper = 1e-3, 270 grace_string = '\\qA\\syy\\N', 271 err = True, 272 sim = True 273 ) 274 self._add( 275 'Axy', 276 scope = 'global', 277 desc = 'The Axy component of the alignment tensor', 278 py_type = float, 279 set = 'params', 280 grid_lower = -1e-3, 281 grid_upper = 1e-3, 282 grace_string = '\\qA\\sxy\\N', 283 err = True, 284 sim = True 285 ) 286 self._add( 287 'Axz', 288 scope = 'global', 289 desc = 'The Axz component of the alignment tensor', 290 py_type = float, 291 set = 'params', 292 grid_lower = -1e-3, 293 grid_upper = 1e-3, 294 grace_string = '\\qA\\sxz\\N', 295 err = True, 296 sim = True 297 ) 298 self._add( 299 'Ayz', 300 scope = 'global', 301 desc = 'The Ayz component of the alignment tensor', 302 py_type = float, 303 set = 'params', 304 grid_lower = -1e-3, 305 grid_upper = 1e-3, 306 grace_string = '\\qA\\syz\\N', 307 err = True, 308 sim = True 309 )

310 311

312 - def _add_csa(self, default=None, set='fixed', err=False, sim=False):

313 """Add the CSA parameter 'csa'. 314 315 @keyword default: The default CSA value. 316 @type default: float 317 @keyword set: The set of object names. This can be set to 'all' for all names, to 'fixed' for parameter of the model which are permanently fixed, to 'params' for parameter of the model which are optimised or calculated, or to 'min' for minimisation specific object names. 318 @type set: str 319 @keyword err: A flag which if True indicates that the 'csa_err' error data structure can exist. 320 @type err: bool 321 @keyword sim: A flag which if True indicates that the 'csa_sim' Monte Carlo simulation data structure can exist. 322 @type sim: bool 323 """ 324 325 # Add the CSA structure. 326 self._add( 327 'csa', 328 scope = 'spin', 329 default = default, 330 units = 'ppm', 331 desc = 'Chemical shift anisotropy (unitless)', 332 py_type = float, 333 set = set, 334 scaling = 1e-4, 335 grid_lower = -120 * 1e-6, 336 grid_upper = -200 * 1e-6, 337 conv_factor = 1e-6, 338 grace_string = '\\qCSA\\Q', 339 err = err, 340 sim = sim 341 )

342 343

344 - def _add_diffusion_params(self):

345 """Add the Brownian rotational diffusion parameters to the list.""" 346 347 # Add the CSA structure. 348 self._add( 349 'tm', 350 scope = 'global', 351 default = 10.0 * 1e-9, 352 grace_string = '\\xt\\f{}\\sm', 353 units = 'ns', 354 desc = 'Global correlation time', 355 py_type = float, 356 set = 'params', 357 scaling = 1e-12, 358 grid_lower = 1.0 * 1e-9, 359 grid_upper = 12.0 * 1e-9, 360 conv_factor = 1e-9, 361 err = True, 362 sim = True 363 ) 364 self._add( 365 'Diso', 366 scope = 'global', 367 default = 1.666 * 1e7, 368 units = '1e6 1/s', 369 desc = 'Isotropic component of the diffusion tensor', 370 py_type = float, 371 set = 'params', 372 conv_factor = 1e6, 373 err = True, 374 sim = True 375 ) 376 self._add( 377 'Dx', 378 scope = 'global', 379 default = 1.666 * 1e7, 380 units = '1e6 1/s', 381 desc = 'Eigenvalue associated with the x-axis of the diffusion tensor', 382 py_type = float, 383 set = 'params', 384 conv_factor = 1e6, 385 err = True, 386 sim = True 387 ) 388 self._add( 389 'Dy', 390 scope = 'global', 391 default = 1.666 * 1e7, 392 units = '1e6 1/s', 393 desc = 'Eigenvalue associated with the y-axis of the diffusion tensor', 394 py_type = float, 395 set = 'params', 396 conv_factor = 1e6, 397 err = True, 398 sim = True 399 ) 400 self._add( 401 'Dz', 402 scope = 'global', 403 default = 1.666 * 1e7, 404 units = '1e6 1/s', 405 desc = 'Eigenvalue associated with the z-axis of the diffusion tensor', 406 py_type = float, 407 set = 'params', 408 conv_factor = 1e6, 409 err = True, 410 sim = True 411 ) 412 self._add( 413 'Dpar', 414 scope = 'global', 415 default = 1.666 * 1e7, 416 units = '1e6 1/s', 417 desc = 'Diffusion coefficient parallel to the major axis of the spheroid diffusion tensor', 418 py_type = float, 419 set = 'params', 420 conv_factor = 1e6, 421 err = True, 422 sim = True 423 ) 424 self._add( 425 'Dper', 426 scope = 'global', 427 default = 1.666 * 1e7, 428 units = '1e6 1/s', 429 desc = 'Diffusion coefficient perpendicular to the major axis of the spheroid diffusion tensor', 430 py_type = float, 431 set = 'params', 432 conv_factor = 1e6, 433 err = True, 434 sim = True 435 ) 436 self._add( 437 'Da', 438 scope = 'global', 439 default = 0.0, 440 units = '1e6 1/s', 441 desc = 'Anisotropic component of the diffusion tensor', 442 py_type = float, 443 set = 'params', 444 scaling = 1e7, 445 grid_lower = da_lower, 446 grid_upper = da_upper, 447 conv_factor = 1e6, 448 err = True, 449 sim = True 450 ) 451 self._add( 452 'Dr', 453 scope = 'global', 454 default = 0.0, 455 desc = 'Rhombic component of the diffusion tensor', 456 py_type = float, 457 set = 'params', 458 grid_lower = 0.0, 459 grid_upper = 1.0, 460 err = True, 461 sim = True 462 ) 463 self._add( 464 'Dratio', 465 scope = 'global', 466 default = 1.0, 467 desc = 'Ratio of the parallel and perpendicular components of the spheroid diffusion tensor', 468 py_type = float, 469 set = 'params', 470 err = True, 471 sim = True 472 ) 473 self._add( 474 'alpha', 475 scope = 'global', 476 default = 0.0, 477 units = 'deg', 478 desc = 'The first Euler angle of the ellipsoid diffusion tensor', 479 py_type = float, 480 set = 'params', 481 grid_lower = 0.0, 482 grid_upper = pi, 483 conv_factor = (2.0*pi) / 360.0, 484 err = True, 485 sim = True 486 ) 487 self._add( 488 'beta', 489 scope = 'global', 490 default = 0.0, 491 units = 'deg', 492 desc = 'The second Euler angle of the ellipsoid diffusion tensor', 493 py_type = float, 494 set = 'params', 495 grid_lower = 0.0, 496 grid_upper = pi, 497 conv_factor = (2.0*pi) / 360.0, 498 err = True, 499 sim = True 500 ) 501 self._add( 502 'gamma', 503 scope = 'global', 504 default = 0.0, 505 units = 'deg', 506 desc = 'The third Euler angle of the ellipsoid diffusion tensor', 507 py_type = float, 508 set = 'params', 509 grid_lower = 0.0, 510 grid_upper = pi, 511 conv_factor = (2.0*pi) / 360.0, 512 err = True, 513 sim = True 514 ) 515 self._add( 516 'theta', 517 scope = 'global', 518 default = 0.0, 519 units = 'deg', 520 desc = 'The polar angle defining the major axis of the spheroid diffusion tensor', 521 py_type = float, 522 set = 'params', 523 grid_lower = 0.0, 524 grid_upper = pi, 525 conv_factor = (2.0*pi) / 360.0, 526 err = True, 527 sim = True 528 ) 529 self._add( 530 'phi', 531 scope = 'global', 532 default = 0.0, 533 units = 'deg', 534 desc = 'The azimuthal angle defining the major axis of the spheroid diffusion tensor', 535 py_type = float, 536 set = 'params', 537 grid_lower = 0.0, 538 grid_upper = pi, 539 conv_factor = (2.0*pi) / 360.0, 540 err = True, 541 sim = True 542 )

543 544

545 - def _add_min_data(self, min_stats_global=False, min_stats_spin=False):

546 """Add minimisation specific objects. 547 548 The parameter scope is defined by the keyword arguments. 549 550 551 @keyword min_stats_global: A flag which if True will cause the parameters to be global. 552 @type min_stats_global: bool 553 @keyword min_stats_spin: A flag which if True will cause the parameters to be spin specific. 554 @type min_stats_spin: bool 555 """ 556 557 # Store the flags. 558 self.min_stats_global = min_stats_global 559 self.min_stats_spin = min_stats_spin 560 561 # Global minimisation data. 562 if self.min_stats_global or self.min_stats_spin: 563 # The scope. 564 if self.min_stats_global and self.min_stats_spin: 565 scope = 'both' 566 elif self.min_stats_global: 567 scope = 'global' 568 else: 569 scope = 'spin' 570 571 # The minimisation parameters. 572 self._add( 573 'chi2', 574 scope = scope, 575 desc = 'Chi-squared value', 576 py_type = float, 577 set = 'min', 578 grace_string = '\\xc\\S2', 579 err = False, 580 sim = True 581 ) 582 self._add( 583 'iter', 584 scope = scope, 585 desc = 'Optimisation iterations', 586 py_type = int, 587 set = 'min', 588 grace_string = 'Iteration count', 589 err = False, 590 sim = True 591 ) 592 self._add( 593 'f_count', 594 scope = scope, 595 desc = 'Number of function calls', 596 py_type = int, 597 set = 'min', 598 grace_string = 'Function call count', 599 err = False, 600 sim = True 601 ) 602 self._add( 603 'g_count', 604 scope = scope, 605 desc = 'Number of gradient calls', 606 py_type = int, 607 set = 'min', 608 grace_string = 'Gradient call count', 609 err = False, 610 sim = True 611 ) 612 self._add( 613 'h_count', 614 scope = scope, 615 desc = 'Number of Hessian calls', 616 py_type = int, 617 set = 'min', 618 grace_string = 'Hessian call count', 619 err = False, 620 sim = True 621 ) 622 self._add( 623 'warning', 624 scope = scope, 625 desc = 'Optimisation warning', 626 py_type = str, 627 set = 'min', 628 err = False, 629 sim = True 630 )

631 632

633 - def _add_model_info(self, scope='spin', model_flag=True, equation_flag=False):

634 """Add model specific objects 'model' and 'params'. 635 636 @keyword scope: The parameter scope. This can be set to 'global' for parameters located within the global scope of the current data pipe. Or set to 'spin' for spin specific parameters. Alternatively the value 'both' indicates that there are both global and specific versions of this parameter. 637 @type scope: str 638 @keyword model_flag: A flag which if True will cause the 'model' structure to be added. 639 @type model_flag: bool 640 """ 641 642 # Add the model structure. 643 if model_flag: 644 self._add( 645 'model', 646 scope = scope, 647 desc = 'The model name', 648 py_type = str 649 ) 650 651 # The equation information. 652 if equation_flag: 653 self._add( 654 'equation', 655 scope = scope, 656 desc = 'The model equation', 657 py_type = str 658 ) 659 660 # Add the parameter name list structure. 661 self._add( 662 'params', 663 scope = scope, 664 desc = 'The parameters of the model', 665 py_type = list 666 )

667 668

669 - def _add_peak_intensity(self):

670 """Add the peak intensity structure 'peak_intensity'.""" 671 672 # Add the peak intensity structure. 673 self._add( 674 'peak_intensity', 675 scope = 'spin', 676 desc = 'The peak intensities', 677 py_type = dict, 678 grace_string = '\\qPeak intensities\\Q' 679 )

680 681

682 - def _add_sn_ratio(self):

683 """Add the signal to noise ratio structure 'sn_ratio'.""" 684 685 # Add the peak intensity structure. 686 self._add( 687 'sn_ratio', 688 scope = 'spin', 689 desc = 'The signal to noise ratios', 690 py_type = dict, 691 grace_string = '\\qS/N ratio\\Q' 692 )

693 694

695 - def _set_uf_title(self, title):

696 """Set the title for the user function documentation. 697 698 @param title: The title to use in the user function docstrings. 699 @type title: str 700 """ 701 702 # Store the text. 703 self._uf_title = title

704 705

706 - def _uf_param_table(self, label=None, caption=None, scope='spin', sets=['params', 'fixed'], default=False, units=False, type=False):

707 """"Create the parameter documentation for the user function docstrings. 708 709 @keyword label: The label of the table. This is used to identify replicated tables, and is also used in the table referencing in the LaTeX compilation of the user manual. If this label is already used, the corresponding pre-constructed documentation object will be returned. 710 @type label: str 711 @keyword caption: The caption for the table. 712 @type caption: str 713 @keyword scope: The parameter scope to restrict the table to, defaulting to 'spin'. 714 @type scope: str or None 715 @keyword sets: The parameter sets to restrict the table to. If not given, then all parameters of the 'params' and 'fixed' sets will be added. This can be set to 'all' for all names, to 'fixed' for parameter of the model which are permanently fixed, to 'params' for parameter of the model which are optimised or calculated, or to 'min' for minimisation specific object names. 716 @type sets: list of str 717 @keyword default: A flag which if True will cause the default parameter value to be included in the table. 718 @type default: bool 719 @keyword units: A flag which if True will cause the units to be included in the table. 720 @type units: bool 721 @keyword type: A flag which if True will cause the parameter type to be included in the table. 722 @type type: bool 723 @return: The parameter documentation. 724 @rtype: Desc_container instance 725 """ 726 727 # Sanity checks. 728 if label == None: 729 raise RelaxError("The table identifying label must be supplied.") 730 if label in self._uf_docs: 731 raise RelaxError("The table identifying label '%s' already exists." % label) 732 733 # Initialise the documentation object. 734 self._uf_docs[label] = Desc_container(self._uf_title) 735 736 # The parameter table. 737 table = uf_tables.add_table(label=label, caption=caption) 738 739 # Add the headings. 740 headings = ["Name", "Description"] 741 if default: 742 headings.append("Default") 743 if units: 744 headings.append("Units") 745 if type: 746 headings.append("Type") 747 table.add_headings(headings) 748 749 # Add each parameter, first of the parameter set, then the 'generic' set. 750 for set in sets: 751 for param in self.loop(set=set): 752 # Limit the scope. 753 if scope and self.scope(param) != scope: 754 continue 755 756 row = [] 757 row.append(param) 758 row.append(self.description(param)) 759 if default: 760 row.append("%s" % self.default_value(param)) 761 if units: 762 row.append("%s" % self.units(param)) 763 if type: 764 row.append("%s" % self.type_string(param)) 765 table.add_row(row) 766 767 # Add the table to the documentation object. 768 self._uf_docs[label].add_table(table.label) 769 770 # Return the documentation object so that additional text can be added after the table. 771 return self._uf_docs[label]

772 773

774 - def _uf_doc_loop(self, tables=None):

775 """Generator method for looping over and yielding the user function parameter documentation. 776 777 @keyword tables: The list of tables to loop over. If None, then all tables will be yielded. 778 @type tables: list of str or None 779 @return: The user function documentation for each table. 780 @rtype: Desc_container instance 781 """ 782 783 # No tables supplied. 784 if tables == None: 785 tables = sorted(self._uf_docs.keys()) 786 787 # Loop over the tables, yielding the documentation objects. 788 for table in tables: 789 yield self._uf_docs[table]

790 791

792 - def base_loop(self, set=None, scope=None):

793 """An iterator method for looping over all the base parameters. 794 795 @keyword set: The set of object names. This can be set to 'all' for all names, to 'fixed' for parameter of the model which are permanently fixed, to 'params' for parameter of the model which are optimised or calculated, or to 'min' for minimisation specific object names. 796 @type set: str 797 @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. 798 @type scope: str or None 799 @returns: The parameter names. 800 @rtype: str 801 """ 802 803 # Loop over the parameters. 804 for name in self._names: 805 # Skip the parameter if the set does not match. 806 if set == 'fixed' and self._set[name] != 'fixed': 807 continue 808 if set == 'params' and self._set[name] != 'params': 809 continue 810 if set == 'min' and self._set[name] != 'min': 811 continue 812 813 # Skip the parameter is outside of the scope. 814 if scope == 'global' and self._scope[name] == 'spin': 815 continue 816 if scope == 'spin' and self._scope[name] == 'global': 817 continue 818 819 # Yield the parameter name. 820 yield name

821 822

823 - def check_param(self, name):

824 """Check if the parameter exists. 825 826 @param name: The name of the parameter to search for. 827 @type name: str 828 @raises RelaxError: If the parameter does not exist. 829 """ 830 831 # Check. 832 if name not in self._names: 833 raise RelaxError("The parameter '%s' does not exist." % name)

834 835

836 - def contains(self, name):

837 """Determine if the given name is within the parameter list. 838 839 @param name: The name of the parameter to search for. 840 @type name: str 841 @return: True if the parameter is within the list, False otherwise. 842 @rtype: bool 843 """ 844 845 # Check. 846 if name in self._names: 847 return True 848 849 # No match. 850 return False

851 852

853 - def conversion_factor(self, name):

854 """Return the conversion factor. 855 856 @param name: The name of the parameter. 857 @type name: str 858 @return: The conversion factor. 859 @rtype: float 860 """ 861 862 # Parameter check. 863 self.check_param(name) 864 865 # No factor. 866 if self._conv_factor[name] == None: 867 return 1.0 868 869 # Function. 870 if isinstance(self._conv_factor[name], FunctionType) or isinstance(self._conv_factor[name], MethodType): 871 return self._conv_factor[name]() 872 873 # Value. 874 return self._conv_factor[name]

875 876

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

878 """Return a list of names of data structures. 879 880 @keyword set: The set of object names. This can be set to 'all' for all names, to 'fixed' for parameter of the model which are permanently fixed, to 'params' for parameter of the model which are optimised or calculated, or to 'min' for minimisation specific object names. 881 @type set: str 882 @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. 883 @type scope: str or None 884 @keyword error_names: A flag which if True will add the error object names as well. 885 @type error_names: bool 886 @keyword sim_names: A flag which if True will add the Monte Carlo simulation object names as well. 887 @type sim_names: bool 888 @return: The list of object names. 889 @rtype: list of str 890 """ 891 892 # Initialise. 893 names = [] 894 895 # Loop over the parameters. 896 for name in self.loop(set=set, scope=scope, error_names=error_names, sim_names=sim_names): 897 names.append(name) 898 899 # Return the names. 900 return names

901 902

903 - def default_value(self, name):

904 """Return the default value of the parameter. 905 906 @param name: The name of the parameter. 907 @type name: str 908 @return: The default value. 909 @rtype: None or str 910 """ 911 912 # Parameter check. 913 self.check_param(name) 914 915 # Return the default value. 916 return self._defaults[name]

917 918

919 - def description(self, name):

920 """Return the description of the parameter. 921 922 @param name: The name of the parameter. 923 @type name: str 924 @return: The description. 925 @rtype: None or str 926 """ 927 928 # Skip error and simulation structures. 929 if name not in ['ri_data_err'] and (search('_err$', name) or search('_sim$', name)): 930 return None 931 932 # Parameter check. 933 self.check_param(name) 934 935 # Return the description. 936 return self._desc[name]

937 938

939 - def error_flag(self, name):

940 """Return the error flag for the parameter. 941 942 @param name: The name of the parameter. 943 @type name: str 944 @return: The error flag for the parameter. 945 @rtype: bool 946 """ 947 948 # Parameter check. 949 self.check_param(name) 950 951 # Return the type. 952 return self._err[name]

953 954

955 - def grid_lower(self, name, incs=None, model_info=None):

956 """Return the default lower grid bound for the parameter. 957 958 @param name: The name of the parameter. 959 @type name: str 960 @keyword incs: The number of grid search increments. This is used by some of the bound determining functions. 961 @type incs: int 962 @keyword model_info: The model information from the model_loop() specific API method. If the lower bound is a function, this information is sent into it. 963 @type model_info: int 964 @return: The lower bound for the grid search. 965 @rtype: int 966 """ 967 968 # Parameter check. 969 self.check_param(name) 970 971 # Call any function or method. 972 if isinstance(self._grid_lower[name], FunctionType) or isinstance(self._grid_lower[name], MethodType): 973 return self._grid_lower[name](incs=incs, model_info=model_info) 974 975 # Return the value. 976 return self._grid_lower[name]

977 978

979 - def grid_upper(self, name, incs=None, model_info=None):

980 """Return the default upper grid bound for the parameter. 981 982 @param name: The name of the parameter. 983 @type name: str 984 @keyword incs: The number of grid search increments. This is used by some of the bound determining functions. 985 @type incs: int 986 @keyword model_info: The model information from the model_loop() specific API method. If the upper bound is a function, this information is sent into it. 987 @type model_info: int 988 @return: The upper bound for the grid search. 989 @rtype: int 990 """ 991 992 # Parameter check. 993 self.check_param(name) 994 995 # Call any function or method. 996 if isinstance(self._grid_upper[name], FunctionType) or isinstance(self._grid_upper[name], MethodType): 997 return self._grid_upper[name](incs=incs, model_info=model_info) 998 999 # Return the value. 1000 return self._grid_upper[name]

1001 1002

1003 - def grace_string(self, name):

1004 """Return the Grace string for the parameter. 1005 1006 @param name: The name of the parameter. 1007 @type name: str 1008 @return: The Grace string. 1009 @rtype: str 1010 """ 1011 1012 # Parameter check. 1013 self.check_param(name) 1014 1015 # Return the value. 1016 return self._grace_string[name]

1017 1018

1019 - def grace_units(self, name):

1020 """Return the Grace units string for the parameter. 1021 1022 @param name: The name of the parameter. 1023 @type name: str 1024 @return: The Grace units string. 1025 @rtype: str 1026 """ 1027 1028 # Parameter check. 1029 self.check_param(name) 1030 1031 # Function. 1032 if isinstance(self._grace_units[name], FunctionType) or isinstance(self._grace_units[name], MethodType): 1033 grace_unit = self._grace_units[name]() 1034 1035 # The value. 1036 else: 1037 grace_unit = self._grace_units[name] 1038 1039 # Convert None to an empty string. 1040 if grace_unit == None: 1041 grace_unit = '' 1042 1043 # Return the units. 1044 return grace_unit

1045 1046

1047 - def is_spin_param(self, name):

1048 """Determine whether the given parameter is spin specific. 1049 1050 @param name: The name of the parameter. 1051 @type name: str 1052 @return: True if the parameter is spin specific, False otherwise. 1053 @rtype: bool 1054 """ 1055 1056 # Use the scope. 1057 if self.scope(name) == 'spin': 1058 return True 1059 else: 1060 return False

1061 1062

1063 - def loop(self, set=None, scope=None, error_names=False, sim_names=False):

1064 """An iterator method for looping over all the parameters. 1065 1066 @keyword set: The set of object names. This can be set to 'all' for all names, to 'fixed' for parameter of the model which are permanently fixed, to 'params' for parameter of the model which are optimised or calculated, or to 'min' for minimisation specific object names. 1067 @type set: str 1068 @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. 1069 @type scope: str or None 1070 @keyword error_names: A flag which if True will add the error object names as well. 1071 @type error_names: bool 1072 @keyword sim_names: A flag which if True will add the Monte Carlo simulation object names as well. 1073 @type sim_names: bool 1074 @returns: The parameter names. 1075 @rtype: str 1076 """ 1077 1078 # Loop over and yield the parameters. 1079 for name in self.base_loop(set=set, scope=scope): 1080 yield name 1081 1082 # Error names. 1083 if error_names: 1084 for name in self.base_loop(set=set): 1085 if self.error_flag(name): 1086 yield name + '_err' 1087 1088 # Sim names. 1089 if sim_names: 1090 for name in self.base_loop(set=set): 1091 if self.simulation_flag(name): 1092 yield name + '_sim'

1093 1094

1095 - def scaling(self, name, model_info=None):

1096 """Return the scaling factor for the parameter. 1097 1098 @param model_info: The model information from the model_loop() specific API method. If the scaling factor is a function, this information is sent into it. 1099 @type model_info: int 1100 @param name: The name of the parameter. 1101 @type name: str 1102 @return: The scaling factor for optimisation. 1103 @rtype: int 1104 """ 1105 1106 # Parameter check. 1107 self.check_param(name) 1108 1109 # Call any function or method. 1110 if isinstance(self._scaling[name], FunctionType) or isinstance(self._scaling[name], MethodType): 1111 return self._scaling[name](model_info) 1112 1113 # Return the scaling factor. 1114 return self._scaling[name]

1115 1116

1117 - def scope(self, name):

1118 """Return the parameter scope. 1119 1120 @param name: The name of the parameter. 1121 @type name: str 1122 @return: The scope. This is 'global' for parameters located within the global scope of the current data pipe. Or 'spin' for spin specific parameters. Alternatively the value 'both' indicates that there are both global and specific versions of this parameter. 1123 @rtype: str 1124 """ 1125 1126 # Parameter check. 1127 self.check_param(name) 1128 1129 # Return the Python type. 1130 return self._scope[name]

1131 1132

1133 - def set(self, name):

1134 """Return the parameter set that the parameter belongs to. 1135 1136 @param name: The name of the parameter. 1137 @type name: str 1138 @return: The parameter set. 1139 @rtype: str 1140 """ 1141 1142 # Parameter check. 1143 self.check_param(name) 1144 1145 # Return the type. 1146 return self._set[name]

1147 1148

1149 - def simulation_flag(self, name):

1150 """Return the Monte Carlo simulation flag for the parameter. 1151 1152 @param name: The name of the parameter. 1153 @type name: str 1154 @return: The Monte Carlo simulation flag for the parameter. 1155 @rtype: bool 1156 """ 1157 1158 # Parameter check. 1159 self.check_param(name) 1160 1161 # Return the type. 1162 return self._sim[name]

1163 1164

1165 - def type(self, name):

1166 """Return the Python type for the parameter. 1167 1168 @param name: The name of the parameter. 1169 @type name: str 1170 @return: The Python type. 1171 @rtype: Python type object 1172 """ 1173 1174 # Parameter check. 1175 self.check_param(name) 1176 1177 # Return the Python type. 1178 return self._py_types[name]

1179 1180

1181 - def type_string(self, name):

1182 """Return the Python type for the parameter as a string representation. 1183 1184 @param name: The name of the parameter. 1185 @type name: str 1186 @return: The Python type. 1187 @rtype: Python type object 1188 """ 1189 1190 # Parameter check. 1191 self.check_param(name) 1192 1193 # The text representation. 1194 text = repr(self._py_types[name]) 1195 1196 # Return only the part in quotes. 1197 return text.split("'")[1]

1198 1199

1200 - def uf_doc(self, label=None, caption=None, scope='spin', default=False, units=False, type=False):

1201 """"Create the parameter documentation for the user function docstrings. 1202 1203 @keyword label: The label of the table to return. 1204 @type label: str 1205 @return: The parameter documentation. 1206 @rtype: Desc_container instance 1207 """ 1208 1209 # Sanity check. 1210 if label == None: 1211 raise RelaxError("The table identifying label must be supplied.") 1212 if label not in self._uf_docs: 1213 raise RelaxError("The table identifying label '%s' does not exist." % label) 1214 1215 # Return the documentation. 1216 return self._uf_docs[label]

1217 1218

1219 - def units(self, name):

1220 """Return the units string for the parameter. 1221 1222 @param name: The name of the parameter. 1223 @type name: str 1224 @return: The units string. If no unit is present, the empty string will be returned. 1225 @rtype: str 1226 """ 1227 1228 # Parameter check. 1229 self.check_param(name) 1230 1231 # Function. 1232 if isinstance(self._units[name], FunctionType) or isinstance(self._units[name], MethodType): 1233 unit = self._units[name]() 1234 1235 # The value. 1236 else: 1237 unit = self._units[name] 1238 1239 # Convert None to an empty string. 1240 if unit == None: 1241 unit = '' 1242 1243 # Return the units. 1244 return unit

Source Code for Module specific_analyses.parameter_object