Package user_functions :: Module pipe
[hide private]
[frames] | no frames]

Source Code for Module user_functions.pipe

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2004-2014 Edward d'Auvergne                                   # 
  4  #                                                                             # 
  5  # This file is part of the program relax (http://www.nmr-relax.com).          # 
  6  #                                                                             # 
  7  # This program 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 3 of the License, or           # 
 10  # (at your option) any later version.                                         # 
 11  #                                                                             # 
 12  # This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.       # 
 19  #                                                                             # 
 20  ############################################################################### 
 21   
 22  # Module docstring. 
 23  """The pipe user function definitions.""" 
 24   
 25  # relax module imports. 
 26  from graphics import WIZARD_IMAGE_PATH 
 27  from pipe_control import pipes 
 28  from specific_analyses.api import return_api 
 29  from user_functions.data import Uf_info; uf_info = Uf_info() 
 30  from user_functions.objects import Desc_container 
 31   
 32   
 33  # The hybrid API object. 
 34  hybrid_obj = return_api('hybrid') 
 35   
 36   
 37  # The user function class. 
 38  uf_class = uf_info.add_class('pipe') 
 39  uf_class.title = "Class holding the user functions for manipulating data pipes." 
 40  uf_class.menu_text = "&pipe" 
 41  uf_class.gui_icon = "relax.pipe" 
 42   
 43   
 44  # The pipe.bundle user function. 
 45  uf = uf_info.add_uf('pipe.bundle') 
 46  uf.title = "The grouping of data pipes into a bundle." 
 47  uf.title_short = "Data pipe bundling." 
 48  uf.add_keyarg( 
 49      name = "bundle", 
 50      py_type = "str", 
 51      desc_short = "pipe bundle", 
 52      desc = "The pipe bundle is a special grouping or clustering of data pipes.", 
 53      wiz_element_type = 'combo', 
 54      wiz_combo_iter = pipes.bundle_names, 
 55      wiz_read_only = False 
 56  ) 
 57  uf.add_keyarg( 
 58      name = "pipe", 
 59      py_type = "str", 
 60      desc_short = "data pipe", 
 61      desc = "The name of the data pipe to add to the bundle.", 
 62      wiz_element_type = 'combo', 
 63      wiz_combo_iter = pipes.pipe_names, 
 64      wiz_read_only = True 
 65  ) 
 66  # Description. 
 67  uf.desc.append(Desc_container()) 
 68  uf.desc[-1].add_paragraph("Data pipes can be grouped or clustered together through special structures known as pipe bundles.  If the specified data pipe bundle does not currently exist, it will be created.") 
 69  # Prompt examples. 
 70  uf.desc.append(Desc_container("Prompt examples")) 
 71  uf.desc[-1].add_paragraph("To add the data pipes 'test 1', 'test 2', and 'test 3' to the bundle 'first analysis', type the following:") 
 72  uf.desc[-1].add_prompt("relax> pipe.bundle('first analysis 1', 'test 1')") 
 73  uf.desc[-1].add_prompt("relax> pipe.bundle('first analysis 1', 'test 2')") 
 74  uf.desc[-1].add_prompt("relax> pipe.bundle('first analysis 1', 'test 3')") 
 75  uf.backend = pipes.bundle 
 76  uf.menu_text = "&bundle" 
 77  uf.gui_icon = "relax.pipe_bundle" 
 78  uf.wizard_image = WIZARD_IMAGE_PATH + 'pipe_bundle.png' 
 79   
 80           
 81  # The pipe.change_type user function. 
 82  uf = uf_info.add_uf('pipe.change_type') 
 83  uf.title = "Change the type of the current data pipe." 
 84  uf.title_short = "Data pipe type change." 
 85  uf.add_keyarg( 
 86      name = "pipe_type", 
 87      py_type = "str", 
 88      desc_short = "type of data pipe", 
 89      desc = "The type of data pipe.", 
 90      wiz_element_type = 'combo', 
 91      wiz_combo_choices = pipes.PIPE_DESC_LIST, 
 92      wiz_combo_data = pipes.VALID_TYPES, 
 93      wiz_read_only = True 
 94  ) 
 95  uf.backend = pipes.change_type 
 96  # Description. 
 97  uf.desc.append(Desc_container()) 
 98  uf.desc[-1].add_paragraph("The data pipe type must be one of the following:") 
 99  for name in pipes.VALID_TYPES: 
100      uf.desc[-1].add_item_list_element("'%s'" % name, "%s." % pipes.PIPE_DESC[name]) 
101  # Prompt examples. 
102  uf.desc.append(Desc_container("Prompt examples")) 
103  uf.desc[-1].add_paragraph("To change the type of the current 'frame order' data pipe to the N-state model, type one of:") 
104  uf.desc[-1].add_prompt("relax> pipe.change_type('N-state')") 
105  uf.desc[-1].add_prompt("relax> pipe.change_type(pipe_type='N-state')") 
106  uf.menu_text = "change_&type" 
107  uf.wizard_image = WIZARD_IMAGE_PATH + 'pipe.png' 
108   
109   
110  # The pipe.copy user function. 
111  uf = uf_info.add_uf('pipe.copy') 
112  uf.title = "Copy a data pipe." 
113  uf.title_short = "Data pipe copying." 
114  uf.add_keyarg( 
115      name = "pipe_from", 
116      py_type = "str", 
117      desc_short = "source data pipe", 
118      desc = "The name of the source data pipe to copy the data from.", 
119      wiz_element_type = 'combo', 
120      wiz_combo_iter = pipes.pipe_names, 
121      wiz_read_only = True, 
122      can_be_none = True 
123  ) 
124  uf.add_keyarg( 
125      name = "pipe_to", 
126      py_type = "str", 
127      desc_short = "destination data pipe", 
128      desc = "The name of the target data pipe to copy the data to.", 
129      can_be_none = True 
130  ) 
131  uf.add_keyarg( 
132      name = "bundle_to", 
133      py_type = "str", 
134      desc_short = "destination pipe bundle", 
135      desc = "If given, the new data pipe will be grouped into this bundle.", 
136      wiz_element_type = 'combo', 
137      wiz_combo_iter = pipes.bundle_names, 
138      wiz_read_only = False, 
139      can_be_none = True 
140  ) 
141  # Description. 
142  uf.desc.append(Desc_container()) 
143  uf.desc[-1].add_paragraph("This allows the contents of a data pipe to be copied.  If the source data pipe is not set, the current data pipe will be assumed.  The target data pipe must not yet exist.") 
144  uf.desc[-1].add_paragraph("The optional bundling allows the newly created data pipe to be placed into either a new or existing data pipe bundle.  If not specified, then the copied data pipe will not be associated with a bundle.") 
145  # Prompt examples. 
146  uf.desc.append(Desc_container("Prompt examples")) 
147  uf.desc[-1].add_paragraph("To copy the contents of the 'm1' data pipe to the 'm2' data pipe, type:") 
148  uf.desc[-1].add_prompt("relax> pipe.copy('m1', 'm2')") 
149  uf.desc[-1].add_prompt("relax> pipe.copy(pipe_from='m1', pipe_to='m2')") 
150  uf.desc[-1].add_paragraph("If the current data pipe is 'm1', then the following command can be used:") 
151  uf.desc[-1].add_prompt("relax> pipe.copy(pipe_to='m2')") 
152  uf.backend = pipes.copy 
153  uf.menu_text = "&copy" 
154  uf.gui_icon = "oxygen.actions.list-add" 
155  uf.wizard_size = (800, 500) 
156  uf.wizard_image = WIZARD_IMAGE_PATH + 'pipe.png' 
157   
158   
159  # The pipe.create user function. 
160  uf = uf_info.add_uf('pipe.create') 
161  uf.title = "Add a new data pipe to the relax data store." 
162  uf.title_short = "Data pipe creation." 
163  uf.add_keyarg( 
164      name = "pipe_name", 
165      py_type = "str", 
166      desc_short = "data pipe name", 
167      desc = "The name of the data pipe.", 
168  ) 
169  uf.add_keyarg( 
170      name = "pipe_type", 
171      py_type = "str", 
172      desc_short = "type of data pipe", 
173      desc = "The type of data pipe.", 
174      wiz_element_type = 'combo', 
175      wiz_combo_choices = pipes.PIPE_DESC_LIST, 
176      wiz_combo_data = pipes.VALID_TYPES, 
177      wiz_read_only = True 
178  ) 
179  uf.add_keyarg( 
180      name = "bundle", 
181      py_type = "str", 
182      desc_short = "pipe bundle", 
183      desc = "The optional pipe bundle is a special grouping or clustering of data pipes.  If this is specified, the newly created data pipe will be added to this bundle.", 
184      wiz_element_type = 'combo', 
185      wiz_combo_iter = pipes.bundle_names, 
186      wiz_read_only = False, 
187      can_be_none = True 
188  ) 
189  uf.backend = pipes.create 
190  # Description. 
191  uf.desc.append(Desc_container()) 
192  uf.desc[-1].add_paragraph("The data pipe name can be any string however the data pipe type can only be one of the following:") 
193  uf.desc[-1].add_item_list_element("'ct'", "Consistency testing,") 
194  uf.desc[-1].add_item_list_element("'frame order'", "The Frame Order theories,") 
195  uf.desc[-1].add_item_list_element("'jw'", "Reduced spectral density mapping,") 
196  uf.desc[-1].add_item_list_element("'hybrid'", "A special hybrid pipe,") 
197  uf.desc[-1].add_item_list_element("'mf'", "Model-free analysis,") 
198  uf.desc[-1].add_item_list_element("'N-state'", "N-state model or ensemble analysis,") 
199  uf.desc[-1].add_item_list_element("'noe'", "Steady state NOE calculation,") 
200  uf.desc[-1].add_item_list_element("'relax_disp'", "Relaxation dispersion curve fitting,") 
201  uf.desc[-1].add_item_list_element("'relax_fit'", "Relaxation curve fitting,") 
202  uf.desc[-1].add_paragraph("The pipe bundling concept is simply a way of grouping data pipes together.  This is useful for a number of purposes:") 
203  uf.desc[-1].add_list_element("The grouping or categorisation of data pipes, for example when multiple related analyses are performed.") 
204  uf.desc[-1].add_list_element("In the auto-analyses, as all the data pipes that they spawn are bound together within the original bundle.") 
205  uf.desc[-1].add_list_element("In the graphical user interface mode as analysis tabs are linked to specific pipe bundles.") 
206  # Prompt examples. 
207  uf.desc.append(Desc_container("Prompt examples")) 
208  uf.desc[-1].add_paragraph("To set up a model-free analysis data pipe with the name 'm5', type:") 
209  uf.desc[-1].add_prompt("relax> pipe.create('m5', 'mf')") 
210  uf.menu_text = "crea&te" 
211  uf.gui_icon = "oxygen.actions.list-add-relax-blue" 
212  uf.wizard_height_desc = 500 
213  uf.wizard_size = (1000, 750) 
214  uf.wizard_image = WIZARD_IMAGE_PATH + 'pipe.png' 
215   
216   
217  # The pipe.current user function. 
218  uf = uf_info.add_uf('pipe.current') 
219  uf.title = "Print the name of the current data pipe." 
220  uf.title_short = "Current data pipe printing." 
221  uf.display = True 
222  uf.backend = pipes.current 
223  # Prompt examples. 
224  uf.desc.append(Desc_container("Prompt examples")) 
225  uf.desc[-1].add_paragraph("To run the user function, type:") 
226  uf.desc[-1].add_prompt("relax> pipe.current()") 
227  uf.menu_text = "c&urrent" 
228  uf.gui_icon = "oxygen.actions.document-preview" 
229  uf.wizard_size = (600, 300) 
230  uf.wizard_image = WIZARD_IMAGE_PATH + 'pipe.png' 
231   
232   
233  # The pipe.delete user function. 
234  uf = uf_info.add_uf('pipe.delete') 
235  uf.title = "Delete a data pipe from the relax data store." 
236  uf.title_short = "Data pipe deletion." 
237  uf.add_keyarg( 
238      name = "pipe_name", 
239      py_type = "str", 
240      desc_short = "data pipe", 
241      desc = "The name of the data pipe to delete.", 
242      wiz_element_type = 'combo', 
243      wiz_combo_iter = pipes.pipe_names, 
244      can_be_none = True 
245  ) 
246  # Description. 
247  uf.desc.append(Desc_container()) 
248  uf.desc[-1].add_paragraph("This will permanently remove the data pipe and all of its contents from the relax data store.  If the pipe name is not given, then all data pipes will be deleted.") 
249  uf.backend = pipes.delete 
250  uf.menu_text = "&delete" 
251  uf.gui_icon = "oxygen.actions.list-remove" 
252  uf.wizard_image = WIZARD_IMAGE_PATH + 'pipe.png' 
253  uf.gui_sync = True    # Force synchronous operation to avoid the GUI from blowing up. 
254   
255   
256  # The pipe.display user function. 
257  uf = uf_info.add_uf('pipe.display') 
258  uf.title = "Print a list of all the data pipes." 
259  uf.title_short = "Data pipe listing." 
260  uf.display = True 
261  uf.backend = pipes.display 
262  # Prompt examples. 
263  uf.desc.append(Desc_container("Prompt examples")) 
264  uf.desc[-1].add_paragraph("To run the user function, type:") 
265  uf.desc[-1].add_prompt("relax> pipe.display()") 
266  uf.menu_text = "di&splay" 
267  uf.gui_icon = "oxygen.actions.document-preview" 
268  uf.wizard_size = (600, 300) 
269  uf.wizard_image = WIZARD_IMAGE_PATH + 'pipe.png' 
270   
271   
272  # The pipe.hybridise user function. 
273  uf = uf_info.add_uf('pipe.hybridise') 
274  uf.title = "Create a hybrid data pipe by fusing a number of other data pipes." 
275  uf.title_short = "Hybrid data pipe creation." 
276  uf.add_keyarg( 
277      name = "hybrid", 
278      py_type = "str", 
279      desc_short = "hybrid pipe name", 
280      desc = "The name of the hybrid data pipe to create." 
281  ) 
282  uf.add_keyarg( 
283      name = "pipes", 
284      py_type = "str_list", 
285      desc_short = "data pipes to hybridise", 
286      desc = "An array containing the names of all data pipes to hybridise.", 
287      wiz_element_type = 'combo_list', 
288      wiz_combo_iter = pipes.pipe_names, 
289      wiz_combo_list_min = 2 
290  ) 
291  uf.backend = hybrid_obj._hybridise 
292  # Description. 
293  uf.desc.append(Desc_container()) 
294  uf.desc[-1].add_paragraph("This user function can be used to construct hybrid models.  An example of the use of a hybrid model could be if the protein consists of two independent domains.  These two domains could be analysed separately, each having their own optimised diffusion tensors.  The N-terminal domain data pipe could be called 'N_sphere' while the C-terminal domain could be called 'C_ellipsoid'.  These two data pipes could then be hybridised into a single data pipe.  This hybrid data pipe can then be compared via model selection to a data pipe whereby the entire protein is assumed to have a single diffusion tensor.") 
295  uf.desc[-1].add_paragraph("The requirements for data pipes to be hybridised is that the molecules, sequences, and spin systems for all the data pipes is the same, and that no spin system is allowed to be selected in two or more data pipes.  The selections must not overlap to allow for rigorous statistical comparisons.") 
296  # Prompt examples. 
297  uf.desc.append(Desc_container("Prompt examples")) 
298  uf.desc[-1].add_paragraph("The two data pipes 'N_sphere' and 'C_ellipsoid' could be hybridised into a single data pipe called 'mixed model' by typing:") 
299  uf.desc[-1].add_prompt("relax> pipe.hybridise('mixed model', ['N_sphere', 'C_ellipsoid'])") 
300  uf.desc[-1].add_prompt("relax> pipe.hybridise(hybrid='mixed model', pipes=['N_sphere', 'C_ellipsoid'])") 
301  uf.menu_text = "&hybridise" 
302  uf.gui_icon = "relax.pipe_hybrid" 
303  uf.wizard_height_desc = 350 
304  uf.wizard_size = (1000, 750) 
305  uf.wizard_image = WIZARD_IMAGE_PATH + 'pipe_hybrid.png' 
306   
307   
308  # The pipe.switch user function. 
309  uf = uf_info.add_uf('pipe.switch') 
310  uf.title = "Switch between the data pipes of the relax data store." 
311  uf.title_short = "Data pipe switching." 
312  uf.add_keyarg( 
313      name = "pipe_name", 
314      py_type = "str", 
315      desc_short = "data pipe", 
316      desc = "The name of the data pipe.", 
317      wiz_element_type = 'combo', 
318      wiz_combo_iter = pipes.pipe_names 
319  ) 
320  uf.backend = pipes.switch 
321  # Description. 
322  uf.desc.append(Desc_container()) 
323  uf.desc[-1].add_paragraph("This will switch between the various data pipes within the relax data store.") 
324  # Prompt examples. 
325  uf.desc.append(Desc_container("Prompt examples")) 
326  uf.desc[-1].add_paragraph("To switch to the 'ellipsoid' data pipe, type:") 
327  uf.desc[-1].add_prompt("relax> pipe.switch('ellipsoid')") 
328  uf.desc[-1].add_prompt("relax> pipe.switch(pipe_name='ellipsoid')") 
329  uf.menu_text = "&switch" 
330  uf.gui_icon = "oxygen.actions.system-switch-user" 
331  uf.wizard_size = (700, 500) 
332  uf.wizard_apply_button = False 
333  uf.wizard_image = WIZARD_IMAGE_PATH + 'pipe_switch.png' 
334