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

Source Code for Module user_functions.dx

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2003-2005,2008-2009,2012-2013,2019 Edward d'Auvergne          # 
  4  # Copyright (C) 2014 Troels E. Linnet                                         # 
  5  #                                                                             # 
  6  # This file is part of the program relax (http://www.nmr-relax.com).          # 
  7  #                                                                             # 
  8  # This program is free software: you can redistribute it and/or modify        # 
  9  # it under the terms of the GNU General Public License as published by        # 
 10  # the Free Software Foundation, either version 3 of the License, or           # 
 11  # (at your option) any later version.                                         # 
 12  #                                                                             # 
 13  # This program is distributed in the hope that it will be useful,             # 
 14  # but WITHOUT ANY WARRANTY; without even the implied warranty of              # 
 15  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the               # 
 16  # GNU General Public License for more details.                                # 
 17  #                                                                             # 
 18  # You should have received a copy of the GNU General Public License           # 
 19  # along with this program.  If not, see <http://www.gnu.org/licenses/>.       # 
 20  #                                                                             # 
 21  ############################################################################### 
 22   
 23  # Module docstring. 
 24  """The dx user function definitions for controlling the OpenDX visualisation software.""" 
 25   
 26  # relax module imports. 
 27  from graphics import WIZARD_IMAGE_PATH 
 28  from lib.software.opendx.execute import run 
 29  from pipe_control.opendx import map 
 30  from specific_analyses.frame_order.parameter_object import Frame_order_params; frame_order_params = Frame_order_params() 
 31  from specific_analyses.model_free.parameter_object import Model_free_params; model_free_params = Model_free_params() 
 32  from specific_analyses.n_state_model.parameter_object import N_state_params; n_state_params = N_state_params() 
 33  from specific_analyses.relax_disp.parameter_object import Relax_disp_params; relax_disp_params = Relax_disp_params() 
 34  from user_functions.data import Uf_info; uf_info = Uf_info() 
 35  from user_functions.data import Uf_tables; uf_tables = Uf_tables() 
 36  from user_functions.objects import Desc_container 
 37   
 38   
 39  # The user function class. 
 40  uf_class = uf_info.add_class("dx") 
 41  uf_class.title = "Class for interfacing with OpenDX." 
 42  uf_class.menu_text = "&dx" 
 43  uf_class.gui_icon = "relax.opendx" 
 44   
 45   
 46  # The dx.execute user function. 
 47  uf = uf_info.add_uf("dx.execute") 
 48  uf.title = "Execute an OpenDX program." 
 49  uf.title_short = "OpenDX execution." 
 50  uf.add_keyarg( 
 51      name = "file_prefix", 
 52      default = "map", 
 53      basic_types = ["str"], 
 54      desc_short = "file name", 
 55      desc = "The file name prefix.  For example if file is set to 'temp', then the OpenDX program temp.net will be loaded." 
 56  ) 
 57  uf.add_keyarg( 
 58      name = "dir", 
 59      default = "dx", 
 60      arg_type = "dir sel", 
 61      desc_short = "directory name", 
 62      desc = "The directory to change to for running OpenDX.  If this is set to None, OpenDX will be run in the current directory.", 
 63      can_be_none = True 
 64  ) 
 65  uf.add_keyarg( 
 66      name = "dx_exe", 
 67      default = "dx", 
 68      arg_type = "file sel read", 
 69      desc_short = "OpenDX executable file name", 
 70      desc = "The OpenDX executable file.", 
 71      wiz_filesel_preview = False 
 72  ) 
 73  uf.add_keyarg( 
 74      name = "vp_exec", 
 75      default = True, 
 76      basic_types = ["bool"], 
 77      desc_short = "visual program execution flag", 
 78      desc = "A flag specifying whether to execute the visual program automatically at start-up.  The default of True causes the program to be executed." 
 79  ) 
 80  # Description. 
 81  uf.desc.append(Desc_container()) 
 82  uf.desc[-1].add_paragraph("This will execute OpenDX to display the space maps created previously by the dx.map user function.  This will work for any type of OpenDX map.") 
 83  uf.backend = run 
 84  uf.menu_text = "&execute" 
 85  uf.gui_icon = "oxygen.categories.applications-education" 
 86  uf.wizard_size = (700, 500) 
 87  uf.wizard_apply_button = False 
 88  uf.wizard_image = WIZARD_IMAGE_PATH + 'opendx.png' 
 89   
 90   
 91  # The dx.map user function. 
 92  uf = uf_info.add_uf("dx.map") 
 93  uf.title = "Create a map of the given space in OpenDX format." 
 94  uf.title_short = "OpenDX map creation." 
 95  uf.display = True 
 96  uf.add_keyarg( 
 97      name = "params", 
 98      basic_types = ["str"], 
 99      container_types = ["list"], 
100      dim = (None,), 
101      desc_short = "parameters", 
102      desc = "The parameters to be mapped.  This should be an array of strings, the meanings of which are described below." 
103  ) 
104  uf.add_keyarg( 
105      name = "map_type", 
106      default = "Iso3D", 
107      basic_types = ["str"], 
108      desc_short = "map type", 
109      desc = "The type of map to create.  For example the default, a 3D isosurface, the type is 'Iso3D'.  See below for more details.", 
110      wiz_element_type = "combo", 
111      wiz_combo_choices = ["Iso3D"], 
112      wiz_read_only = True, 
113  ) 
114  uf.add_keyarg( 
115      name = "spin_id", 
116      basic_types = ["str"], 
117      desc_short = "spin ID string", 
118      desc = "The spin ID string.", 
119      can_be_none = True 
120  ) 
121  uf.add_keyarg( 
122      name = "inc", 
123      default = 20, 
124      basic_types = ["int"], 
125      desc_short = "number of increments", 
126      desc = "The number of increments to map in each dimension.  This value controls the resolution of the map.", 
127      wiz_element_type = "spin" 
128  ) 
129  uf.add_keyarg( 
130      name = "lower", 
131      basic_types = ["number"], 
132      container_types = ["list", "numpy array"], 
133      dim = (None,), 
134      desc_short = "lower bounds", 
135      desc = "The lower bounds of the space.  If you wish to change the lower bounds of the map then supply an array of length equal to the number of parameters in the model.  A lower bound for each parameter must be supplied.  If nothing is supplied then the defaults will be used.", 
136      can_be_none = True 
137  ) 
138  uf.add_keyarg( 
139      name = "upper", 
140      basic_types = ["number"], 
141      container_types = ["list", "numpy array"], 
142      dim = (None,), 
143      desc_short = "upper bounds", 
144      desc = "The upper bounds of the space.  If you wish to change the upper bounds of the map then supply an array of length equal to the number of parameters in the model.  A upper bound for each parameter must be supplied.  If nothing is supplied then the defaults will be used.", 
145      can_be_none = True 
146  ) 
147  uf.add_keyarg( 
148      name = "axis_incs", 
149      default = 5, 
150      basic_types = ["int"], 
151      desc_short = "axis increments", 
152      desc = "The number of increments or ticks displaying parameter values along the axes of the OpenDX plot.", 
153      wiz_element_type = "spin" 
154  ) 
155  uf.add_keyarg( 
156      name = "file_prefix", 
157      default = "map", 
158      basic_types = ["str"], 
159      desc_short = "file prefix", 
160      desc = "The file name.  All the output files are prefixed with this name.  The main file containing the data points will be called the value of 'file'.  The OpenDX program will be called 'file.net' and the OpenDX import file will be called 'file.general'." 
161  ) 
162  uf.add_keyarg( 
163      name = "dir", 
164      default = "dx", 
165      arg_type = "dir sel", 
166      desc_short = "directory name", 
167      desc = "The directory to output files to.  Set this to 'None' if you do not want the files to be placed in subdirectory.  If the directory does not exist, it will be created.", 
168      can_be_none = True 
169  ) 
170  uf.add_keyarg( 
171      name = "point", 
172      basic_types = ["number"], 
173      container_types = ["list"], 
174      dim = [(3,), (None, 3)], 
175      desc_short = "highlight points in the space", 
176      desc = "This argument allows specific points in the optimisation space to be displayed as coloured spheres.  This can be used to highlight a minimum or other any other feature of the space.  Either a single point or a list of points can be supplied.  Each point is a list of floating point numbers in the form [x, y, z]", 
177      list_titles = ['X coordinate', 'Y coordinate', 'Z coordinate'], 
178      can_be_none = True 
179  ) 
180  uf.add_keyarg( 
181      name = "point_file", 
182      default = "point", 
183      basic_types = ["str"], 
184      desc_short = "point file name prefix", 
185      desc = "The name of that the point output files will be prefixed with.", 
186      can_be_none = True 
187  ) 
188  uf.add_keyarg( 
189      name = "chi_surface", 
190      default = None, 
191      basic_types = ["float"], 
192      container_types = ["list", "numpy array"], 
193      dim = (4,), 
194      desc_short = "Set the chi2 surface level for the Innermost, Inner, Middle and Outer Isosurface.", 
195      desc = "A list of 4 numbers, setting the level for the 4 isosurfaces. Useful in scripting if you create a set of OpenDX maps with all the same contour levels.  Ideal for comparisons.", 
196      can_be_none = True, 
197  ) 
198  uf.add_keyarg( 
199      name = "create_par_file", 
200      default = False, 
201      basic_types = ["bool"], 
202      desc_short = "creation of file with parameter and calculated chi2", 
203      desc = "A flag specifying whether to create a file with parameters and associated chi2 value.  The default of False causes the file not to be created." 
204  ) 
205  # Description. 
206  uf.desc.append(Desc_container()) 
207  uf.desc[-1].add_paragraph("This will map the space corresponding to the spin identifier and create the OpenDX files.  The map type can be changed to one of the following supported map types:") 
208  table = uf_tables.add_table(label="table: opendx map", caption="OpenDx mapping types.") 
209  table.add_headings(["Surface type", "Name"]) 
210  table.add_row(["3D isosurface", "'Iso3D'"]) 
211  uf.desc[-1].add_table(table.label) 
212  # Additional. 
213  uf.desc.append(model_free_params.uf_doc(label="table: all model-free parameters")) 
214  uf.desc.append(n_state_params.uf_doc(label="table: N-state parameters")) 
215  uf.desc.append(relax_disp_params.uf_doc(label="table: dispersion parameters")) 
216  uf.desc.append(frame_order_params.uf_doc(label="table: frame order parameters")) 
217  # Prompt examples. 
218  uf.desc.append(Desc_container("Prompt examples")) 
219  uf.desc[-1].add_paragraph("The following commands will generate a map of the extended model-free space for model 'm5' consisting of the parameters {S2, S2f, ts}.  Files will be output into the directory 'dx' and will be prefixed by 'map'.  In this case, the system is a protein and residue number 6 will be mapped.") 
220  uf.desc[-1].add_prompt("relax> dx.map(['s2', 's2f', 'ts'], spin_id=':6')") 
221  uf.desc[-1].add_prompt("relax> dx.map(['s2', 's2f', 'ts'], spin_id=':6', file_prefix='map', dir='dx')") 
222  uf.desc[-1].add_prompt("relax> dx.map(params=['s2', 's2f', 'ts'], spin_id=':6', inc=20, file_prefix='map', dir='dx')") 
223  uf.desc[-1].add_prompt("relax> dx.map(params=['s2', 's2f', 'ts'], spin_id=':6', map_type='Iso3D', inc=20, file_prefix='map', dir='dx')") 
224  uf.desc[-1].add_paragraph("To map the model-free space 'm4' for residue 2, spin N6 defined by the parameters {S2, te, Rex}, name the results 'test', and to place the files in the current directory, use one of the following commands:") 
225  uf.desc[-1].add_prompt("relax> dx.map(['s2', 'te', 'rex'], spin_id=':2@N6', file_prefix='test', dir=None)") 
226  uf.desc[-1].add_prompt("relax> dx.map(params=['s2', 'te', 'rex'], spin_id=':2@N6', inc=100, file_prefix='test', dir=None)") 
227  uf.backend = map 
228  uf.menu_text = "&map" 
229  uf.gui_icon = "relax.grid_search" 
230  uf.wizard_height_desc = 260 
231  uf.wizard_size = (1000, 750) 
232  uf.wizard_image = WIZARD_IMAGE_PATH + 'opendx.png' 
233