Source Code for Module specific_analyses.relax_disp.parameter_object

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