Source Code for Module target_functions.consistency_tests

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2004-2013 Edward d'Auvergne                                   # 
  4  # Copyright (C) 2007-2009 Sebastien Morin                                     # 
  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  # Python module imports. 
 24  from math import cos, pi 
 25  from numpy import float64, zeros 
 26   
 27  # relax module imports. 
 28  from lib.auto_relaxation.ri_comps import calc_fixed_csa, calc_fixed_dip, comp_csa_const_func, comp_dip_const_func 
 29   
 30   
 31 -class Consistency: 
 32 -    def __init__(self, frq=None, gx=None, gh=None, mu0=None, h_bar=None): 
 33          """Consistency tests for data acquired at different magnetic fields. 
 34   
 35          These three tests are used to assess the consistency of datasets aquired at different 
 36          magnetic fields. Inconsistency can affect extracted information from experimental data and 
 37          can be caused by variations in temperature, concentration, pH, water suppression, etc. The 
 38          approach is described in Morin & Gagne (2009) JBNMR, 45: 361-372. 
 39   
 40          This code calculates three functions for each residue. When comparing datasets from 
 41          different magnetic fields, the value should be the same for each function as these are field 
 42          independent. The J(0) function is the spectral density at the zero frequency and is obtained 
 43          using a reduced spectral density approach (Farrow et al. (1995) JBNMR, 6: 153-162). The 
 44          F_eta and F_R2 functions are the consistency functions proposed by Fushman et al. (1998) 
 45          JACS, 120: 10947-10952. 
 46   
 47          To assess the consistency of its datasets, one should first calculate one of those values 
 48          (J(0), F_eta and F_R2, preferentially J(0) as discussed in Morin & Gagne (2009) JBNMR, 45: 
 49          361-372) for each field. Then, the user should compare values obtained for different 
 50          magnetic fields. Comparisons should proceed using correlation plots and histograms, and the 
 51          user could also calculate correlation, skewness and kurtosis coefficients. 
 52   
 53          For examples, see Morin & Gagne (2009) JBNMR, 45: 361-372. 
 54          """ 
 55   
 56          # Initialise the data container. 
 57          self.data = Data() 
 58   
 59          # Add the initial data to self.data. 
 60          self.data.gx = gx 
 61          self.data.gh = gh 
 62          self.data.mu0 = mu0 
 63          self.data.h_bar = h_bar 
 64   
 65          # The number of frequencies. 
 66          self.data.num_frq = 1 
 67   
 68          # Dipolar and CSA data structures. 
 69          self.data.dip_const_fixed = 0.0 
 70          self.data.csa_const_fixed = [0.0] 
 71          self.data.dip_const_func = 0.0 
 72          self.data.csa_const_func = zeros(1, float64) 
 73   
 74          # Nuclear frequencies. 
 75          frq = frq * 2 * pi 
 76          frqX = frq * self.data.gx / self.data.gh 
 77   
 78          # Calculate the five frequencies which cause R1, R2, and NOE relaxation. 
 79          self.data.frq_list = zeros((1, 5), float64) 
 80          self.data.frq_list[0, 1] = frqX 
 81          self.data.frq_list[0, 2] = frq - frqX 
 82          self.data.frq_list[0, 3] = frq 
 83          self.data.frq_list[0, 4] = frq + frqX 
 84          self.data.frq_sqrd_list = self.data.frq_list ** 2 
 85   
 86   
 87 -    def calc_sigma_noe(self, noe, r1): 
 88          """Function for calculating the sigma NOE value.""" 
 89   
 90          return (noe - 1.0) * r1 * self.data.gx / self.data.gh 
 91   
 92   
 93 -    def func(self, orientation=None, tc=None, r=None, csa=None, r1=None, r2=None, noe=None): 
 94          """Function for calculating the three consistency testing values. 
 95   
 96          Three values are returned, J(0), F_eta and F_R2. 
 97          """ 
 98   
 99          # Calculate the fixed component of the dipolar and CSA constants. 
100          calc_fixed_dip(self.data) 
101          calc_fixed_csa(self.data) 
102   
103          # Calculate the dipolar and CSA constants. 
104          comp_dip_const_func(self.data, r) 
105          comp_csa_const_func(self.data, csa) 
106   
107          # Rename the dipolar and CSA constants. 
108          d = self.data.dip_const_func 
109          c = self.data.csa_const_func[0] 
110   
111          # Calculate the sigma NOE value. 
112          sigma_noe = self.calc_sigma_noe(noe, r1) 
113   
114          # Calculate J(0). 
115          j0 = -1.5 / (3.0*d + c) * (0.5*r1 - r2 + 0.6*sigma_noe) 
116   
117          # Calculate J(wX). 
118          jwx = 1.0 / (3.0*d + c) * (r1 - 1.4*sigma_noe) 
119   
120          # Calculate P_2. 
121          # p_2 is a second rank Legendre polynomial as p_2(x) = 0.5 * (3 * (x ** 2) -1) 
122          # where x is the cosine of the angle Theta when expressed in radians. 
123          # 
124          # Note that the angle Theta (called 'orientation' in relax) is the angle between the 15N-1H 
125          # vector and the principal axis of the 15N chemical shift tensor. 
126          p_2 = 0.5 * ((3.0 * (cos(orientation * pi / 180)) ** 2) -1) 
127   
128          # Calculate eta. 
129          # eta is the cross-correlation rate between 15N CSA and 15N-1H dipolar interaction. It is 
130          # expressed here as proposed in Fushman & Cowburn (1998) JACS, 120: 7109-7110. 
131          eta = ((d * c/3.0) ** 0.5) * (4.0 * j0 + 3.0 * jwx) * p_2 
132   
133          # Calculate F_eta. 
134          # F_eta is independent of the magnetic field for residues with local mobility 
135          f_eta = eta * self.data.gh / (self.data.frq_list[0, 3] * (4.0 + 3.0 / (1 + (self.data.frq_list[0, 1] * tc) ** 2))) 
136   
137          # Calculate P_HF. 
138          # P_HF is the contribution to R2 from high frequency motions. 
139          # P_HF = 0.5 * d * [J(wH-wN) + 6 * J(wH) + 6 * J(wH+wN)]. 
140          # Here, P_HF is described using a reduced spectral density approach. 
141          p_hf = 1.3 * (self.data.gx / self.data.gh) * (1.0 - noe) * r1 
142   
143          # Calculate F_R2. 
144          # F_R2 tests the consistency of the transverse relaxation data. 
145          f_r2 = (r2 - p_hf) / ((4.0 + 3.0 / (1 + (self.data.frq_list[0, 1] * tc) ** 2)) * (d + c/3.0)) 
146   
147          # Return the three values. 
148          return j0, f_eta, f_r2 
149   
150   
151 -class Data: 
152 -    def __init__(self): 
153          """Empty container for storing data.""" 
154