Package target_functions :: Module relax_disp :: Class Dispersion
[hide private]
[frames] | no frames]

Class Dispersion

source code

Instance Methods [hide private]
 
__init__(self, model=None, num_params=None, num_spins=None, num_frq=None, exp_types=None, values=None, errors=None, missing=None, frqs=None, frqs_H=None, cpmg_frqs=None, spin_lock_nu1=None, chemical_shifts=None, offset=None, tilt_angles=None, r1=None, relax_times=None, scaling_matrix=None, recalc_tau=True)
Relaxation dispersion target functions for optimisation.
source code
float
calc_CR72_chi2(self, R20A=None, R20B=None, dw=None, pA=None, kex=None)
Calculate the chi-squared value of the 'NS CPMG 2-site star' models.
source code
float
calc_ns_cpmg_2site_3D_chi2(self, R20A=None, R20B=None, dw=None, pA=None, kex=None)
Calculate the chi-squared value of the 'NS CPMG 2-site' models.
source code
float
calc_ns_cpmg_2site_star_chi2(self, R20A=None, R20B=None, dw=None, pA=None, kex=None)
Calculate the chi-squared value of the 'NS CPMG 2-site star' models.
source code
float
calc_ns_mmq_3site_chi2(self, R20A=None, R20B=None, R20C=None, dw_AB=None, dw_BC=None, dwH_AB=None, dwH_BC=None, pA=None, pB=None, kex_AB=None, kex_BC=None, kex_AC=None)
Calculate the chi-squared value for the 'NS MMQ 3-site' models.
source code
float
calc_ns_r1rho_3site_chi2(self, r1rho_prime=None, dw_AB=None, dw_BC=None, pA=None, pB=None, kex_AB=None, kex_BC=None, kex_AC=None)
Calculate the chi-squared value for the 'NS MMQ 3-site' models.
source code
 
experiment_type_setup(self)
Check the experiment types and simplify data structures.
source code
float
func_CR72(self, params)
Target function for the reduced Carver and Richards (1972) 2-site exchange model on all time scales.
source code
float
func_CR72_full(self, params)
Target function for the full Carver and Richards (1972) 2-site exchange model on all time scales.
source code
float
func_DPL94(self, params)
Target function for the Davis, Perlman and London (1994) fast 2-site off-resonance exchange model for R1rho-type experiments.
source code
float
func_IT99(self, params)
Target function for the Ishima and Torchia (1999) 2-site model for all timescales with pA >> pB.
source code
float
func_LM63_3site(self, params)
Target function for the Luz and Meiboom (1963) fast 3-site exchange model.
source code
float
func_LM63(self, params)
Target function for the Luz and Meiboom (1963) fast 2-site exchange model.
source code
float
func_M61(self, params)
Target function for the Meiboom (1961) fast 2-site exchange model for R1rho-type experiments.
source code
float
func_M61b(self, params)
Target function for the Meiboom (1961) R1rho on-resonance 2-site model for skewed populations (pA >> pB).
source code
float
func_MP05(self, params)
Target function for the Miloushev and Palmer (2005) R1rho off-resonance 2-site model.
source code
float
func_mmq_CR72(self, params)
Target function for the CR72 model extended for MQ CPMG data.
source code
float
func_NOREX(self, params)
Target function for no exchange.
source code
float
func_ns_cpmg_2site_3D(self, params)
Target function for the reduced numerical solution for the 2-site Bloch-McConnell equations.
source code
float
func_ns_cpmg_2site_3D_full(self, params)
Target function for the full numerical solution for the 2-site Bloch-McConnell equations.
source code
float
func_ns_cpmg_2site_expanded(self, params)
Target function for the numerical solution for the 2-site Bloch-McConnell equations using the expanded notation.
source code
float
func_ns_cpmg_2site_star(self, params)
Target function for the reduced numerical solution for the 2-site Bloch-McConnell equations using complex conjugate matrices.
source code
float
func_ns_cpmg_2site_star_full(self, params)
Target function for the full numerical solution for the 2-site Bloch-McConnell equations using complex conjugate matrices.
source code
float
func_ns_mmq_2site(self, params)
Target function for the combined SQ, ZQ, DQ and MQ CPMG numeric solution.
source code
float
func_ns_mmq_3site(self, params)
Target function for the combined SQ, ZQ, DQ and MQ 3-site MMQ CPMG numeric solution.
source code
float
func_ns_mmq_3site_linear(self, params)
Target function for the combined SQ, ZQ, DQ and MQ 3-site linearised MMQ CPMG numeric solution.
source code
float
func_ns_r1rho_2site(self, params)
Target function for the reduced numerical solution for the 2-site Bloch-McConnell equations for R1rho data.
source code
float
func_ns_r1rho_3site(self, params)
Target function for the R1rho 3-site numeric solution.
source code
float
func_ns_r1rho_3site_linear(self, params)
Target function for the R1rho 3-site numeric solution linearised with kAC = kCA = 0.
source code
float
func_TAP03(self, params)
Target function for the Trott, Abergel and Palmer (2003) R1rho off-resonance 2-site model.
source code
float
func_TP02(self, params)
Target function for the Trott and Palmer (2002) R1rho off-resonance 2-site model.
source code
float
func_TSMFK01(self, params)
Target function for the the Tollinger et al.
source code
Method Details [hide private]

__init__(self, model=None, num_params=None, num_spins=None, num_frq=None, exp_types=None, values=None, errors=None, missing=None, frqs=None, frqs_H=None, cpmg_frqs=None, spin_lock_nu1=None, chemical_shifts=None, offset=None, tilt_angles=None, r1=None, relax_times=None, scaling_matrix=None, recalc_tau=True)
(Constructor)

source code 

Relaxation dispersion target functions for optimisation.

Models

The following analytic models are currently supported:

  • 'No Rex': The model for no chemical exchange relaxation.
  • 'LM63': The Luz and Meiboom (1963) 2-site fast exchange model.
  • 'LM63 3-site': The Luz and Meiboom (1963) 3-site fast exchange model.
  • 'CR72': The reduced Carver and Richards (1972) 2-site model for all time scales with R20A = R20B.
  • 'CR72 full': The full Carver and Richards (1972) 2-site model for all time scales.
  • 'IT99': The Ishima and Torchia (1999) 2-site model for all time scales with skewed populations (pA >> pB).
  • 'TSMFK01': The Tollinger et al. (2001) 2-site very-slow exchange model, range of microsecond to second time scale.
  • 'M61': The Meiboom (1961) 2-site fast exchange model for R1rho-type experiments.
  • 'DPL94': The Davis, Perlman and London (1994) 2-site fast exchange model for R1rho-type experiments.
  • 'M61 skew': The Meiboom (1961) on-resonance 2-site model with skewed populations (pA >> pB) for R1rho-type experiments.
  • 'TP02': The Trott and Palmer (2002) 2-site exchange model for R1rho-type experiments.
  • 'TAP03': The Trott, Abergel and Palmer (2003) 2-site exchange model for R1rho-type experiments.
  • 'MP05': The Miloushev and Palmer (2005) off-resonance 2-site exchange model for R1rho-type experiments.

The following numerical models are currently supported:

  • 'NS CPMG 2-site 3D': The reduced numerical solution for the 2-site Bloch-McConnell equations for CPMG data using 3D magnetisation vectors with R20A = R20B.
  • 'NS CPMG 2-site 3D full': The full numerical solution for the 2-site Bloch-McConnell equations for CPMG data using 3D magnetisation vectors.
  • 'NS CPMG 2-site star': The reduced numerical solution for the 2-site Bloch-McConnell equations for CPMG data using complex conjugate matrices with R20A = R20B.
  • 'NS CPMG 2-site star full': The full numerical solution for the 2-site Bloch-McConnell equations for CPMG data using complex conjugate matrices.
  • 'NS CPMG 2-site expanded': The numerical solution for the 2-site Bloch-McConnell equations for CPMG data expanded using Maple by Nikolai Skrynnikov.
  • 'NS MMQ 2-site': The numerical solution for the 2-site Bloch-McConnell equations for combined proton-heteronuclear SQ, ZD, DQ, and MQ CPMG data with R20A = R20B.
  • 'NS MMQ 3-site linear': The numerical solution for the 3-site Bloch-McConnell equations linearised with kAC = kCA = 0 for combined proton-heteronuclear SQ, ZD, DQ, and MQ CPMG data with R20A = R20B = R20C.
  • 'NS MMQ 3-site': The numerical solution for the 3-site Bloch-McConnell equations for combined proton-heteronuclear SQ, ZD, DQ, and MQ CPMG data with R20A = R20B = R20C.
  • 'NS R1rho 2-site': The numerical solution for the 2-site Bloch-McConnell equations for R1rho data with R20A = R20B.
  • 'NS R1rho 3-site linear': The numerical solution for the 3-site Bloch-McConnell equations linearised with kAC = kCA = 0 for R1rho data with R20A = R20B = R20C.
  • 'NS R1rho 3-site': The numerical solution for the 3-site Bloch-McConnell equations for R1rho data with R20A = R20B = R20C.

Indices

The data structures used in this target function class consist of many different index types. These are:

  • Ei: The index for each experiment type.
  • Si: The index for each spin of the spin cluster.
  • Mi: The index for each magnetic field strength.
  • Oi: The index for each spin-lock offset. In the case of CPMG-type data, this index is always zero.
  • Di: The index for each dispersion point (either the spin-lock field strength or the nu_CPMG frequency).
Parameters:
  • model (str) - The relaxation dispersion model to fit.
  • num_param (int) - The number of parameters in the model.
  • num_spins (int) - The number of spins in the cluster.
  • num_frq (int) - The number of spectrometer field strengths.
  • exp_types (list of str) - The list of experiment types. The dimensions are {Ei}.
  • values (rank-4 list of numpy rank-1 float arrays) - The R2eff/R1rho values. The dimensions are {Ei, Si, Mi, Oi, Di}.
  • errors (rank-4 list of numpy rank-1 float arrays) - The R2eff/R1rho errors. The dimensions are {Ei, Si, Mi, Oi, Di}.
  • missing (rank-4 list of numpy rank-1 int arrays) - The data structure indicating missing R2eff/R1rho data. The dimensions are {Ei, Si, Mi, Oi, Di}.
  • frqs (rank-3 list of floats) - The spin Larmor frequencies (in MHz*2pi to speed up the ppm to rad/s conversion). The dimensions are {Ei, Si, Mi}.
  • frqs_H (rank-3 list of floats) - The proton spin Larmor frequencies for the MMQ-type models (in MHz*2pi to speed up the ppm to rad/s conversion). The dimensions are {Ei, Si, Mi}.
  • cpmg_frqs (rank-2 list of floats) - The CPMG frequencies in Hertz. This will be ignored for R1rho experiments. The dimensions are {Ei, Mi}.
  • spin_lock_nu1 (rank-2 list of floats) - The spin-lock field strengths in Hertz. This will be ignored for CPMG experiments. The dimensions are {Ei, Mi}.
  • chemical_shifts (rank-3 list of floats) - The chemical shifts in rad/s. This is only used for off-resonance R1rho models. The ppm values are not used to save computation time, therefore they must be converted to rad/s by the calling code. The dimensions are {Ei, Si, Mi}.
  • offset (rank-4 list of floats) - The structure of spin-lock or hard pulse offsets in rad/s. This is only currently used for off-resonance R1rho models. The dimensions are {Ei, Si, Mi, Oi}.
  • tilt_angles (rank-5 list of floats) - The spin-lock rotating frame tilt angle. This is only used for off-resonance R1rho models. The dimensions are {Ei, Si, Mi, Oi, Di}.
  • r1 (rank-3 list of floats) - The R1 relaxation rates. This is only used for off-resonance R1rho models. The dimensions are {Ei, Si, Mi}.
  • relax_times (rank-2 list of floats) - The experiment specific fixed time period for relaxation (in seconds). The dimensions are {Ei, Mi}.
  • scaling_matrix (numpy rank-2 float array) - The square and diagonal scaling matrix.
  • recalc_tau (bool) - A flag which if True will cause tau_CPMG to be recalculated to remove user input truncation.

calc_CR72_chi2(self, R20A=None, R20B=None, dw=None, pA=None, kex=None)

source code 

Calculate the chi-squared value of the 'NS CPMG 2-site star' models.

Parameters:
  • R20A (list of float) - The R2 value for state A in the absence of exchange.
  • R20B (list of float) - The R2 value for state B in the absence of exchange.
  • dw (list of float) - The chemical shift differences in ppm for each spin.
  • pA (float) - The population of state A.
  • kex (float) - The rate of exchange.
Returns: float
The chi-squared value.

calc_ns_cpmg_2site_3D_chi2(self, R20A=None, R20B=None, dw=None, pA=None, kex=None)

source code 

Calculate the chi-squared value of the 'NS CPMG 2-site' models.

Parameters:
  • R20A (list of float) - The R2 value for state A in the absence of exchange.
  • R20B (list of float) - The R2 value for state B in the absence of exchange.
  • dw (list of float) - The chemical shift differences in ppm for each spin.
  • pA (float) - The population of state A.
  • kex (float) - The rate of exchange.
Returns: float
The chi-squared value.

calc_ns_cpmg_2site_star_chi2(self, R20A=None, R20B=None, dw=None, pA=None, kex=None)

source code 

Calculate the chi-squared value of the 'NS CPMG 2-site star' models.

Parameters:
  • R20A (list of float) - The R2 value for state A in the absence of exchange.
  • R20B (list of float) - The R2 value for state B in the absence of exchange.
  • dw (list of float) - The chemical shift differences in ppm for each spin.
  • pA (float) - The population of state A.
  • kex (float) - The rate of exchange.
Returns: float
The chi-squared value.

calc_ns_mmq_3site_chi2(self, R20A=None, R20B=None, R20C=None, dw_AB=None, dw_BC=None, dwH_AB=None, dwH_BC=None, pA=None, pB=None, kex_AB=None, kex_BC=None, kex_AC=None)

source code 

Calculate the chi-squared value for the 'NS MMQ 3-site' models.

Parameters:
  • R20A (list of float) - The R2 value for state A in the absence of exchange.
  • R20B (list of float) - The R2 value for state B in the absence of exchange.
  • R20C (list of float) - The R2 value for state C in the absence of exchange.
  • dw_AB (float) - The chemical exchange difference between states A and B in rad/s.
  • dw_BC (float) - The chemical exchange difference between states B and C in rad/s.
  • dwH_AB (float) - The proton chemical exchange difference between states A and B in rad/s.
  • dwH_BC (float) - The proton chemical exchange difference between states B and C in rad/s.
  • pA (float) - The population of state A.
  • kex_AB (float) - The rate of exchange between states A and B.
  • kex_BC (float) - The rate of exchange between states B and C.
  • kex_AC (float) - The rate of exchange between states A and C.
Returns: float
The chi-squared value.

calc_ns_r1rho_3site_chi2(self, r1rho_prime=None, dw_AB=None, dw_BC=None, pA=None, pB=None, kex_AB=None, kex_BC=None, kex_AC=None)

source code 

Calculate the chi-squared value for the 'NS MMQ 3-site' models.

Parameters:
  • r1rho_prime (list of float) - The R1rho value for all states in the absence of exchange.
  • dw_AB (float) - The chemical exchange difference between states A and B in rad/s.
  • dw_BC (float) - The chemical exchange difference between states B and C in rad/s.
  • pA (float) - The population of state A.
  • kex_AB (float) - The rate of exchange between states A and B.
  • kex_BC (float) - The rate of exchange between states B and C.
  • kex_AC (float) - The rate of exchange between states A and C.
Returns: float
The chi-squared value.

experiment_type_setup(self)

source code 

Check the experiment types and simplify data structures.

For the single experiment type models, the first dimension of the values, errors, and missing data structures will be removed to simplify the target functions.

func_CR72(self, params)

source code 

Target function for the reduced Carver and Richards (1972) 2-site exchange model on all time scales.

This assumes that pA > pB, and hence this must be implemented as a constraint. For this model, the simplification R20A = R20B is assumed.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_CR72_full(self, params)

source code 

Target function for the full Carver and Richards (1972) 2-site exchange model on all time scales.

This assumes that pA > pB, and hence this must be implemented as a constraint.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_DPL94(self, params)

source code 

Target function for the Davis, Perlman and London (1994) fast 2-site off-resonance exchange model for R1rho-type experiments.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_IT99(self, params)

source code 

Target function for the Ishima and Torchia (1999) 2-site model for all timescales with pA >> pB.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_LM63_3site(self, params)

source code 

Target function for the Luz and Meiboom (1963) fast 3-site exchange model.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_LM63(self, params)

source code 

Target function for the Luz and Meiboom (1963) fast 2-site exchange model.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_M61(self, params)

source code 

Target function for the Meiboom (1961) fast 2-site exchange model for R1rho-type experiments.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_M61b(self, params)

source code 

Target function for the Meiboom (1961) R1rho on-resonance 2-site model for skewed populations (pA >> pB).

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_MP05(self, params)

source code 

Target function for the Miloushev and Palmer (2005) R1rho off-resonance 2-site model.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_mmq_CR72(self, params)

source code 

Target function for the CR72 model extended for MQ CPMG data.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_NOREX(self, params)

source code 

Target function for no exchange.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_cpmg_2site_3D(self, params)

source code 

Target function for the reduced numerical solution for the 2-site Bloch-McConnell equations.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_cpmg_2site_3D_full(self, params)

source code 

Target function for the full numerical solution for the 2-site Bloch-McConnell equations.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_cpmg_2site_expanded(self, params)

source code 

Target function for the numerical solution for the 2-site Bloch-McConnell equations using the expanded notation.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_cpmg_2site_star(self, params)

source code 

Target function for the reduced numerical solution for the 2-site Bloch-McConnell equations using complex conjugate matrices.

This is the model whereby the simplification R20A = R20B is assumed.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_cpmg_2site_star_full(self, params)

source code 

Target function for the full numerical solution for the 2-site Bloch-McConnell equations using complex conjugate matrices.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_mmq_2site(self, params)

source code 

Target function for the combined SQ, ZQ, DQ and MQ CPMG numeric solution.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_mmq_3site(self, params)

source code 

Target function for the combined SQ, ZQ, DQ and MQ 3-site MMQ CPMG numeric solution.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_mmq_3site_linear(self, params)

source code 

Target function for the combined SQ, ZQ, DQ and MQ 3-site linearised MMQ CPMG numeric solution.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_r1rho_2site(self, params)

source code 

Target function for the reduced numerical solution for the 2-site Bloch-McConnell equations for R1rho data.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_r1rho_3site(self, params)

source code 

Target function for the R1rho 3-site numeric solution.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_ns_r1rho_3site_linear(self, params)

source code 

Target function for the R1rho 3-site numeric solution linearised with kAC = kCA = 0.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_TAP03(self, params)

source code 

Target function for the Trott, Abergel and Palmer (2003) R1rho off-resonance 2-site model.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_TP02(self, params)

source code 

Target function for the Trott and Palmer (2002) R1rho off-resonance 2-site model.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.

func_TSMFK01(self, params)

source code 

Target function for the the Tollinger et al. (2001) 2-site very-slow exchange model, range of microsecond to second time scale.

Parameters:
  • params (numpy rank-1 float array) - The vector of parameter values.
Returns: float
The chi-squared value.