generic_fns.value

1 ############################################################################### 2 # # 3 # Copyright (C) 2003-2012 Edward d'Auvergne # 4 # # 5 # This file is part of the program relax. # 6 # # 7 # relax is free software; you can redistribute it and/or modify # 8 # it under the terms of the GNU General Public License as published by # 9 # the Free Software Foundation; either version 2 of the License, or # 10 # (at your option) any later version. # 11 # # 12 # relax is distributed in the hope that it will be useful, # 13 # but WITHOUT ANY WARRANTY; without even the implied warranty of # 14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # 15 # GNU General Public License for more details. # 16 # # 17 # You should have received a copy of the GNU General Public License # 18 # along with relax; if not, write to the Free Software # 19 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # 20 # # 21 ############################################################################### 22 23 # Module docstring. 24 """Module for the manipulation of parameter and constant values.""" 25 26 # Python module imports. 27 from numpy import ndarray 28 import sys 29 30 # relax module imports. 31 from generic_fns import minimise, pipes 32 from generic_fns.mol_res_spin import exists_mol_res_spin_data, generate_spin_id, generate_spin_id_data_array, return_spin, spin_loop 33 from relax_errors import RelaxError, RelaxNoSequenceError, RelaxNoSpinError, RelaxParamSetError, RelaxValueError 34 from relax_io import get_file_path, open_write_file, read_spin_data, write_spin_data 35 import specific_fns 36 from status import Status; status = Status() 37 38

39 -def copy(pipe_from=None, pipe_to=None, param=None):

40 """Copy spin specific data values from pipe_from to pipe_to. 41 42 @param pipe_from: The data pipe to copy the value from. This defaults to the current data 43 pipe. 44 @type pipe_from: str 45 @param pipe_to: The data pipe to copy the value to. This defaults to the current data pipe. 46 @type pipe_to: str 47 @param param: The name of the parameter to copy the values of. 48 @type param: str 49 """ 50 51 # The current data pipe. 52 if pipe_from == None: 53 pipe_from = pipes.cdp_name() 54 if pipe_to == None: 55 pipe_to = pipes.cdp_name() 56 57 # The second pipe does not exist. 58 pipes.test(pipe_to) 59 60 # Test if the sequence data for pipe_from is loaded. 61 if not exists_mol_res_spin_data(pipe_from): 62 raise RelaxNoSequenceError(pipe_from) 63 64 # Test if the sequence data for pipe_to is loaded. 65 if not exists_mol_res_spin_data(pipe_to): 66 raise RelaxNoSequenceError(pipe_to) 67 68 # Specific value and error returning function. 69 return_value = specific_fns.setup.get_specific_fn('return_value', pipes.get_type(pipe_from)) 70 71 # Test if the data exists for pipe_to. 72 for spin in spin_loop(pipe_to): 73 # Get the value and error for pipe_to. 74 value, error = return_value(spin, param) 75 76 # Data exists. 77 if value != None or error != None: 78 raise RelaxValueError(param, pipe_to) 79 80 # Copy the values. 81 for spin, spin_id in spin_loop(pipe_from, return_id=True): 82 # Get the value and error from pipe_from. 83 value, error = return_value(spin, param) 84 85 # Get the equivalent spin in pipe_to. 86 spin_to = return_spin(spin_id, pipe_to) 87 88 # Set the values of pipe_to. 89 set(spin_id=spin_to, value=value, error=error, param=param) 90 91 # Reset all minimisation statistics. 92 minimise.reset_min_stats(pipe_to)

93 94

95 -def display(param=None):

96 """Display spin specific data values. 97 98 @param param: The name of the parameter to display. 99 @type param: str 100 """ 101 102 # Test if the current pipe exists. 103 pipes.test() 104 105 # Test if the sequence data is loaded. 106 if not exists_mol_res_spin_data(): 107 raise RelaxNoSequenceError 108 109 # Print the data. 110 write_data(param, sys.stdout)

111 112

113 -def get_parameters():

114 """Return a list of the parameters associated with the current data pipe. 115 116 @return: The list of parameters. 117 @rtype: list of str 118 """ 119 120 # No data pipes. 121 if cdp == None: 122 return [] 123 124 # Get the specific functions. 125 data_names = specific_fns.setup.get_specific_fn('data_names', cdp.pipe_type, raise_error=False) 126 return_data_desc = specific_fns.setup.get_specific_fn('return_data_desc', cdp.pipe_type, raise_error=False) 127 128 # Loop over the parameters. 129 params = [] 130 for name in (data_names(set='params') + data_names(set='generic')): 131 # Get the description. 132 desc = return_data_desc(name) 133 134 # No description. 135 if not desc: 136 text = name 137 138 # The text. 139 else: 140 text = "'%s': %s" % (name, desc) 141 142 # Append the data as a list. 143 params.append((text, name)) 144 145 # Return the data. 146 return params

147 148

149 -def partition_params(val, param):

150 """Function for sorting and partitioning the parameters and their values. 151 152 The two major partitions are the tensor parameters and the spin specific parameters. 153 154 @param val: The parameter values. 155 @type val: None, number, or list of numbers 156 @param param: The parameter names. 157 @type param: None, str, or list of str 158 @return: A tuple, of length 4, of lists. The first and second elements are the lists of 159 spin specific parameters and values respectively. The third and forth elements 160 are the lists of all other parameters and their values. 161 @rtype: tuple of 4 lists 162 """ 163 164 # Specific functions. 165 is_spin_param = specific_fns.setup.get_specific_fn('is_spin_param', pipes.get_type()) 166 167 # Initialise. 168 spin_params = [] 169 spin_values = [] 170 other_params = [] 171 other_values = [] 172 173 # Single parameter. 174 if isinstance(param, str): 175 # Spin specific parameter. 176 if is_spin_param(param): 177 params = spin_params 178 values = spin_values 179 180 # Other parameters. 181 else: 182 params = other_params 183 values = other_values 184 185 # List of values. 186 if isinstance(val, list) or isinstance(val, ndarray): 187 # Parameter name. 188 for i in xrange(len(val)): 189 params.append(param) 190 191 # Parameter value. 192 values = val 193 194 # Single value. 195 else: 196 # Parameter name. 197 params.append(param) 198 199 # Parameter value. 200 values.append(val) 201 202 # Multiple parameters. 203 elif isinstance(param, list): 204 # Loop over all parameters. 205 for i in xrange(len(param)): 206 # Spin specific parameter. 207 if is_spin_param(param[i]): 208 params = spin_params 209 values = spin_values 210 211 # Other parameters. 212 else: 213 params = other_params 214 values = other_values 215 216 # Parameter name. 217 params.append(param[i]) 218 219 # Parameter value. 220 if isinstance(val, list) or isinstance(val, ndarray): 221 values.append(val[i]) 222 else: 223 values.append(val) 224 225 226 # Return the partitioned parameters and values. 227 return spin_params, spin_values, other_params, other_values

228 229

230 -def read(param=None, scaling=1.0, file=None, dir=None, file_data=None, spin_id_col=None, mol_name_col=None, res_num_col=None, res_name_col=None, spin_num_col=None, spin_name_col=None, data_col=None, error_col=None, sep=None, spin_id=None):

231 """Read spin specific data values from a file. 232 233 @keyword param: The name of the parameter to read. 234 @type param: str 235 @keyword scaling: A scaling factor by which all read values are multiplied by. 236 @type scaling: float 237 @keyword file: The name of the file to open. 238 @type file: str 239 @keyword dir: The directory containing the file (defaults to the current directory if None). 240 @type dir: str or None 241 @keyword file_data: An alternative to opening a file, if the data already exists in the correct format. The format is a list of lists where the first index corresponds to the row and the second the column. 242 @type file_data: list of lists 243 @keyword spin_id_col: The column containing the spin ID strings. If supplied, the mol_name_col, res_name_col, res_num_col, spin_name_col, and spin_num_col arguments must be none. 244 @type spin_id_col: int or None 245 @keyword mol_name_col: The column containing the molecule name information. If supplied, spin_id_col must be None. 246 @type mol_name_col: int or None 247 @keyword res_name_col: The column containing the residue name information. If supplied, spin_id_col must be None. 248 @type res_name_col: int or None 249 @keyword res_num_col: The column containing the residue number information. If supplied, spin_id_col must be None. 250 @type res_num_col: int or None 251 @keyword spin_name_col: The column containing the spin name information. If supplied, spin_id_col must be None. 252 @type spin_name_col: int or None 253 @keyword spin_num_col: The column containing the spin number information. If supplied, spin_id_col must be None. 254 @type spin_num_col: int or None 255 @keyword data_col: The column containing the RDC data in Hz. 256 @type data_col: int or None 257 @keyword error_col: The column containing the RDC errors. 258 @type error_col: int or None 259 @keyword sep: The column separator which, if None, defaults to whitespace. 260 @type sep: str or None 261 @keyword spin_id: The spin ID string. 262 @type spin_id: None or str 263 """ 264 265 # Test if the current pipe exists. 266 pipes.test() 267 268 # Test if sequence data is loaded. 269 if not exists_mol_res_spin_data(): 270 raise RelaxNoSequenceError 271 272 # Minimisation parameter. 273 if minimise.return_data_name(param): 274 # Minimisation statistic flag. 275 min_stat = True 276 277 # Specific value and error returning function. 278 return_value = minimise.return_value 279 280 # Specific set function. 281 set_fn = minimise.set 282 283 # Normal parameter. 284 else: 285 # Minimisation statistic flag. 286 min_stat = False 287 288 # Specific v 289 return_value = specific_fns.setup.get_specific_fn('return_value', pipes.get_type()) 290 291 # Specific set function. 292 set_fn = set 293 294 # Test data corresponding to param already exists. 295 for spin in spin_loop(): 296 # Skip deselected spins. 297 if not spin.select: 298 continue 299 300 # Get the value and error. 301 value, error = return_value(spin, param) 302 303 # Data exists. 304 if value != None or error != None: 305 raise RelaxValueError(param) 306 307 # Loop over the data. 308 mol_names = [] 309 res_nums = [] 310 res_names = [] 311 spin_nums = [] 312 spin_names = [] 313 values = [] 314 errors = [] 315 for data in read_spin_data(file=file, dir=dir, file_data=file_data, spin_id_col=spin_id_col, mol_name_col=mol_name_col, res_num_col=res_num_col, res_name_col=res_name_col, spin_num_col=spin_num_col, spin_name_col=spin_name_col, data_col=data_col, error_col=error_col, sep=sep, spin_id=spin_id): 316 # Unpack. 317 if data_col and error_col: 318 mol_name, res_num, res_name, spin_num, spin_name, value, error = data 319 elif data_col: 320 mol_name, res_num, res_name, spin_num, spin_name, value = data 321 error = None 322 else: 323 mol_name, res_num, res_name, spin_num, spin_name, error = data 324 value = None 325 326 # Set the value. 327 id = generate_spin_id(mol_name=mol_name, res_num=res_num, res_name=res_name, spin_num=spin_num, spin_name=spin_name) 328 set_fn(val=value, error=error, param=param, spin_id=id) 329 330 # Append the data for printout. 331 mol_names.append(mol_name) 332 res_nums.append(res_num) 333 res_names.append(res_name) 334 spin_nums.append(spin_num) 335 spin_names.append(spin_name) 336 values.append(value) 337 errors.append(error) 338 339 # Print out. 340 write_spin_data(file=sys.stdout, mol_names=mol_names, res_nums=res_nums, res_names=res_names, spin_nums=spin_nums, spin_names=spin_names, data=values, data_name=param, error=errors, error_name='%s_error'%param) 341 342 # Reset the minimisation statistics. 343 if not min_stat: 344 minimise.reset_min_stats()

345 346

347 -def set(val=None, param=None, error=None, pipe=None, spin_id=None, force=True, reset=True):

348 """Set global or spin specific data values. 349 350 @keyword val: The parameter values. 351 @type val: None or list 352 @keyword param: The parameter names. 353 @type param: None, str, or list of str 354 @keyword error: The parameter errors. 355 @type error: None, number, or list of numbers 356 @keyword pipe: The data pipe the values should be placed in. 357 @type pipe: None or str 358 @keyword spin_id: The spin identification string. 359 @type spin_id: str 360 @keyword force: A flag forcing the overwriting of current values. 361 @type force: bool 362 @keyword reset: A flag which if True will cause all minimisation statistics to be reset. 363 @type reset: bool 364 """ 365 366 # Switch to the data pipe, storing the original. 367 if pipe: 368 orig_pipe = pipes.cdp_name() 369 pipes.switch(pipe) 370 371 # Test if the current data pipe exists. 372 pipes.test() 373 374 # Specific functions. 375 default_value = specific_fns.setup.get_specific_fn('default_value', pipes.get_type()) 376 get_param_names = specific_fns.setup.get_specific_fn('get_param_names', pipes.get_type()) 377 return_data_name = specific_fns.setup.get_specific_fn('return_data_name', pipes.get_type()) 378 set_param_values = specific_fns.setup.get_specific_fn('set_param_values', pipes.get_type()) 379 380 # Convert numpy arrays to lists, if necessary. 381 if isinstance(val, ndarray): 382 val = val.tolist() 383 384 # Invalid combinations. 385 if (isinstance(val, float) or isinstance(val, int)) and param == None: 386 raise RelaxError("The combination of a single value '%s' without specifying the parameter name is invalid." % val) 387 if isinstance(val, list) and isinstance(param, str): 388 raise RelaxError("Invalid combination: When multiple values '%s' are specified, either no parameters or a list of parameters must by supplied rather than the single parameter '%s'." % (val, param)) 389 390 # Value array and parameter array of equal length. 391 if isinstance(val, list) and isinstance(param, list) and len(val) != len(param): 392 raise RelaxError("Both the value array and parameter array must be of equal length.") 393 394 # Get the parameter list if needed. 395 if param == None: 396 param = get_param_names() 397 398 # Convert the param to a list if needed. 399 if not isinstance(param, list): 400 param = [param] 401 402 # Convert the value to a list if needed. 403 if val != None and not isinstance(val, list): 404 val = [val] * len(param) 405 406 # Default values. 407 if val == None: 408 # Loop over the parameters, getting the default values. 409 val = [] 410 for i in range(len(param)): 411 val.append(default_value(return_data_name(param[i]))) 412 413 # Check that there is a default. 414 if val[-1] == None: 415 raise RelaxParamSetError(param[i]) 416 417 # Set the parameter values. 418 set_param_values(param=param, value=val, spin_id=spin_id, force=force) 419 420 # Reset all minimisation statistics. 421 if reset: 422 minimise.reset_min_stats() 423 424 # Switch back. 425 if pipe: 426 pipes.switch(orig_pipe)

427 428

429 -def write(param=None, file=None, dir=None, bc=False, force=False, return_value=None):

430 """Write data to a file. 431 432 @keyword param: The name of the parameter to write to file. 433 @type param: str 434 @keyword file: The file to write the data to. 435 @type file: str 436 @keyword dir: The name of the directory to place the file into (defaults to the 437 current directory). 438 @type dir: str 439 @keyword bc: A flag which if True will cause the back calculated values to be written. 440 @type bc: bool 441 @keyword force: A flag which if True will cause any pre-existing file to be overwritten. 442 @type force: bool 443 @keyword return_value: An optional function which if supplied will override the default value 444 returning function. 445 @type return_value: None or func 446 """ 447 448 # Test if the current pipe exists. 449 pipes.test() 450 451 # Test if the sequence data is loaded. 452 if not exists_mol_res_spin_data(): 453 raise RelaxNoSequenceError 454 455 # Open the file for writing. 456 file_path = get_file_path(file, dir) 457 file = open_write_file(file, dir, force) 458 459 # Write the data. 460 write_data(param, file, bc, return_value) 461 462 # Close the file. 463 file.close() 464 465 # Add the file to the results file list. 466 if not hasattr(cdp, 'result_files'): 467 cdp.result_files = [] 468 cdp.result_files.append(['text', 'Text', file_path]) 469 status.observers.result_file.notify()

470 471

472 -def write_data(param=None, file=None, bc=False, return_value=None):

473 """The function which actually writes the data. 474 475 @keyword param: The parameter to write. 476 @type param: str 477 @keyword file: The file to write the data to. 478 @type file: str 479 @keyword bc: A flag which if True will cause the back calculated values to be written. 480 @type bc: bool 481 @keyword return_value: An optional function which if supplied will override the default value returning function. 482 @type return_value: None or func 483 """ 484 485 # Get the value and error returning function if required. 486 if not return_value: 487 return_value = specific_fns.setup.get_specific_fn('return_value', pipes.get_type()) 488 489 # Format string. 490 format = "%-30s%-30s" 491 492 # Init the data. 493 mol_names = [] 494 res_nums = [] 495 res_names = [] 496 spin_nums = [] 497 spin_names = [] 498 values = [] 499 errors = [] 500 501 # Loop over the sequence. 502 for spin, mol_name, res_num, res_name in spin_loop(full_info=True): 503 # Get the value and error. 504 value, error = return_value(spin, param, bc=bc) 505 506 # Append the data. 507 mol_names.append(mol_name) 508 res_nums.append(res_num) 509 res_names.append(res_name) 510 spin_nums.append(spin.num) 511 spin_names.append(spin.name) 512 values.append(value) 513 errors.append(error) 514 515 # Write the data. 516 write_spin_data(file, mol_names=mol_names, res_nums=res_nums, res_names=res_names, spin_nums=spin_nums, spin_names=spin_names, data=values, data_name='value', error=errors, error_name='error')

517

Source Code for Module generic_fns.value