Source Code for Module maths_fns.consistency_tests

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