def back_calc_peak_intensities(spin=None, exp_type=None, frq=None, offset=None, point=None):
"""Back-calculation of peak intensity for the given relaxation time.
@keyword spin: The specific spin data container.
@type spin: SpinContainer instance
@keyword exp_type: The experiment type.
@type exp_type: str
@keyword frq: The spectrometer frequency.
@type frq: float
@keyword offset: For R1rho-type data, the spin-lock offset value in ppm.
@type offset: None or float
@keyword point: The dispersion point data (either the spin-lock field strength in Hz or the nu_CPMG frequency in Hz).
@type point: float
@return: The back-calculated peak intensities for the given exponential curve.
@rtype: numpy rank-1 float array
"""
# Check.
if not has_exponential_exp_type():
raise RelaxError("Back-calculation is not allowed for the fixed time experiment types.")
# The key.
param_key = return_param_key_from_data(exp_type=exp_type, frq=frq, offset=offset, point=point)
# Create the initial parameter vector.
param_vector = assemble_param_vector(spins=[spin], key=param_key)
# The peak intensities and times.
values = []
errors = []
times = []
for time in loop_time(exp_type=exp_type, frq=frq, offset=offset, point=point):
# The data.
values.append(average_intensity(spin=spin, exp_type=exp_type, frq=frq, offset=offset, point=point, time=time))
errors.append(average_intensity(spin=spin, exp_type=exp_type, frq=frq, offset=offset, point=point, time=time, error=True))
times.append(time)
# The scaling matrix in a diagonalised list form.
scaling_list = []
for i in range(len(param_vector)):
scaling_list.append(1.0)
# Initialise the relaxation fit functions.
model = Relax_fit_opt(model='exp', num_params=len(spin.params), values=values, errors=errors, relax_times=times, scaling_matrix=scaling_list)
# Make a single function call. This will cause back calculation and the data will be stored in the C module.
model.func(param_vector)
# Get the data back.
results = model.back_calc_data()
# Return the correct peak height.
return results
def back_calc(spin=None, relax_time_id=None):
"""Back-calculation of peak intensity for the given relaxation time.
@keyword spin: The spin container.
@type spin: SpinContainer instance
@keyword relax_time_id: The ID string for the desired relaxation time.
@type relax_time_id: str
@return: The peak intensity for the desired relaxation time.
@rtype: float
"""
# Create the initial parameter vector.
param_vector = assemble_param_vector(spin=spin)
# The keys.
keys = list(spin.peak_intensity.keys())
# The peak intensities and times.
values = []
errors = []
times = []
for key in keys:
values.append(spin.peak_intensity[key])
errors.append(spin.peak_intensity_err[key])
times.append(cdp.relax_times[key])
# A fake scaling matrix in a diagonalised list form.
scaling_list = []
for i in range(len(param_vector)):
scaling_list.append(1.0)
# Initialise the relaxation fit functions.
model = Relax_fit_opt(model=spin.model,
num_params=len(spin.params),
values=values,
errors=errors,
relax_times=times,
scaling_matrix=scaling_list)
# Make a single function call. This will cause back calculation and the data will be stored in the C module.
model.func(param_vector)
# Get the data back.
results = model.back_calc_data()
# Return the correct peak height.
return results[keys.index(relax_time_id)]
def back_calc(spin=None, relax_time_id=None):
"""Back-calculation of peak intensity for the given relaxation time.
@keyword spin: The spin container.
@type spin: SpinContainer instance
@keyword relax_time_id: The ID string for the desired relaxation time.
@type relax_time_id: str
@return: The peak intensity for the desired relaxation time.
@rtype: float
"""
# Create the initial parameter vector.
param_vector = assemble_param_vector(spin=spin)
# The keys.
keys = list(spin.peak_intensity.keys())
# The peak intensities and times.
values = []
errors = []
times = []
for key in keys:
values.append(spin.peak_intensity[key])
errors.append(spin.peak_intensity_err[key])
times.append(cdp.relax_times[key])
# A fake scaling matrix in a diagonalised list form.
scaling_list = []
for i in range(len(param_vector)):
scaling_list.append(1.0)
# Initialise the relaxation fit functions.
model = Relax_fit_opt(model=spin.model, num_params=len(spin.params), values=values, errors=errors, relax_times=times, scaling_matrix=scaling_list)
# Make a single function call. This will cause back calculation and the data will be stored in the C module.
model.func(param_vector)
# Get the data back.
results = model.back_calc_data()
# Return the correct peak height.
return results[keys.index(relax_time_id)]
def covariance_matrix(self, model_info=None, verbosity=1):
"""Return the Jacobian and weights required for parameter errors via the covariance matrix.
@keyword model_info: The spin container and the spin ID string from the _model_loop_spin() method.
@type model_info: SpinContainer instance, str
@keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
@type verbosity: int
@return: The Jacobian and weight matrices for the given model.
@rtype: numpy rank-2 array, numpy rank-2 array
"""
# Unpack the data.
spin, spin_id = model_info
# Check that the C modules have been compiled.
if not C_module_exp_fn:
raise RelaxError("Relaxation curve fitting is not available. Try compiling the C modules on your platform.")
# Raise Error, if not optimised.
if not (hasattr(spin, 'rx') and hasattr(spin, 'i0')):
raise RelaxError("Spin '%s' does not contain optimised 'rx' and 'i0' values. Try execute: minimise.execute(min_algor='Newton', constraints=False)"%(spin_id))
# Raise warning, if gradient count is 0. This could point to a lack of minimisation first.
if hasattr(spin, 'g_count'):
if getattr(spin, 'g_count') == 0.0:
text = "Spin %s contains a gradient count of 0.0. Is the rx parameter optimised? Try execute: minimise.execute(min_algor='Newton', constraints=False)" %(spin_id)
warn(RelaxWarning("%s." % text))
# Print information.
if verbosity >= 1:
# Individual spin block section.
top = 2
if verbosity >= 2:
top += 2
subsection(file=sys.stdout, text="Estimating rx error for spin: %s"%spin_id, prespace=top)
# The peak intensities and times.
values = []
errors = []
times = []
for key in spin.peak_intensity:
values.append(spin.peak_intensity[key])
errors.append(spin.peak_intensity_err[key])
times.append(cdp.relax_times[key])
# Convert to numpy array.
values = asarray(values)
errors = asarray(errors)
times = asarray(times)
# Create the parameter vector and scaling matrix (as a diagonalised list).
param_vector = assemble_param_vector(spin=spin)
scaling_list = []
for i in range(len(spin.params)):
scaling_list.append(1.0)
# Initialise data in C code.
model = Relax_fit_opt(model=spin.model, num_params=len(param_vector), values=values, errors=errors, relax_times=times, scaling_matrix=scaling_list)
# Use the direct Jacobian from function.
jacobian_matrix_exp = transpose(asarray( model.jacobian(param_vector) ) )
weights = 1. / errors**2
# Return the matrices.
return jacobian_matrix_exp, weights
def back_calc_peak_intensities(spin=None, spin_id=None, exp_type=None, frq=None, offset=None, point=None):
"""Back-calculation of peak intensity for the given relaxation time.
@keyword spin: The specific spin data container.
@type spin: SpinContainer instance
@keyword spin_id: The optional spin ID string for use in warning messages.
@type spin_id: str or None
@keyword exp_type: The experiment type.
@type exp_type: str
@keyword frq: The spectrometer frequency.
@type frq: float
@keyword offset: For R1rho-type data, the spin-lock offset value in ppm.
@type offset: None or float
@keyword point: The dispersion point data (either the spin-lock field strength in Hz or the nu_CPMG frequency in Hz).
@type point: float
@return: The back-calculated peak intensities for the given exponential curve.
@rtype: numpy rank-1 float array
"""
# Check.
if not has_exponential_exp_type():
raise RelaxError("Back-calculation is not allowed for the fixed time experiment types.")
# The key.
param_key = return_param_key_from_data(exp_type=exp_type, frq=frq, offset=offset, point=point)
# Create the initial parameter vector.
param_vector = assemble_param_vector(spins=[spin], key=param_key)
# The peak intensities and times.
values = []
errors = []
times = []
for time in loop_time(exp_type=exp_type, frq=frq, offset=offset, point=point):
# Check the peak intensity keys.
int_keys = find_intensity_keys(exp_type=exp_type, frq=frq, offset=offset, point=point, time=time)
for i in range(len(int_keys)):
if int_keys[i] not in spin.peak_intensity:
if spin_id:
warn(RelaxWarning("The spin %s peak intensity key '%s' is not present, skipping the back-calculation." % (spin_id, int_keys[i])))
else:
warn(RelaxWarning("The peak intensity key '%s' is not present, skipping the back-calculation." % int_keys[i]))
return
# The data.
values.append(average_intensity(spin=spin, exp_type=exp_type, frq=frq, offset=offset, point=point, time=time))
errors.append(average_intensity(spin=spin, exp_type=exp_type, frq=frq, offset=offset, point=point, time=time, error=True))
times.append(time)
# The scaling matrix in a diagonalised list form.
scaling_list = []
for i in range(len(param_vector)):
scaling_list.append(1.0)
# Initialise the relaxation fit functions.
model = Relax_fit_opt(model='exp', num_params=len(spin.params), values=values, errors=errors, relax_times=times, scaling_matrix=scaling_list)
# Make a single function call. This will cause back calculation and the data will be stored in the C module.
model.func(param_vector)
# Get the data back.
results = model.back_calc_data()
# Return the correct peak height.
return results
def minimise_r2eff(spins=None, spin_ids=None, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=False, scaling_matrix=None, verbosity=0, sim_index=None, lower=None, upper=None, inc=None):
"""Optimise the R2eff model by fitting the 2-parameter exponential curves.
This mimics the R1 and R2 relax_fit analysis.
@keyword spins: The list of spins for the cluster.
@type spins: list of SpinContainer instances
@keyword spin_ids: The list of spin IDs for the cluster.
@type spin_ids: list of str
@keyword min_algor: The minimisation algorithm to use.
@type min_algor: str
@keyword min_options: An array of options to be used by the minimisation algorithm.
@type min_options: array of str
@keyword func_tol: The function tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
@type func_tol: None or float
@keyword grad_tol: The gradient tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
@type grad_tol: None or float
@keyword max_iterations: The maximum number of iterations for the algorithm.
@type max_iterations: int
@keyword constraints: If True, constraints are used during optimisation.
@type constraints: bool
@keyword scaling_matrix: The diagonal and square scaling matrix.
@type scaling_matrix: numpy rank-2, float64 array or None
@keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
@type verbosity: int
@keyword sim_index: The index of the simulation to optimise. This should be None if normal optimisation is desired.
@type sim_index: None or int
@keyword lower: The model specific lower bounds of the grid search which must be equal to the number of parameters in the model. This optional argument is only used when doing a grid search.
@type lower: list of numbers
@keyword upper: The model specific upper bounds of the grid search which must be equal to the number of parameters in the model. This optional argument is only used when doing a grid search.
@type upper: list of numbers
@keyword inc: The model specific increments for each dimension of the space for the grid search. The number of elements in the array must equal to the number of parameters in the model. This argument is only used when doing a grid search.
@type inc: list of int
"""
# Check that the C modules have been compiled.
if not C_module_exp_fn:
raise RelaxError("Relaxation curve fitting is not available. Try compiling the C modules on your platform.")
# Loop over the spins.
for si in range(len(spins)):
# Skip deselected spins.
if not spins[si].select:
continue
# Loop over each spectrometer frequency and dispersion point.
for exp_type, frq, offset, point in loop_exp_frq_offset_point():
# The parameter key.
param_key = return_param_key_from_data(exp_type=exp_type, frq=frq, offset=offset, point=point)
# The initial parameter vector.
param_vector = assemble_param_vector(spins=[spins[si]], key=param_key, sim_index=sim_index)
# Diagonal scaling.
if scaling_matrix is not None:
param_vector = dot(inv(scaling_matrix), param_vector)
# Linear constraints.
A, b = None, None
if constraints:
A, b = linear_constraints(spins=[spins[si]], scaling_matrix=scaling_matrix)
# Print out.
if verbosity >= 1:
# Individual spin section.
top = 2
if verbosity >= 2:
top += 2
text = "Fitting to spin %s, frequency %s and dispersion point %s" % (spin_ids[si], frq, point)
subsection(file=sys.stdout, text=text, prespace=top)
# Grid search printout.
if match('^[Gg]rid', min_algor):
result = 1
for x in inc:
result = mul(result, x)
print("Unconstrained grid search size: %s (constraints may decrease this size).\n" % result)
# The peak intensities, errors and times.
values = []
errors = []
times = []
data_flag = True
for time in loop_time(exp_type=exp_type, frq=frq, offset=offset, point=point):
# Check the peak intensity keys.
int_keys = find_intensity_keys(exp_type=exp_type, frq=frq, offset=offset, point=point, time=time)
peak_intensities = spins[si].peak_intensity
if sim_index != None:
peak_intensities = spins[si].peak_intensity_sim
for i in range(len(int_keys)):
if int_keys[i] not in peak_intensities:
if verbosity:
warn(RelaxWarning("The spin %s peak intensity key '%s' is not present, skipping the optimisation." % (spin_ids[si], int_keys[i])))
data_flag = False
break
if data_flag:
values.append(average_intensity(spin=spins[si], exp_type=exp_type, frq=frq, offset=offset, point=point, time=time, sim_index=sim_index))
errors.append(average_intensity(spin=spins[si], exp_type=exp_type, frq=frq, offset=offset, point=point, time=time, error=True))
times.append(time)
if not data_flag:
continue
# Raise errors if number of time points is less than 2.
if len(times) < 3:
subsection(file=sys.stdout, text="Exponential curve fitting error for point:", prespace=2)
point_info = "%s at %3.1f MHz, for offset=%3.3f ppm and dispersion point %-5.1f, with %i time points." % (exp_type, frq/1E6, offset, point, len(times))
raise RelaxError("The data setup points to exponential curve fitting, but only %i time points was found, where 3 time points is minimum. If calculating R2eff values for fixed relaxation time period data, check that a reference intensity has been specified for each offset value."%(len(times)))
# The scaling matrix in a diagonalised list form.
scaling_list = []
if scaling_matrix is None:
for i in range(len(param_vector)):
scaling_list.append(1.0)
else:
for i in range(len(scaling_matrix)):
scaling_list.append(scaling_matrix[i, i])
# Initialise the function to minimise.
model = Relax_fit_opt(model='exp', num_params=len(param_vector), values=values, errors=errors, relax_times=times, scaling_matrix=scaling_list)
# Grid search.
if search('^[Gg]rid', min_algor):
results = grid(func=model.func, args=(), num_incs=inc, lower=lower, upper=upper, A=A, b=b, verbosity=verbosity)
# Unpack the results.
param_vector, chi2, iter_count, warning = results
f_count = iter_count
g_count = 0.0
h_count = 0.0
# Minimisation.
else:
results = generic_minimise(func=model.func, dfunc=model.dfunc, d2func=model.d2func, args=(), x0=param_vector, min_algor=min_algor, min_options=min_options, func_tol=func_tol, grad_tol=grad_tol, maxiter=max_iterations, A=A, b=b, full_output=True, print_flag=verbosity)
# Unpack the results.
if results == None:
return
param_vector, chi2, iter_count, f_count, g_count, h_count, warning = results
# Scaling.
if scaling_matrix is not None:
param_vector = dot(scaling_matrix, param_vector)
# Disassemble the parameter vector.
disassemble_param_vector(param_vector=param_vector, spins=[spins[si]], key=param_key, sim_index=sim_index)
# Monte Carlo minimisation statistics.
if sim_index != None:
# Chi-squared statistic.
spins[si].chi2_sim[sim_index] = chi2
# Iterations.
spins[si].iter_sim[sim_index] = iter_count
# Function evaluations.
spins[si].f_count_sim[sim_index] = f_count
# Gradient evaluations.
spins[si].g_count_sim[sim_index] = g_count
# Hessian evaluations.
spins[si].h_count_sim[sim_index] = h_count
# Warning.
spins[si].warning_sim[sim_index] = warning
# Normal statistics.
else:
# Chi-squared statistic.
spins[si].chi2 = chi2
# Iterations.
spins[si].iter = iter_count
# Function evaluations.
spins[si].f_count = f_count
# Gradient evaluations.
spins[si].g_count = g_count
# Hessian evaluations.
spins[si].h_count = h_count
# Warning.
spins[si].warning = warning
def minimise_minfx(E=None):
"""Estimate r2eff and errors by minimising with minfx.
@keyword E: The Exponential function class, which contain data and functions.
@type E: class
@return: Packed list with optimised parameter, parameter error set to 'inf', chi2, iter_count, f_count, g_count, h_count, warning
@rtype: list
"""
# Check that the C modules have been compiled.
if not C_module_exp_fn:
raise RelaxError(
"Relaxation curve fitting is not available. Try compiling the C modules on your platform."
)
# Initial guess for minimisation. Solved by linear least squares.
x0 = asarray(E.estimate_x0_exp(times=E.times, values=E.values))
if E.c_code:
# Minimise with C code.
# Initialise the function to minimise.
scaling_list = [1.0, 1.0]
model = Relax_fit_opt(model='exp',
num_params=len(x0),
values=E.values,
errors=E.errors,
relax_times=E.times,
scaling_matrix=scaling_list)
# Define function to minimise for minfx.
t_func = model.func
t_dfunc = model.dfunc
t_d2func = model.d2func
args = ()
else:
# Minimise with minfx.
# Define function to minimise for minfx.
t_func = E.func_exp_chi2
t_dfunc = E.func_exp_chi2_grad
t_d2func = None
# All args to function. Params are packed out through function, then other parameters.
args = (E.times, E.values, E.errors)
# Minimise.
results_minfx = generic_minimise(func=t_func,
dfunc=t_dfunc,
d2func=t_d2func,
args=args,
x0=x0,
min_algor=E.min_algor,
min_options=E.min_options,
func_tol=E.func_tol,
grad_tol=E.grad_tol,
maxiter=E.max_iterations,
A=E.A,
b=E.b,
full_output=True,
print_flag=0)
# Unpack
param_vector, chi2, iter_count, f_count, g_count, h_count, warning = results_minfx
# Extract.
r2eff, i0 = param_vector
# Get the Jacobian.
if E.c_code == True:
if E.chi2_jacobian:
# Use the chi2 Jacobian from C.
jacobian_matrix_exp = transpose(
asarray(model.jacobian_chi2(param_vector)))
weights = ones(E.errors.shape)
else:
# Use the direct Jacobian from C.
jacobian_matrix_exp = transpose(
asarray(model.jacobian(param_vector)))
weights = 1. / E.errors**2
elif E.c_code == False:
if E.chi2_jacobian:
# Use the chi2 Jacobian from python.
jacobian_matrix_exp = E.func_exp_chi2_grad_array(
params=param_vector,
times=E.times,
values=E.values,
errors=E.errors)
weights = ones(E.errors.shape)
else:
# Use the direct Jacobian from python.
jacobian_matrix_exp = E.func_exp_grad(params=param_vector,
times=E.times)
weights = 1. / E.errors**2
pcov = multifit_covar(J=jacobian_matrix_exp, weights=weights)
# To compute one standard deviation errors on the parameters, take the square root of the diagonal covariance.
param_vector_error = sqrt(diag(pcov))
# Pack to list.
results = [
param_vector, param_vector_error, chi2, iter_count, f_count, g_count,
h_count, warning
]
# Return, including errors.
return results
def estimate_r2eff_err(spin_id=None, epsrel=0.0, verbosity=1):
"""This will estimate the R2eff and i0 errors from the covariance matrix Qxx. Qxx is calculated from the Jacobian matrix and the optimised parameters.
@keyword spin_id: The spin identification string.
@type spin_id: str
@param epsrel: Any columns of R which satisfy |R_{kk}| <= epsrel |R_{11}| are considered linearly-dependent and are excluded from the covariance matrix, where the corresponding rows and columns of the covariance matrix are set to zero.
@type epsrel: float
@keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
@type verbosity: int
"""
# Check that the C modules have been compiled.
if not C_module_exp_fn:
raise RelaxError(
"Relaxation curve fitting is not available. Try compiling the C modules on your platform."
)
# Perform checks.
check_model_type(model=MODEL_R2EFF)
# Loop over the spins.
for cur_spin, mol_name, resi, resn, cur_spin_id in spin_loop(
selection=spin_id, full_info=True, return_id=True,
skip_desel=True):
# Generate spin string.
spin_string = generate_spin_string(spin=cur_spin,
mol_name=mol_name,
res_num=resi,
res_name=resn)
# Raise Error, if not optimised.
if not (hasattr(cur_spin, 'r2eff') and hasattr(cur_spin, 'i0')):
raise RelaxError(
"Spin %s does not contain optimised 'r2eff' and 'i0' values. Try execute: minimise.execute(min_algor='Newton', constraints=False)"
% (spin_string))
# Raise warning, if gradient count is 0. This could point to a lack of minimisation first.
if hasattr(cur_spin, 'g_count'):
if getattr(cur_spin, 'g_count') == 0.0:
text = "Spin %s contains a gradient count of 0.0. Is the R2eff parameter optimised? Try execute: minimise.execute(min_algor='Newton', constraints=False)" % (
spin_string)
warn(RelaxWarning("%s." % text))
# Print information.
if verbosity >= 1:
# Individual spin block section.
top = 2
if verbosity >= 2:
top += 2
subsection(file=sys.stdout,
text="Estimating R2eff error for spin: %s" %
spin_string,
prespace=top)
# Loop over each spectrometer frequency and dispersion point.
for exp_type, frq, offset, point, ei, mi, oi, di in loop_exp_frq_offset_point(
return_indices=True):
# The parameter key.
param_key = return_param_key_from_data(exp_type=exp_type,
frq=frq,
offset=offset,
point=point)
# Extract values.
r2eff = getattr(cur_spin, 'r2eff')[param_key]
i0 = getattr(cur_spin, 'i0')[param_key]
# Pack data
param_vector = [r2eff, i0]
# The peak intensities, errors and times.
values = []
errors = []
times = []
for time in loop_time(exp_type=exp_type,
frq=frq,
offset=offset,
point=point):
values.append(
average_intensity(spin=cur_spin,
exp_type=exp_type,
frq=frq,
offset=offset,
point=point,
time=time))
errors.append(
average_intensity(spin=cur_spin,
exp_type=exp_type,
frq=frq,
offset=offset,
point=point,
time=time,
error=True))
times.append(time)
# Convert to numpy array.
values = asarray(values)
errors = asarray(errors)
times = asarray(times)
# Initialise data in C code.
scaling_list = [1.0, 1.0]
model = Relax_fit_opt(model='exp',
num_params=len(param_vector),
values=values,
errors=errors,
relax_times=times,
scaling_matrix=scaling_list)
# Use the direct Jacobian from function.
jacobian_matrix_exp = transpose(
asarray(model.jacobian(param_vector)))
weights = 1. / errors**2
# Get the co-variance
pcov = multifit_covar(J=jacobian_matrix_exp, weights=weights)
# To compute one standard deviation errors on the parameters, take the square root of the diagonal covariance.
param_vector_error = sqrt(diag(pcov))
# Extract values.
r2eff_err, i0_err = param_vector_error
# Copy r2eff dictionary, to r2eff_err dictionary. They have same keys to the dictionary,
if not hasattr(cur_spin, 'r2eff_err'):
setattr(cur_spin, 'r2eff_err',
deepcopy(getattr(cur_spin, 'r2eff')))
if not hasattr(cur_spin, 'i0_err'):
setattr(cur_spin, 'i0_err', deepcopy(getattr(cur_spin, 'i0')))
# Set error.
cur_spin.r2eff_err[param_key] = r2eff_err
cur_spin.i0_err[param_key] = i0_err
# Get other relevant information.
chi2 = getattr(cur_spin, 'chi2')
# Print information.
print_strings = []
if verbosity >= 1:
# Add print strings.
point_info = "%s at %3.1f MHz, for offset=%3.3f ppm and dispersion point %-5.1f, with %i time points." % (
exp_type, frq / 1E6, offset, point, len(times))
print_strings.append(point_info)
par_info = "r2eff=%3.3f r2eff_err=%3.4f, i0=%6.1f, i0_err=%3.4f, chi2=%3.3f.\n" % (
r2eff, r2eff_err, i0, i0_err, chi2)
print_strings.append(par_info)
if verbosity >= 2:
time_info = ', '.join(map(str, times))
print_strings.append('For time array: ' + time_info +
'.\n\n')
# Print info
if len(print_strings) > 0:
for print_string in print_strings:
print(print_string),
def covariance_matrix(self, model_info=None, verbosity=1):
"""Return the Jacobian and weights required for parameter errors via the covariance matrix.
@keyword model_info: The spin container and the spin ID string from the _model_loop_spin() method.
@type model_info: SpinContainer instance, str
@keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
@type verbosity: int
@return: The Jacobian and weight matrices for the given model.
@rtype: numpy rank-2 array, numpy rank-2 array
"""
# Unpack the data.
spin, spin_id = model_info
# Check that the C modules have been compiled.
if not C_module_exp_fn:
raise RelaxError("Relaxation curve fitting is not available. Try compiling the C modules on your platform.")
# Raise Error, if not optimised.
if not (hasattr(spin, 'rx') and hasattr(spin, 'i0')):
raise RelaxError("Spin '%s' does not contain optimised 'rx' and 'i0' values. Try execute: minimise.execute(min_algor='Newton', constraints=False)"%(spin_id))
# Raise warning, if gradient count is 0. This could point to a lack of minimisation first.
if hasattr(spin, 'g_count'):
if getattr(spin, 'g_count') == 0.0:
text = "Spin %s contains a gradient count of 0.0. Is the rx parameter optimised? Try execute: minimise.execute(min_algor='Newton', constraints=False)" %(spin_id)
warn(RelaxWarning("%s." % text))
# Print information.
if verbosity >= 1:
# Individual spin block section.
top = 2
if verbosity >= 2:
top += 2
subsection(file=sys.stdout, text="Estimating rx error for spin: %s"%spin_id, prespace=top)
# The peak intensities and times.
values = []
errors = []
times = []
for key in spin.peak_intensity:
values.append(spin.peak_intensity[key])
errors.append(spin.peak_intensity_err[key])
times.append(cdp.relax_times[key])
# Convert to numpy array.
values = asarray(values)
errors = asarray(errors)
times = asarray(times)
# Create the parameter vector and scaling matrix (as a diagonalised list).
param_vector = assemble_param_vector(spin=spin)
scaling_list = []
for i in range(len(spin.params)):
scaling_list.append(1.0)
# Initialise data in C code.
model = Relax_fit_opt(model=spin.model, num_params=len(param_vector), values=values, errors=errors, relax_times=times, scaling_matrix=scaling_list)
# Use the direct Jacobian from function.
jacobian_matrix_exp = transpose(asarray( model.jacobian(param_vector) ) )
weights = 1. / errors**2
# Return the matrices.
return jacobian_matrix_exp, weights
def minimise(self, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=False, scaling_matrix=None, verbosity=0, sim_index=None, lower=None, upper=None, inc=None):
"""Relaxation curve fitting minimisation method.
@keyword min_algor: The minimisation algorithm to use.
@type min_algor: str
@keyword min_options: An array of options to be used by the minimisation algorithm.
@type min_options: array of str
@keyword func_tol: The function tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
@type func_tol: None or float
@keyword grad_tol: The gradient tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
@type grad_tol: None or float
@keyword max_iterations: The maximum number of iterations for the algorithm.
@type max_iterations: int
@keyword constraints: If True, constraints are used during optimisation.
@type constraints: bool
@keyword scaling_matrix: The per-model list of diagonal and square scaling matrices.
@type scaling_matrix: list of numpy rank-2, float64 array or list of None
@keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
@type verbosity: int
@keyword sim_index: The index of the simulation to optimise. This should be None if normal optimisation is desired.
@type sim_index: None or int
@keyword lower: The per-model lower bounds of the grid search which must be equal to the number of parameters in the model. This optional argument is only used when doing a grid search.
@type lower: list of lists of numbers
@keyword upper: The per-model upper bounds of the grid search which must be equal to the number of parameters in the model. This optional argument is only used when doing a grid search.
@type upper: list of lists of numbers
@keyword inc: The per-model increments for each dimension of the space for the grid search. The number of elements in the array must equal to the number of parameters in the model. This argument is only used when doing a grid search.
@type inc: list of lists of int
"""
# Checks.
check_mol_res_spin_data()
# Loop over the sequence.
model_index = 0
for spin, spin_id in self.model_loop():
# Skip deselected spins.
if not spin.select:
continue
# Skip spins which have no data.
if not hasattr(spin, 'peak_intensity'):
continue
# Create the initial parameter vector.
param_vector = assemble_param_vector(spin=spin)
# Diagonal scaling.
if scaling_matrix[model_index] is not None:
param_vector = dot(inv(scaling_matrix[model_index]), param_vector)
# Linear constraints.
if constraints:
A, b = linear_constraints(spin=spin, scaling_matrix=scaling_matrix[model_index])
else:
A, b = None, None
# Print out.
if verbosity >= 1:
# Individual spin printout.
if verbosity >= 2:
print("\n\n")
string = "Fitting to spin " + repr(spin_id)
print("\n\n" + string)
print(len(string) * '~')
# Initialise the function to minimise.
######################################
# The peak intensities and times.
values = []
errors = []
times = []
for key in spin.peak_intensity:
# The values.
if sim_index == None:
values.append(spin.peak_intensity[key])
else:
values.append(spin.peak_intensity_sim[sim_index][key])
# The errors.
errors.append(spin.peak_intensity_err[key])
# The relaxation times.
times.append(cdp.relax_times[key])
# The scaling matrix in a diagonalised list form.
scaling_list = []
if scaling_matrix[model_index] is None:
for i in range(len(param_vector)):
scaling_list.append(1.0)
else:
for i in range(len(scaling_matrix[model_index])):
scaling_list.append(scaling_matrix[model_index][i, i])
# Set up the target function.
model = Relax_fit_opt(model=spin.model, num_params=len(spin.params), values=values, errors=errors, relax_times=times, scaling_matrix=scaling_list)
# Setup the minimisation algorithm when constraints are present.
################################################################
if constraints and not match('^[Gg]rid', min_algor):
algor = min_options[0]
else:
algor = min_algor
# Levenberg-Marquardt minimisation.
###################################
if match('[Ll][Mm]$', algor) or match('[Ll]evenburg-[Mm]arquardt$', algor):
# Reconstruct the error data structure.
lm_error = zeros(len(spin.relax_times), float64)
index = 0
for k in range(len(spin.relax_times)):
lm_error[index:index+len(relax_error[k])] = relax_error[k]
index = index + len(relax_error[k])
min_options = min_options + (self.relax_fit.lm_dri, lm_error)
# Minimisation.
###############
# Grid search.
if search('^[Gg]rid', min_algor):
results = grid(func=model.func, args=(), num_incs=inc[model_index], lower=lower[model_index], upper=upper[model_index], A=A, b=b, verbosity=verbosity)
# Unpack the results.
param_vector, chi2, iter_count, warning = results
f_count = iter_count
g_count = 0.0
h_count = 0.0
# Minimisation.
else:
results = generic_minimise(func=model.func, dfunc=model.dfunc, d2func=model.d2func, args=(), x0=param_vector, min_algor=min_algor, min_options=min_options, func_tol=func_tol, grad_tol=grad_tol, maxiter=max_iterations, A=A, b=b, full_output=True, print_flag=verbosity)
# Unpack the results.
if results == None:
return
param_vector, chi2, iter_count, f_count, g_count, h_count, warning = results
# Scaling.
if scaling_matrix[model_index] is not None:
param_vector = dot(scaling_matrix[model_index], param_vector)
# Disassemble the parameter vector.
disassemble_param_vector(param_vector=param_vector, spin=spin, sim_index=sim_index)
# Monte Carlo minimisation statistics.
if sim_index != None:
# Chi-squared statistic.
spin.chi2_sim[sim_index] = chi2
# Iterations.
spin.iter_sim[sim_index] = iter_count
# Function evaluations.
spin.f_count_sim[sim_index] = f_count
# Gradient evaluations.
spin.g_count_sim[sim_index] = g_count
# Hessian evaluations.
spin.h_count_sim[sim_index] = h_count
# Warning.
spin.warning_sim[sim_index] = warning
# Normal statistics.
else:
# Chi-squared statistic.
spin.chi2 = chi2
# Iterations.
spin.iter = iter_count
# Function evaluations.
spin.f_count = f_count
# Gradient evaluations.
spin.g_count = g_count
# Hessian evaluations.
spin.h_count = h_count
# Warning.
spin.warning = warning
# Increment the model index.
model_index += 1
def minimise_minfx(E=None):
"""Estimate r2eff and errors by minimising with minfx.
@keyword E: The Exponential function class, which contain data and functions.
@type E: class
@return: Packed list with optimised parameter, parameter error set to 'inf', chi2, iter_count, f_count, g_count, h_count, warning
@rtype: list
"""
# Check that the C modules have been compiled.
if not C_module_exp_fn:
raise RelaxError("Relaxation curve fitting is not available. Try compiling the C modules on your platform.")
# Initial guess for minimisation. Solved by linear least squares.
x0 = asarray( E.estimate_x0_exp(times=E.times, values=E.values) )
if E.c_code:
# Minimise with C code.
# Initialise the function to minimise.
scaling_list = [1.0, 1.0]
model = Relax_fit_opt(model='exp', num_params=len(x0), values=E.values, errors=E.errors, relax_times=E.times, scaling_matrix=scaling_list)
# Define function to minimise for minfx.
t_func = model.func
t_dfunc = model.dfunc
t_d2func = model.d2func
args=()
else:
# Minimise with minfx.
# Define function to minimise for minfx.
t_func = E.func_exp_chi2
t_dfunc = E.func_exp_chi2_grad
t_d2func = None
# All args to function. Params are packed out through function, then other parameters.
args=(E.times, E.values, E.errors)
# Minimise.
results_minfx = generic_minimise(func=t_func, dfunc=t_dfunc, d2func=t_d2func, args=args, x0=x0, min_algor=E.min_algor, min_options=E.min_options, func_tol=E.func_tol, grad_tol=E.grad_tol, maxiter=E.max_iterations, A=E.A, b=E.b, full_output=True, print_flag=0)
# Unpack
param_vector, chi2, iter_count, f_count, g_count, h_count, warning = results_minfx
# Extract.
r2eff, i0 = param_vector
# Get the Jacobian.
if E.c_code == True:
if E.chi2_jacobian:
# Use the chi2 Jacobian from C.
jacobian_matrix_exp = transpose(asarray( model.jacobian_chi2(param_vector) ) )
weights = ones(E.errors.shape)
else:
# Use the direct Jacobian from C.
jacobian_matrix_exp = transpose(asarray( model.jacobian(param_vector) ) )
weights = 1. / E.errors**2
elif E.c_code == False:
if E.chi2_jacobian:
# Use the chi2 Jacobian from python.
jacobian_matrix_exp = E.func_exp_chi2_grad_array(params=param_vector, times=E.times, values=E.values, errors=E.errors)
weights = ones(E.errors.shape)
else:
# Use the direct Jacobian from python.
jacobian_matrix_exp = E.func_exp_grad(params=param_vector, times=E.times)
weights = 1. / E.errors**2
pcov = multifit_covar(J=jacobian_matrix_exp, weights=weights)
# To compute one standard deviation errors on the parameters, take the square root of the diagonal covariance.
param_vector_error = sqrt(diag(pcov))
# Pack to list.
results = [param_vector, param_vector_error, chi2, iter_count, f_count, g_count, h_count, warning]
# Return, including errors.
return results
def estimate_r2eff_err(spin_id=None, epsrel=0.0, verbosity=1):
"""This will estimate the R2eff and i0 errors from the covariance matrix Qxx. Qxx is calculated from the Jacobian matrix and the optimised parameters.
@keyword spin_id: The spin identification string.
@type spin_id: str
@param epsrel: Any columns of R which satisfy |R_{kk}| <= epsrel |R_{11}| are considered linearly-dependent and are excluded from the covariance matrix, where the corresponding rows and columns of the covariance matrix are set to zero.
@type epsrel: float
@keyword verbosity: The amount of information to print. The higher the value, the greater the verbosity.
@type verbosity: int
"""
# Check that the C modules have been compiled.
if not C_module_exp_fn:
raise RelaxError("Relaxation curve fitting is not available. Try compiling the C modules on your platform.")
# Perform checks.
check_model_type(model=MODEL_R2EFF)
# Loop over the spins.
for cur_spin, mol_name, resi, resn, cur_spin_id in spin_loop(selection=spin_id, full_info=True, return_id=True, skip_desel=True):
# Generate spin string.
spin_string = generate_spin_string(spin=cur_spin, mol_name=mol_name, res_num=resi, res_name=resn)
# Raise Error, if not optimised.
if not (hasattr(cur_spin, 'r2eff') and hasattr(cur_spin, 'i0')):
raise RelaxError("Spin %s does not contain optimised 'r2eff' and 'i0' values. Try execute: minimise.execute(min_algor='Newton', constraints=False)"%(spin_string))
# Raise warning, if gradient count is 0. This could point to a lack of minimisation first.
if hasattr(cur_spin, 'g_count'):
if getattr(cur_spin, 'g_count') == 0.0:
text = "Spin %s contains a gradient count of 0.0. Is the R2eff parameter optimised? Try execute: minimise.execute(min_algor='Newton', constraints=False)" %(spin_string)
warn(RelaxWarning("%s." % text))
# Print information.
if verbosity >= 1:
# Individual spin block section.
top = 2
if verbosity >= 2:
top += 2
subsection(file=sys.stdout, text="Estimating R2eff error for spin: %s"%spin_string, prespace=top)
# Loop over each spectrometer frequency and dispersion point.
for exp_type, frq, offset, point, ei, mi, oi, di in loop_exp_frq_offset_point(return_indices=True):
# The parameter key.
param_key = return_param_key_from_data(exp_type=exp_type, frq=frq, offset=offset, point=point)
# Extract values.
r2eff = getattr(cur_spin, 'r2eff')[param_key]
i0 = getattr(cur_spin, 'i0')[param_key]
# Pack data
param_vector = [r2eff, i0]
# The peak intensities, errors and times.
values = []
errors = []
times = []
for time in loop_time(exp_type=exp_type, frq=frq, offset=offset, point=point):
values.append(average_intensity(spin=cur_spin, exp_type=exp_type, frq=frq, offset=offset, point=point, time=time))
errors.append(average_intensity(spin=cur_spin, exp_type=exp_type, frq=frq, offset=offset, point=point, time=time, error=True))
times.append(time)
# Convert to numpy array.
values = asarray(values)
errors = asarray(errors)
times = asarray(times)
# Initialise data in C code.
scaling_list = [1.0, 1.0]
model = Relax_fit_opt(model='exp', num_params=len(param_vector), values=values, errors=errors, relax_times=times, scaling_matrix=scaling_list)
# Use the direct Jacobian from function.
jacobian_matrix_exp = transpose(asarray( model.jacobian(param_vector) ) )
weights = 1. / errors**2
# Get the co-variance
pcov = multifit_covar(J=jacobian_matrix_exp, weights=weights)
# To compute one standard deviation errors on the parameters, take the square root of the diagonal covariance.
param_vector_error = sqrt(diag(pcov))
# Extract values.
r2eff_err, i0_err = param_vector_error
# Copy r2eff dictionary, to r2eff_err dictionary. They have same keys to the dictionary,
if not hasattr(cur_spin, 'r2eff_err'):
setattr(cur_spin, 'r2eff_err', deepcopy(getattr(cur_spin, 'r2eff')))
if not hasattr(cur_spin, 'i0_err'):
setattr(cur_spin, 'i0_err', deepcopy(getattr(cur_spin, 'i0')))
# Set error.
cur_spin.r2eff_err[param_key] = r2eff_err
cur_spin.i0_err[param_key] = i0_err
# Get other relevant information.
chi2 = getattr(cur_spin, 'chi2')
# Print information.
print_strings = []
if verbosity >= 1:
# Add print strings.
point_info = "%s at %3.1f MHz, for offset=%3.3f ppm and dispersion point %-5.1f, with %i time points." % (exp_type, frq/1E6, offset, point, len(times))
print_strings.append(point_info)
par_info = "r2eff=%3.3f r2eff_err=%3.4f, i0=%6.1f, i0_err=%3.4f, chi2=%3.3f.\n" % ( r2eff, r2eff_err, i0, i0_err, chi2)
print_strings.append(par_info)
if verbosity >= 2:
time_info = ', '.join(map(str, times))
print_strings.append('For time array: '+time_info+'.\n\n')
# Print info
if len(print_strings) > 0:
for print_string in print_strings:
print(print_string),
