Source Code for Module specific_analyses.relax_disp.parameter_object

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2014 Edward d'Auvergne                                        # 
  4  # Copyright (C) 2009 Sebastien Morin                                          # 
  5  # Copyright (C) 2014 Troels E. Linnet                                         # 
  6  #                                                                             # 
  7  # This file is part of the program relax (http://www.nmr-relax.com).          # 
  8  #                                                                             # 
  9  # This program is free software: you can redistribute it and/or modify        # 
 10  # it under the terms of the GNU General Public License as published by        # 
 11  # the Free Software Foundation, either version 3 of the License, or           # 
 12  # (at your option) any later version.                                         # 
 13  #                                                                             # 
 14  # This program is distributed in the hope that it will be useful,             # 
 15  # but WITHOUT ANY WARRANTY; without even the implied warranty of              # 
 16  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the               # 
 17  # GNU General Public License for more details.                                # 
 18  #                                                                             # 
 19  # You should have received a copy of the GNU General Public License           # 
 20  # along with this program.  If not, see <http://www.gnu.org/licenses/>.       # 
 21  #                                                                             # 
 22  ############################################################################### 
 23   
 24  # Module docstring. 
 25  """The module for the relaxation dispersion parameter list object.""" 
 26   
 27  # relax module imports. 
 28  from lib.dispersion.variables import MODEL_LIST_MMQ, MODEL_M61B 
 29  from lib.mathematics import round_to_next_order 
 30  from pipe_control.mol_res_spin import return_spin 
 31  from specific_analyses.parameter_object import Param_list 
 32   
 33   
 34 -def dw_lower(incs=None, model_info=None): 
 35      """Determine the lower grid bound for the dw parameters. 
 36   
 37      @keyword incs:          The number of grid search increments. 
 38      @type incs:             int 
 39      @keyword model_info:    The spin ID strings from the model_loop() specific API method. 
 40      @type model_info:       list of str 
 41      @return:                The lower grid search bound for the dw parameters. 
 42      @rtype:                 float 
 43      """ 
 44   
 45      # Fetch the first spin container. 
 46      spin0 = return_spin(model_info[0]) 
 47   
 48      # The MMQ models. 
 49      if spin0.model in MODEL_LIST_MMQ: 
 50          return -10.0 
 51   
 52      # All other models. 
 53      else: 
 54          return 0.0 
 55   
 56   
 57 -def dwH_lower(incs=None, model_info=None): 
 58      """Determine the lower grid bound for the dwH parameters. 
 59   
 60      @keyword incs:          The number of grid search increments. 
 61      @type incs:             int 
 62      @keyword model_info:    The spin ID strings from the model_loop() specific API method. 
 63      @type model_info:       list of str 
 64      @return:                The lower grid search bound for the dwH parameters. 
 65      @rtype:                 float 
 66      """ 
 67   
 68      # Fetch the first spin container. 
 69      spin0 = return_spin(model_info[0]) 
 70   
 71      # The MMQ models. 
 72      if spin0.model in MODEL_LIST_MMQ: 
 73          return -3.0 
 74   
 75      # All other models. 
 76      else: 
 77          return 0.0 
 78   
 79   
 80 -def pA_lower(incs=None, model_info=None): 
 81      """Determine the lower grid bound for the pA parameter. 
 82   
 83      @keyword incs:          The number of grid search increments. 
 84      @type incs:             int 
 85      @keyword model_info:    The spin containers and the spin ID strings from the model_loop() specific API method. 
 86      @type model_info:       list of SpinContainer instances, list of str 
 87      @return:                The lower grid search bound for the pA parameter. 
 88      @rtype:                 float 
 89      """ 
 90   
 91      # Fetch the first spin container. 
 92      spin0 = return_spin(model_info[0]) 
 93   
 94      # The MMQ models. 
 95      if spin0.model == MODEL_M61B: 
 96          return 0.85 
 97   
 98      # All other models. 
 99      else: 
100          return 0.5 
101   
102   
103 -def i0_upper(incs=None, model_info=None): 
104      """Find the maximum peak intensity for the cluster. 
105   
106      This is for the grid search upper bound for the I0 parameter. 
107   
108   
109      @keyword incs:          The number of grid search increments. 
110      @type incs:             int 
111      @keyword model_info:    The spin containers and the spin ID strings from the model_loop() specific API method. 
112      @type model_info:       list of SpinContainer instances, list of str 
113      @return:                The maximum peak intensity of all spins and time points. 
114      @rtype:                 float 
115      """ 
116   
117      # Alias. 
118      spin_ids = model_info 
119   
120      # Find the maximum intensity. 
121      upper = 0.0 
122      for si in range(len(spin_ids)): 
123          spin = return_spin(spin_ids[si]) 
124          upper = max(upper, max(spin.peak_intensity.values())) 
125   
126      # Multiply the value by 2.0 and then round up to the next order - this will be the upper bound. 
127      return round_to_next_order(upper * 2.0) 
128   
129   
130   
131 -class Relax_disp_params(Param_list): 
132      """The relaxation dispersion parameter list singleton.""" 
133   
134      # Class variable for storing the class instance (for the singleton design pattern). 
135      _instance = None 
136   
137 -    def __init__(self): 
138          """Define all the parameters of the analysis.""" 
139   
140          # The object is already initialised. 
141          if self._initialised: return 
142   
143          # Execute the base class __init__ method. 
144          Param_list.__init__(self) 
145   
146          # Add the base data for the 'R2eff' model. 
147          self._add_peak_intensity() 
148   
149          # Add the signal to noise ratio. 
150          self._add_sn_ratio() 
151   
152          # Add the base information for the dispersion analysis. 
153          self._add( 
154              'relax_times', 
155              scope = 'spin', 
156              py_type = dict, 
157              grace_string = '\\qRelaxation time period (s)\\Q' 
158          ) 
159          self._add( 
160              'cpmg_frqs', 
161              scope = 'spin', 
162              py_type = dict, 
163              grace_string = '\\qCPMG pulse train frequency (Hz)\\Q' 
164          ) 
165          self._add( 
166              'spin_lock_nu1', 
167              scope = 'spin', 
168              py_type = dict, 
169              grace_string = '\\qSpin-lock field strength (Hz)\\Q' 
170          ) 
171   
172          # Add the model variables. 
173          self._add_model_info() 
174   
175          # Add the parameters of the 'R2eff' model. 
176          self._add( 
177              'r2eff', 
178              scope = 'spin', 
179              default = 10.0, 
180              desc = 'The effective transversal relaxation rate', 
181              py_type = dict, 
182              set = 'params', 
183              grid_lower = 1.0, 
184              grid_upper = 40.0, 
185              grace_string = '\\qR\\s2,eff\\N\\Q (rad.s\\S-1\\N)', 
186              err = True, 
187              sim = True 
188          ) 
189          self._add( 
190              'i0', 
191              scope = 'spin', 
192              default = 10000.0, 
193              desc = 'The initial intensity', 
194              py_type = dict, 
195              set = 'params', 
196              grid_lower = 0.0001, 
197              grid_upper = i0_upper, 
198              grace_string = '\\qI\\s0\\Q', 
199              err = True, 
200              sim = True 
201          ) 
202   
203          # Add the parameters of all dispersion models. 
204          self._add( 
205              'r1', 
206              scope = 'spin', 
207              default = 2.0, 
208              desc = 'The longitudinal relaxation rate', 
209              py_type = dict, 
210              set = 'params', 
211              scaling = 10, 
212              grid_lower = 0.1, 
213              grid_upper = 20.0, 
214              grace_string = '\\qR\\s1\\N\\Q (rad.s\\S-1\\N)', 
215              err = True, 
216              sim = True 
217          ) 
218          self._add( 
219              'r2', 
220              scope = 'spin', 
221              default = 10.0, 
222              desc = 'The transversal relaxation rate', 
223              py_type = dict, 
224              set = 'params', 
225              scaling = 10, 
226              grid_lower = 5.0, 
227              grid_upper = 20.0, 
228              grace_string = '\\qR\\s2\\N\\Q (rad.s\\S-1\\N)', 
229              err = True, 
230              sim = True 
231          ) 
232          self._add( 
233              'r2a', 
234              scope = 'spin', 
235              default = 10.0, 
236              desc = 'The transversal relaxation rate for state A in the absence of exchange', 
237              py_type = dict, 
238              set = 'params', 
239              scaling = 10, 
240              grid_lower = 5.0, 
241              grid_upper = 20.0, 
242              grace_string = '\\qR\\s2,A\\N\\Q (rad.s\\S-1\\N)', 
243              err = True, 
244              sim = True 
245          ) 
246          self._add( 
247              'r2b', 
248              scope = 'spin', 
249              default = 10.0, 
250              desc = 'The transversal relaxation rate for state B in the absence of exchange', 
251              py_type = dict, 
252              set = 'params', 
253              scaling = 10, 
254              grid_lower = 5.0, 
255              grid_upper = 20.0, 
256              grace_string = '\\qR\\s2,B\\N\\Q (rad.s\\S-1\\N)', 
257              err = True, 
258              sim = True 
259          ) 
260          self._add( 
261              'pA', 
262              scope = 'spin', 
263              default = 0.90, 
264              desc = 'The population for state A', 
265              py_type = float, 
266              set = 'params', 
267              grid_lower = pA_lower, 
268              grid_upper = 1.0, 
269              grace_string = '\\qp\\sA\\N\\Q', 
270              err = True, 
271              sim = True 
272          ) 
273          self._add( 
274              'pB', 
275              scope = 'spin', 
276              default = 0.5, 
277              desc = 'The population for state B', 
278              py_type = float, 
279              set = 'params', 
280              grid_lower = 0.0, 
281              grid_upper = 0.5, 
282              grace_string = '\\qp\\sB\\N\\Q', 
283              err = True, 
284              sim = True 
285          ) 
286          self._add( 
287              'pC', 
288              scope = 'spin', 
289              default = 0.5, 
290              desc = 'The population for state C', 
291              py_type = float, 
292              set = 'params', 
293              grace_string = '\\qp\\sC\\N\\Q', 
294              err = True, 
295              sim = True 
296          ) 
297          self._add( 
298              'phi_ex', 
299              scope = 'spin', 
300              default = 5.0, 
301              desc = 'The phi_ex = pA.pB.dw**2 value (ppm^2)', 
302              py_type = float, 
303              set = 'params', 
304              grid_lower = 0.0, 
305              grid_upper = 10.0, 
306              grace_string = '\\xF\\B\\sex\\N = \\q p\\sA\\N.p\\sB\\N.\\xDw\\B\\S2\\N\\Q  (ppm\\S2\\N)', 
307              err = True, 
308              sim = True 
309          ) 
310          self._add( 
311              'phi_ex_B', 
312              scope = 'spin', 
313              default = 5.0, 
314              desc = 'The fast exchange factor between sites A and B (ppm^2)', 
315              py_type = float, 
316              set = 'params', 
317              grid_lower = 0.0, 
318              grid_upper = 10.0, 
319              grace_string = '\\xF\\B\\sex,B\\N (ppm\\S2\\N)', 
320              err = True, 
321              sim = True 
322          ) 
323          self._add( 
324              'phi_ex_C', 
325              scope = 'spin', 
326              default = 5.0, 
327              desc = 'The fast exchange factor between sites A and C (ppm^2)', 
328              py_type = float, 
329              set = 'params', 
330              grid_lower = 0.0, 
331              grid_upper = 10.0, 
332              grace_string = '\\xF\\B\\sex,C\\N (ppm\\S2\\N)', 
333              err = True, 
334              sim = True 
335          ) 
336          self._add( 
337              'padw2', 
338              scope = 'spin', 
339              default = 1.0, 
340              desc = 'The pA.dw**2 value (ppm^2)', 
341              py_type = float, 
342              set = 'params', 
343              grid_lower = 0.0, 
344              grid_upper = 10.0, 
345              grace_string = '\\qp\\sA\\N.\\xDw\\B\\S2\\N\\Q  (ppm\\S2\\N)', 
346              err = True, 
347              sim = True 
348          ) 
349          self._add( 
350              'dw', 
351              scope = 'spin', 
352              default = 1.0, 
353              desc = 'The chemical shift difference between states A and B (in ppm)', 
354              py_type = float, 
355              set = 'params', 
356              grid_lower = dw_lower, 
357              grid_upper = 10.0, 
358              grace_string = '\\q\\xDw\\B\\Q (ppm)', 
359              err = True, 
360              sim = True 
361          ) 
362          self._add( 
363              'dw_AB', 
364              scope = 'spin', 
365              default = 1.0, 
366              desc = 'The chemical shift difference between states A and B for 3-site exchange (in ppm)', 
367              py_type = float, 
368              set = 'params', 
369              grid_lower = dw_lower, 
370              grid_upper = 10.0, 
371              grace_string = '\\q\\xDw\\B\\Q\\SAB\\N (ppm)', 
372              err = True, 
373              sim = True 
374          ) 
375          self._add( 
376              'dw_AC', 
377              scope = 'spin', 
378              default = 1.0, 
379              desc = 'The chemical shift difference between states A and C for 3-site exchange (in ppm)', 
380              py_type = float, 
381              set = 'params', 
382              grid_lower = dw_lower, 
383              grid_upper = 10.0, 
384              grace_string = '\\q\\xDw\\B\\Q\\SAC\\N (ppm)', 
385              err = True, 
386              sim = True 
387          ) 
388          self._add( 
389              'dw_BC', 
390              scope = 'spin', 
391              default = 1.0, 
392              desc = 'The chemical shift difference between states B and C for 3-site exchange (in ppm)', 
393              py_type = float, 
394              set = 'params', 
395              grid_lower = dw_lower, 
396              grid_upper = 10.0, 
397              grace_string = '\\q\\xDw\\B\\Q\\SBC\\N (ppm)', 
398              err = True, 
399              sim = True 
400          ) 
401          self._add( 
402              'dwH', 
403              scope = 'spin', 
404              default = 1.0, 
405              desc = 'The proton chemical shift difference between states A and B (in ppm)', 
406              py_type = float, 
407              set = 'params', 
408              grid_lower = dwH_lower, 
409              grid_upper = 3.0, 
410              grace_string = '\\q\\xDw\\B\\sH\\N\\Q (ppm)', 
411              err = True, 
412              sim = True 
413          ) 
414          self._add( 
415              'dwH_AB', 
416              scope = 'spin', 
417              default = 1.0, 
418              desc = 'The proton chemical shift difference between states A and B for 3-site exchange (in ppm)', 
419              py_type = float, 
420              set = 'params', 
421              grid_lower = dwH_lower, 
422              grid_upper = 3.0, 
423              grace_string = '\\q\\xDw\\B\\sH\\N\\Q\\SAB\\N (ppm)', 
424              err = True, 
425              sim = True 
426          ) 
427          self._add( 
428              'dwH_AC', 
429              scope = 'spin', 
430              default = 1.0, 
431              desc = 'The proton chemical shift difference between states A and C for 3-site exchange (in ppm)', 
432              py_type = float, 
433              set = 'params', 
434              grid_lower = dwH_lower, 
435              grid_upper = 3.0, 
436              grace_string = '\\q\\xDw\\B\\sH\\N\\Q\\SAC\\N (ppm)', 
437              err = True, 
438              sim = True 
439          ) 
440          self._add( 
441              'dwH_BC', 
442              scope = 'spin', 
443              default = 1.0, 
444              desc = 'The proton chemical shift difference between states B and C for 3-site exchange (in ppm)', 
445              py_type = float, 
446              set = 'params', 
447              grid_lower = dwH_lower, 
448              grid_upper = 3.0, 
449              grace_string = '\\q\\xDw\\B\\sH\\N\\Q\\SBC\\N (ppm)', 
450              err = True, 
451              sim = True 
452          ) 
453          self._add( 
454              'kex', 
455              scope = 'spin', 
456              default = 1000.0, 
457              desc = 'The exchange rate', 
458              py_type = float, 
459              set = 'params', 
460              scaling = 10000, 
461              grid_lower = 1.0, 
462              grid_upper = 10000.0, 
463              grace_string = '\\qk\\sex\\N\\Q (rad.s\\S-1\\N)', 
464              err = True, 
465              sim = True 
466          ) 
467          self._add( 
468              'kex_AB', 
469              scope = 'spin', 
470              default = 1000.0, 
471              desc = 'The exchange rate between sites A and B for 3-site exchange with kex_AB = k_AB + k_BA (rad.s^-1)', 
472              py_type = float, 
473              set = 'params', 
474              scaling = 10000, 
475              grid_lower = 1.0, 
476              grid_upper = 10000.0, 
477              grace_string = '\\qk\\sex\\N\\Q\\SAB\\N (rad.s\\S-1\\N)', 
478              err = True, 
479              sim = True 
480          ) 
481          self._add( 
482              'kex_AC', 
483              scope = 'spin', 
484              default = 1000.0, 
485              desc = 'The exchange rate between sites A and C for 3-site exchange with kex_AC = k_AC + k_CA (rad.s^-1)', 
486              py_type = float, 
487              set = 'params', 
488              scaling = 10000, 
489              grid_lower = 1.0, 
490              grid_upper = 10000.0, 
491              grace_string = '\\qk\\sex\\N\\Q\\SAC\\N (rad.s\\S-1\\N)', 
492              err = True, 
493              sim = True 
494          ) 
495          self._add( 
496              'kex_BC', 
497              scope = 'spin', 
498              default = 1000.0, 
499              desc = 'The exchange rate between sites B and C for 3-site exchange with kex_BC = k_BC + k_CB (rad.s^-1)', 
500              py_type = float, 
501              set = 'params', 
502              scaling = 10000, 
503              grid_lower = 1.0, 
504              grid_upper = 10000.0, 
505              grace_string = '\\qk\\sex\\N\\Q\\SBC\\N (rad.s\\S-1\\N)', 
506              err = True, 
507              sim = True 
508          ) 
509          self._add( 
510              'kB', 
511              scope = 'spin', 
512              default = 1000.0, 
513              desc = 'Approximate chemical exchange rate constant between sites A and B (rad.s^-1)', 
514              py_type = float, 
515              set = 'params', 
516              scaling = 10000, 
517              grid_lower = 1.0, 
518              grid_upper = 10000.0, 
519              grace_string = '\\qk\\sB\\N\\Q (rad.s\\S-1\\N)', 
520              err = True, 
521              sim = True 
522          ) 
523          self._add( 
524              'kC', 
525              scope = 'spin', 
526              default = 1000.0, 
527              desc = 'Approximate chemical exchange rate constant between sites A and C (rad.s^-1)', 
528              py_type = float, 
529              set = 'params', 
530              scaling = 10000, 
531              grid_lower = 1.0, 
532              grid_upper = 10000.0, 
533              grace_string = '\\qk\\sC\\N\\Q (rad.s\\S-1\\N)', 
534              err = True, 
535              sim = True 
536          ) 
537          self._add( 
538              'tex', 
539              scope = 'spin', 
540              default = 1.0/1000.0, 
541              desc = 'The time of exchange (tex = 1/kex)', 
542              py_type = float, 
543              set = 'params', 
544              scaling = 1e-4, 
545              grid_lower = 1/10000.0, 
546              grid_upper = 1.0, 
547              grace_string = '\\q\\xt\\B\\sex\\N\\Q (s.rad\\S-1\\N)', 
548              err = True, 
549              sim = True 
550          ) 
551          self._add( 
552              'theta', 
553              scope = 'spin', 
554              desc = 'Rotating frame tilt angle : ( theta = arctan(w_1 / Omega) ) (rad)', 
555              grace_string = 'Rotating frame tilt angle (rad)', 
556              py_type = dict, 
557              set = 'all', 
558              err = False, 
559              sim = False 
560          ) 
561          self._add( 
562              'w_eff', 
563              scope = 'spin', 
564              desc = 'Effective field in rotating frame : ( w_eff = sqrt(Omega^2 + w_1^2) ) (rad.s^-1)', 
565              grace_string = 'Effective field in rotating frame (rad.s\\S-1\\N)', 
566              py_type = dict, 
567              set = 'all', 
568              err = False, 
569              sim = False 
570          ) 
571          self._add( 
572              'k_AB', 
573              scope = 'spin', 
574              default = 2.0, 
575              desc = 'The exchange rate from state A to state B', 
576              py_type = float, 
577              set = 'params', 
578              scaling = 20, 
579              grid_lower = 0.1, 
580              grid_upper = 20.0, 
581              grace_string = '\\qk\\sAB\\N\\Q (rad.s\\S-1\\N)', 
582              err = True, 
583              sim = True 
584          ) 
585          self._add( 
586              'k_BA', 
587              scope = 'spin', 
588              default = 1000.0, 
589              desc = 'The exchange rate from state B to state A', 
590              py_type = float, 
591              set = 'params', 
592              scaling = 10000, 
593              grid_lower = 1.0, 
594              grid_upper = 10000.0, 
595              grace_string = '\\qk\\sBA\\N\\Q (rad.s\\S-1\\N)', 
596              err = True, 
597              sim = True 
598          ) 
599   
600          # Add the minimisation data. 
601          self._add_min_data(min_stats_global=False, min_stats_spin=True) 
602   
603          # Set up the user function documentation. 
604          self._set_uf_title("Relaxation dispersion parameters") 
605          self._uf_param_table(label="table: dispersion parameters", caption="Relaxation dispersion parameters.", type=True) 
606          self._uf_param_table(label="table: dispersion parameters and min stats", caption="Relaxation dispersion parameters and minimisation statistics.", sets=['params', 'fixed', 'min']) 
607          self._uf_param_table(label="table: dispersion parameter value setting", caption="Relaxation dispersion parameters.", type=True) 
608          self._uf_param_table(label="table: dispersion parameter value setting with defaults", caption="Relaxation dispersion parameter value setting.", default=True, type=True) 
609   
610          # Value setting documentation. 
611          for doc in self._uf_doc_loop(["table: dispersion parameter value setting", "table: dispersion parameter value setting with defaults"]): 
612              doc.add_paragraph("Any of the relaxation dispersion parameters which are of the 'float' type can be set.  Note that setting values for parameters which are not part of the model will have no effect.") 
613