generic_fns.pipes

1 ############################################################################### 2 # # 3 # Copyright (C) 2004-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 manipulating data pipes.""" 25 26 27 # Python module imports 28 import __builtin__ 29 import sys 30 31 # relax module imports. 32 from data import Relax_data_store; ds = Relax_data_store() 33 from dep_check import C_module_exp_fn, scipy_module 34 from relax_errors import RelaxError, RelaxNoPipeError, RelaxPipeError 35 from status import Status; status = Status() 36 37 38 # List of valid data pipe types and descriptions. 39 VALID_TYPES = ['ct', 'frame order', 'jw', 'hybrid', 'mf', 'N-state', 'noe', 'relax_fit'] 40 PIPE_DESC = { 41 'ct': 'Consistency testing', 42 'frame order': 'Frame Order theories', 43 'jw': 'Reduced spectral density mapping', 44 'hybrid': 'Special hybrid pipe', 45 'mf': 'Model-free analysis', 46 'N-state': 'N-state model or ensemble analysis', 47 'noe': 'Steady state NOE calculation', 48 'relax_fit': 'Relaxation curve fitting' 49 } 50 PIPE_DESC_LIST = [] 51 for name in VALID_TYPES: 52 PIPE_DESC_LIST.append(PIPE_DESC[name]) 53 54

55 -def bundle(bundle=None, pipe=None):

56 """Add the data pipe to the given bundle, created the bundle as needed. 57 58 @keyword bundle: The name of the data pipe bundle. 59 @type bundle: str 60 @keyword pipe: The name of the data pipe to add to the bundle. 61 @type pipe: str 62 """ 63 64 # Check that the data pipe exists. 65 test(pipe) 66 67 # Check that the pipe is not in another bundle. 68 for key in ds.pipe_bundles.keys(): 69 if pipe in ds.pipe_bundles[key]: 70 raise RelaxError("The data pipe is already within the '%s' bundle." % key) 71 72 # Create a new bundle if needed. 73 if bundle not in ds.pipe_bundles.keys(): 74 ds.pipe_bundles[bundle] = [] 75 76 # Add the pipe to the bundle. 77 ds.pipe_bundles[bundle].append(pipe) 78 79 # Notify observers that something has occurred. 80 status.observers.pipe_alteration.notify()

81 82

83 -def bundle_names():

84 """Return the list of all data pipe bundles. 85 86 @return: The list of data pipe bundles. 87 @rtype: list of str 88 """ 89 90 return list(ds.pipe_bundles.keys())

91 92

93 -def copy(pipe_from=None, pipe_to=None, bundle_to=None):

94 """Copy the contents of the source data pipe to a new target data pipe. 95 96 If the 'pipe_from' argument is None then the current data pipe is assumed as the source. The 97 data pipe corresponding to 'pipe_to' cannot exist. 98 99 @param pipe_from: The name of the source data pipe to copy the data from. 100 @type pipe_from: str 101 @param pipe_to: The name of the target data pipe to copy the data to. 102 @type pipe_to: str 103 @keyword bundle_to: The optional data pipe bundle to associate the new data pipe with. 104 @type bundle_to: str or None 105 """ 106 107 # Test if the pipe already exists. 108 if pipe_to in list(ds.keys()): 109 raise RelaxPipeError(pipe_to) 110 111 # Both pipe arguments cannot be None. 112 if pipe_from == None and pipe_to == None: 113 raise RelaxError("The pipe_from and pipe_to arguments cannot both be set to None.") 114 115 # Acquire the pipe lock (data modifying function), and make sure it is finally released. 116 status.pipe_lock.acquire(sys._getframe().f_code.co_name) 117 try: 118 # The current data pipe. 119 if pipe_from == None: 120 pipe_from = cdp_name() 121 122 # Copy the data. 123 ds[pipe_to] = ds[pipe_from].__clone__() 124 125 # Bundle the pipe. 126 if bundle_to: 127 bundle(bundle=bundle_to, pipe=pipe_to) 128 129 # Release the lock. 130 finally: 131 status.pipe_lock.release(sys._getframe().f_code.co_name) 132 133 # Notify observers that a pipe change has occurred. 134 status.observers.pipe_alteration.notify()

135 136

137 -def create(pipe_name=None, pipe_type=None, bundle=None, switch=True):

138 """Create a new data pipe. 139 140 The current data pipe will be changed to this new data pipe. 141 142 143 @keyword pipe_name: The name of the new data pipe. 144 @type pipe_name: str 145 @keyword pipe_type: The new data pipe type which can be one of the following: 146 'ct': Consistency testing, 147 'frame order': The Frame Order theories. 148 'jw': Reduced spectral density mapping, 149 'hybrid': The hybridised data pipe. 150 'mf': Model-free analysis, 151 'N-state': N-state model of domain dynamics, 152 'noe': Steady state NOE calculation, 153 'relax_fit': Relaxation curve fitting, 154 'relax_disp': Relaxation dispersion, 155 @type pipe_type: str 156 @keyword bundle: The optional data pipe bundle to associate the data pipe with. 157 @type bundle: str or None 158 @keyword switch: If True, this new pipe will be switched to, otherwise the current data pipe will remain as is. 159 @type switch: bool 160 """ 161 162 # Test if pipe_type is valid. 163 if not pipe_type in VALID_TYPES: 164 raise RelaxError("The data pipe type " + repr(pipe_type) + " is invalid and must be one of the strings in the list " + repr(VALID_TYPES) + ".") 165 166 # Test that the C modules have been loaded. 167 if pipe_type == 'relax_fit' and not C_module_exp_fn: 168 raise RelaxError("Relaxation curve fitting is not available. Try compiling the C modules on your platform.") 169 170 # Test that the scipy is installed for the frame order analysis. 171 if pipe_type == 'frame order' and not scipy_module: 172 raise RelaxError("The frame order analysis is not available. Please install the scipy Python package.") 173 174 # Acquire the pipe lock (data modifying function), and make sure it is finally released. 175 status.pipe_lock.acquire(sys._getframe().f_code.co_name) 176 try: 177 # Add the data pipe. 178 ds.add(pipe_name=pipe_name, pipe_type=pipe_type, bundle=bundle, switch=switch) 179 180 # Release the lock. 181 finally: 182 status.pipe_lock.release(sys._getframe().f_code.co_name)

183 184

185 -def cdp_name():

186 """Return the name of the current data pipe. 187 188 @return: The name of the current data pipe. 189 @rtype: str 190 """ 191 192 return ds.current_pipe

193 194

195 -def current():

196 """Print the name of the current data pipe.""" 197 198 print(cdp_name())

199 200

201 -def delete(pipe_name=None):

202 """Delete a data pipe. 203 204 @param pipe_name: The name of the data pipe to delete. 205 @type pipe_name: str 206 """ 207 208 # Acquire the pipe lock (data modifying function), and make sure it is finally released. 209 status.pipe_lock.acquire(sys._getframe().f_code.co_name) 210 try: 211 # Pipe name is supplied. 212 if pipe_name != None: 213 # Test if the data pipe exists. 214 test(pipe_name) 215 216 # Convert to a list. 217 pipes = [pipe_name] 218 219 # All pipes. 220 else: 221 pipes = ds.keys() 222 223 # Loop over the pipes. 224 for pipe in pipes: 225 # Clean up the pipe bundle, if needed. 226 bundle = get_bundle(pipe) 227 if bundle: 228 # Remove the pipe from the bundle, if needed. 229 ds.pipe_bundles[bundle].remove(pipe) 230 231 # Clean up the bundle. 232 if ds.pipe_bundles[bundle] == []: 233 ds.pipe_bundles.pop(bundle) 234 235 # Delete the data pipe. 236 del ds[pipe] 237 238 # Set the current data pipe to None if it is the deleted data pipe. 239 if ds.current_pipe == pipe: 240 ds.current_pipe = None 241 __builtin__.cdp = None 242 243 # Release the lock. 244 finally: 245 status.pipe_lock.release(sys._getframe().f_code.co_name) 246 247 # Notify observers that the switch has occurred. 248 status.observers.pipe_alteration.notify()

249 250

251 -def display():

252 """Print the details of all the data pipes.""" 253 254 # Acquire the pipe lock, and make sure it is finally released. 255 status.pipe_lock.acquire(sys._getframe().f_code.co_name) 256 try: 257 # Heading. 258 print(("%-20s%-20s%-20s%-20s" % ("Data pipe name", "Data pipe type", "Bundle", "Current"))) 259 260 # Loop over the data pipes. 261 for pipe_name in ds: 262 # The current data pipe. 263 current = '' 264 if pipe_name == cdp_name(): 265 current = '*' 266 267 # Print out. 268 print("%-20s%-20s%-20s%-20s" % (repr(pipe_name), get_type(pipe_name), repr(get_bundle(pipe_name)), current)) 269 270 # Release the lock. 271 finally: 272 status.pipe_lock.release(sys._getframe().f_code.co_name)

273 274

275 -def get_bundle(pipe=None):

276 """Return the name of the bundle that the given pipe belongs to. 277 278 @keyword pipe: The name of the data pipe to find the bundle of. 279 @type pipe: str 280 @return: The name of the bundle that the pipe is located in. 281 @rtype: str or None 282 """ 283 284 # Check that the data pipe exists. 285 test(pipe) 286 287 # Find and return the bundle. 288 for key in ds.pipe_bundles.keys(): 289 if pipe in ds.pipe_bundles[key]: 290 return key

291 292

293 -def get_pipe(name=None):

294 """Return a data pipe. 295 296 @keyword name: The name of the data pipe to return. If None, the current data pipe is 297 returned. 298 @type name: str or None 299 @return: The current data pipe. 300 @rtype: PipeContainer instance 301 """ 302 303 # The name of the data pipe. 304 if name == None: 305 name = cdp_name() 306 307 # Test if the data pipe exists. 308 test(name) 309 310 return ds[name]

311 312

313 -def get_type(name=None):

314 """Return the type of the data pipe. 315 316 @keyword name: The name of the data pipe. If None, the current data pipe is used. 317 @type name: str or None 318 @return: The current data pipe type. 319 @rtype: str 320 """ 321 322 # The name of the data pipe. 323 if name == None: 324 name = cdp_name() 325 326 # Get the data pipe. 327 pipe = get_pipe(name) 328 329 return pipe.pipe_type

330 331

332 -def has_bundle(bundle=None):

333 """Determine if the relax data store contains the data pipe bundle. 334 335 @keyword bundle: The name of the data pipe bundle. 336 @type bundle: str 337 @return: The answer to the question. 338 @rtype: bool 339 """ 340 341 # Is the bundle in the keys. 342 if bundle in ds.pipe_bundles.keys(): 343 return True 344 else: 345 return False

346 347

348 -def has_pipe(name):

349 """Determine if the relax data store contains the data pipe. 350 351 @param name: The name of the data pipe. 352 @type name: str 353 @return: True if the data pipe exists, False otherwise. 354 @rtype: bool 355 """ 356 357 # Check. 358 if name in ds: 359 return True 360 else: 361 return False

362 363

364 -def pipe_loop(name=False):

365 """Generator function for looping over and yielding the data pipes. 366 367 @keyword name: A flag which if True will cause the name of the pipe to be returned. 368 @type name: bool 369 @return: The data pipes, and optionally the pipe names. 370 @rtype: PipeContainer instance or tuple of PipeContainer instance and str if name=True 371 """ 372 373 # Acquire the pipe lock, and make sure it is finally released. 374 status.pipe_lock.acquire(sys._getframe().f_code.co_name) 375 try: 376 # Loop over the keys. 377 for key in list(ds.keys()): 378 # Return the pipe and name. 379 if name: 380 yield ds[key], key 381 382 # Return just the pipe. 383 else: 384 yield ds[key] 385 386 # Release the lock. 387 finally: 388 status.pipe_lock.release(sys._getframe().f_code.co_name)

389 390

391 -def pipe_names(bundle=None):

392 """Return the list of all data pipes. 393 394 @keyword bundle: If supplied, the pipe names will be restricted to those of the bundle. 395 @type bundle: str or None 396 @return: The list of data pipes. 397 @rtype: list of str 398 """ 399 400 # Initialise. 401 names = [] 402 pipes = ds.keys() 403 pipes.sort() 404 405 # Loop over the pipes. 406 for pipe in pipes: 407 # The bundle restriction. 408 if bundle and get_bundle(pipe) != bundle: 409 continue 410 411 # Add the pipe. 412 names.append(pipe) 413 414 # Return the pipe list. 415 return names

416 417

418 -def switch(pipe_name=None):

419 """Switch the current data pipe to the given data pipe. 420 421 @param pipe_name: The name of the data pipe to switch to. 422 @type pipe_name: str 423 """ 424 425 # Acquire the pipe lock (data modifying function), and make sure it is finally released. 426 status.pipe_lock.acquire(sys._getframe().f_code.co_name) 427 try: 428 # Test if the data pipe exists. 429 test(pipe_name) 430 431 # Switch the current data pipe. 432 ds.current_pipe = pipe_name 433 __builtin__.cdp = get_pipe() 434 435 # Release the lock. 436 finally: 437 status.pipe_lock.release(sys._getframe().f_code.co_name) 438 439 # Notify observers that the switch has occurred. 440 status.observers.pipe_alteration.notify()

441 442

443 -def test(pipe_name=None):

444 """Function for testing the existence of the current or supplied data pipe. 445 446 @param pipe_name: The name of the data pipe to switch to. 447 @type pipe_name: str 448 @return: The answer to the question of whether the pipe exists. 449 @rtype: Boolean 450 """ 451 452 # No supplied data pipe and no current data pipe. 453 if pipe_name == None: 454 # Get the current pipe. 455 pipe_name = cdp_name() 456 457 # Still no luck. 458 if pipe_name == None: 459 raise RelaxNoPipeError 460 461 # Test if the data pipe exists. 462 if pipe_name not in ds: 463 raise RelaxNoPipeError(pipe_name)

464

Source Code for Module generic_fns.pipes