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

Source Code for Module user_functions.n_state_model

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2008-2010,2012,2019 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 n_state_model user function definitions.""" 
 24   
 25  # relax module imports. 
 26  from graphics import WIZARD_IMAGE_PATH 
 27  from specific_analyses.n_state_model import uf as n_state_model_uf 
 28  from specific_analyses.n_state_model.parameters import elim_no_prob, number_of_states, ref_domain, select_model 
 29  from user_functions.data import Uf_info; uf_info = Uf_info() 
 30  from user_functions.objects import Desc_container 
 31  from user_functions.wildcards import WILDCARD_STRUCT_PDB_ALL 
 32   
 33   
 34  # The user function class. 
 35  uf_class = uf_info.add_class('n_state_model') 
 36  uf_class.title = "Class for the N-state models." 
 37  uf_class.menu_text = "&n_state_model" 
 38  uf_class.gui_icon = "relax.n_state_model" 
 39   
 40   
 41  # The n_state_model.CoM user function. 
 42  uf = uf_info.add_uf('n_state_model.CoM') 
 43  uf.title = "The defunct centre of mass (CoM) analysis." 
 44  uf.title_short = "CoM analysis." 
 45  uf.add_keyarg( 
 46      name = "pivot_point", 
 47      default = [0.0, 0.0, 0.0], 
 48      basic_types = ["number"], 
 49      container_types = ["list"], 
 50      dim = (3,), 
 51      desc_short = "pivot point", 
 52      desc = "The pivot point of the motions between the two domains.", 
 53      list_titles = ['X coordinate', 'Y coordinate', 'Z coordinate'] 
 54  ) 
 55  uf.add_keyarg( 
 56      name = "centre", 
 57      basic_types = ["number"], 
 58      container_types = ["list"], 
 59      dim = (3,), 
 60      desc_short = "centre of mass", 
 61      desc = "Manually specify the CoM of the initial position prior to the N rotations to the positions of the N states.  This is optional.", 
 62      list_titles = ['X coordinate', 'Y coordinate', 'Z coordinate'], 
 63      can_be_none = True 
 64  ) 
 65  # Description. 
 66  uf.desc.append(Desc_container()) 
 67  uf.desc[-1].add_paragraph("WARNING:  This analysis is now defunct!") 
 68  uf.desc[-1].add_paragraph("This is used for analysing the domain motion information content of the N states from the N-state model.  The states do not correspond to physical states, hence nothing can be extracted from the individual states.  This analysis involves the calculation of the pivot to centre of mass (pivot-CoM) order parameter and subsequent cone of motions.") 
 69  uf.desc[-1].add_paragraph("For the analysis, both the pivot point and centre of mass must be specified.  The supplied pivot point must be a vector of floating point numbers of length 3.  If the centre of mass is supplied, it must also be a vector of floating point numbers (of length 3).  If the centre of mass is not supplied, then the CoM will be calculated from the selected parts of a previously loaded structure.") 
 70  # Prompt examples. 
 71  uf.desc.append(Desc_container("Prompt examples")) 
 72  uf.desc[-1].add_paragraph("To perform an analysis where the pivot is at the origin and the CoM is set to the N-terminal domain of a previously loaded PDB file (the C-terminal domain has been deselected), type:") 
 73  uf.desc[-1].add_prompt("relax> n_state_model.CoM()") 
 74  uf.desc[-1].add_paragraph("To perform an analysis where the pivot is at the origin (because the real pivot has been shifted to this position) and the CoM is at the position [0, 0, 1], type one of:") 
 75  uf.desc[-1].add_prompt("relax> n_state_model.CoM(centre=[0, 0, 1])") 
 76  uf.desc[-1].add_prompt("relax> n_state_model.CoM(centre=[0.0, 0.0, 1.0])") 
 77  uf.desc[-1].add_prompt("relax> n_state_model.CoM(pivot_point=[0.0, 0.0, 0.0], centre=[0.0, 0.0, 1.0])") 
 78  uf.backend = n_state_model_uf.CoM 
 79  uf.menu_text = "Co&M" 
 80  uf.wizard_height_desc = 350 
 81  uf.wizard_size = (800, 600) 
 82  uf.wizard_apply_button = False 
 83  uf.wizard_image = WIZARD_IMAGE_PATH + 'n_state_model.png' 
 84   
 85   
 86  # The n_state_model.cone_pdb user function. 
 87  uf = uf_info.add_uf('n_state_model.cone_pdb') 
 88  uf.title = "Create a PDB file representing the cone models from the centre of mass (CoM) analysis." 
 89  uf.title_short = "Cone PDB creation." 
 90  uf.add_keyarg( 
 91      name = "cone_type", 
 92      basic_types = ["str"], 
 93      desc_short = "cone type", 
 94      desc = "The type of cone model to represent.", 
 95      wiz_element_type = "combo", 
 96      wiz_combo_choices = [ 
 97          'diff in cone', 
 98          'diff on cone' 
 99      ], 
100      wiz_read_only = True 
101  ) 
102   
103  uf.add_keyarg( 
104      name = "scale", 
105      default = 1.0, 
106      basic_types = ["number"], 
107      desc_short = "scaling factor", 
108      desc = "Value for scaling the pivot-CoM distance which the size of the cone defaults to." 
109  ) 
110   
111  uf.add_keyarg( 
112      name = "file", 
113      default = "cone.pdb", 
114      arg_type = "file sel write", 
115      desc_short = "file name", 
116      desc = "The name of the PDB file.", 
117      wiz_filesel_wildcard = WILDCARD_STRUCT_PDB_ALL, 
118  ) 
119   
120  uf.add_keyarg( 
121      name = "dir", 
122      arg_type = "dir", 
123      desc_short = "directory name", 
124      desc = "The directory where the file is located.", 
125      can_be_none = True 
126  ) 
127   
128  uf.add_keyarg( 
129      name = "force", 
130      default = False, 
131      basic_types = ["bool"], 
132      desc_short = "force flag", 
133      desc = "A flag which, if set to True, will overwrite the any pre-existing file." 
134  ) 
135  # Description. 
136  uf.desc.append(Desc_container()) 
137  uf.desc[-1].add_paragraph("WARNING:  This analysis is now defunct!") 
138  uf.desc[-1].add_paragraph("This creates a PDB file containing an artificial geometric structure to represent the various cone models.  These models include:") 
139  uf.desc[-1].add_list_element("'diff in cone'") 
140  uf.desc[-1].add_list_element("'diff on cone'") 
141  uf.desc[-1].add_paragraph("The model can be selected by setting the cone type to one of these values.  The cone is represented as an isotropic cone with its axis parallel to the average pivot-CoM vector, the vertex placed at the pivot point of the domain motions, and the length of the edge of the cone equal to the pivot-CoM distance multiplied by the scaling factor.  The resultant PDB file can subsequently read into any molecular viewer.") 
142  uf.desc[-1].add_paragraph("There are four different types of residue within the PDB.  The pivot point is represented as as a single carbon atom of the residue 'PIV'.  The cone consists of numerous H atoms of the residue 'CON'.  The average pivot-CoM vector is presented as the residue 'AVE' with one carbon atom positioned at the pivot and the other at the head of the vector (after scaling by the scaling factor).  Finally, if Monte Carlo have been performed, there will be multiple 'MCC' residues representing the cone for each simulation, and multiple 'MCA' residues representing the varying average pivot-CoM vector for each simulation.") 
143  uf.desc[-1].add_paragraph("To create the diffusion in a cone PDB representation, a uniform distribution of vectors on a sphere is generated using spherical coordinates with the polar angle defined from the average pivot-CoM vector.  By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors.  These are all placed into the PDB file as H atoms and are all connected using PDB CONECT records.  Each H atom is connected to its two neighbours on the both the longitude and latitude.  This creates a geometric PDB object with longitudinal and latitudinal lines representing the filled cone.") 
144  uf.backend = n_state_model_uf.cone_pdb 
145  uf.menu_text = "&cone_pdb" 
146  uf.wizard_height_desc = 480 
147  uf.wizard_size = (1000, 750) 
148  uf.wizard_apply_button = False 
149  uf.wizard_image = WIZARD_IMAGE_PATH + 'n_state_model.png' 
150   
151   
152  # The n_state_model.elim_no_prob user function. 
153  uf = uf_info.add_uf('n_state_model.elim_no_prob') 
154  uf.title = "Eliminate the structures or states with no probability." 
155  uf.title_short = "Insignificant state elimination." 
156  # Description. 
157  uf.desc.append(Desc_container()) 
158  uf.desc[-1].add_paragraph("This will simply remove the structures from the N-state analysis which have an optimised probability of zero.") 
159  # Prompt examples. 
160  uf.desc.append(Desc_container("Prompt examples")) 
161  uf.desc[-1].add_paragraph("Simply type:") 
162  uf.desc[-1].add_prompt("relax> n_state_model.elim_no_prob(N=8)") 
163  uf.backend = elim_no_prob 
164  uf.menu_text = "&elim_no_prob" 
165  uf.gui_icon = "oxygen.actions.list-remove" 
166  uf.wizard_size = (700, 400) 
167  uf.wizard_apply_button = False 
168  uf.wizard_image = WIZARD_IMAGE_PATH + 'n_state_model.png' 
169   
170   
171  # The n_state_model.number_of_states user function. 
172  uf = uf_info.add_uf('n_state_model.number_of_states') 
173  uf.title = "Set the number of states in the N-state model." 
174  uf.title_short = "Number of states." 
175  uf.add_keyarg( 
176      name = "N", 
177      default = 1, 
178      basic_types = ["int"], 
179      desc_short = "number of states N", 
180      desc = "The number of states." 
181  ) 
182  # Description. 
183  uf.desc.append(Desc_container()) 
184  uf.desc[-1].add_paragraph("Prior to optimisation, the number of states in the N-state model can be specified.  If the number of states is not set, then this parameter will be equal to the number of loaded structures - the ensemble size.") 
185  # Prompt examples. 
186  uf.desc.append(Desc_container("Prompt examples")) 
187  uf.desc[-1].add_paragraph("To set up an 8-state model, type:") 
188  uf.desc[-1].add_prompt("relax> n_state_model.number_of_states(N=8)") 
189  uf.backend = number_of_states 
190  uf.menu_text = "&number_of_states" 
191  uf.gui_icon = "oxygen.actions.edit-rename" 
192  uf.wizard_apply_button = False 
193  uf.wizard_image = WIZARD_IMAGE_PATH + 'n_state_model.png' 
194   
195   
196  # The n_state_model.ref_domain user function. 
197  uf = uf_info.add_uf('n_state_model.ref_domain') 
198  uf.title = "Set the reference domain for the '2-domain' N-state model." 
199  uf.title_short = "Reference domain identification." 
200  uf.add_keyarg( 
201      name = "ref", 
202      basic_types = ["str"], 
203      desc_short = "reference frame", 
204      desc = "The domain which will act as the frame of reference.  This is only valid for the '2-domain' N-state model." 
205  ) 
206  # Description. 
207  uf.desc.append(Desc_container()) 
208  uf.desc[-1].add_paragraph("Prior to optimisation of the '2-domain' N-state model, which of the two domains will act as the frame of reference must be specified.  The N-states will be rotations of the other domain, so to switch the frame of reference to the other domain simply transpose the rotation matrices.") 
209  # Prompt examples. 
210  uf.desc.append(Desc_container("Prompt examples")) 
211  uf.desc[-1].add_paragraph("To set up a 5-state model with 'C' domain being the frame of reference, type:") 
212  uf.desc[-1].add_prompt("relax> n_state_model.ref_domain(ref='C')") 
213  uf.backend = ref_domain 
214  uf.menu_text = "&ref_domain" 
215  uf.gui_icon = "oxygen.actions.edit-rename" 
216  uf.wizard_image = WIZARD_IMAGE_PATH + 'n_state_model.png' 
217   
218   
219  # The n_state_model.select_model user function. 
220  uf = uf_info.add_uf('n_state_model.select_model') 
221  uf.title = "Select the N-state model type and set up the model." 
222  uf.title_short = "N-state model choice." 
223  uf.add_keyarg( 
224      name = "model", 
225      default = "population", 
226      basic_types = ["str"], 
227      desc_short = "model", 
228      desc = "The name of the preset N-state model.", 
229      wiz_element_type = "combo", 
230      wiz_combo_choices = ["population", "fixed", "2-domain"], 
231      wiz_read_only = True 
232  ) 
233  # Description. 
234  uf.desc.append(Desc_container()) 
235  uf.desc[-1].add_paragraph("Prior to optimisation, the N-state model type should be selected.  The preset models are:") 
236  uf.desc[-1].add_item_list_element("'population'", "The N-state model whereby only populations are optimised.  The structures loaded into relax are assumed to be fixed, i.e. the orientations are not optimised, or if two domains are present the Euler angles for each state are fixed.  The parameters of the model include the weight or probability for each state and the alignment tensors - {p0, p1, ..., pN, Axx, Ayy, Axy, Axz, Ayz, ...}.") 
237  uf.desc[-1].add_item_list_element("'fixed'", "The N-state model whereby all motions are fixed and all populations are fixed to the set probabilities.  The parameters of the model are simply the parameters of each alignment tensor {Axx, Ayy, Axy, Axz, Ayz, ...}.") 
238  uf.desc[-1].add_item_list_element("'2-domain'", "The N-state model for a system of two domains, where one domain experiences a reduced tensor.") 
239  # Prompt examples. 
240  uf.desc.append(Desc_container("Prompt examples")) 
241  uf.desc[-1].add_paragraph("To analyse populations of states, type:") 
242  uf.desc[-1].add_prompt("relax> n_state_model.select_model(model='populations')") 
243  uf.backend = select_model 
244  uf.menu_text = "&select_model" 
245  uf.gui_icon = "oxygen.actions.list-add" 
246  uf.wizard_height_desc = 400 
247  uf.wizard_size = (800, 600) 
248  uf.wizard_image = WIZARD_IMAGE_PATH + 'n_state_model.png' 
249