parameters.free_energy submodule

cg_openmm.parameters.free_energy.bootstrap_free_energy_folding(Q, Q_folded, array_folded_states=None, output_data='output/output.nc', frame_begin=0, sample_spacing=1, n_trial_boot=200, num_intermediate_states=0, conf_percent='sigma', plotfile_dir='output')

Function for computing uncertainty of free energy, entropy, and enthalpy using bootstrapping with varying starting frames.

Parameters

• Q (2D numpy array ( float )) – native contact fraction array of size [n_frames x n_states] (with equilibration region already trimmed)

• Q_folded (float or list ( float )) – threshold for a native contact fraction corresponding to a folded state (Q[i,j] is folded if Q[i,j] >= Q_folded)

• array_folded_states (2d numpy array (int)) – a precomputed array classifying the different conformational states

• output_data (str) – Path to the simulation .nc file.

• frame_begin (int) – index of first frame defining the range of samples to use as a production period (default=0)

• sample_spacing (int) – spacing of uncorrelated data points, for example determined from pymbar timeseries subsampleCorrelatedData

• n_trial_boot (int) – number of trials to run for generating bootstrapping uncertainties (default=200)

• num_intermediate_states (int) – Number of unsampled thermodynamic states between sampled states to include in the calculation

Returns

• full_T_list - A 1D numpy array listing of all temperatures, including sampled and intermediate unsampled

• deltaF_values - A dictionary of the form {“statei_statej”: 1D numpy array}, containing free energy change for each T in

  full_T_list, for each conformational state transition.

• deltaF uncertainty - A dictionary containing tuple of 1D numpy arrays of lower/upper of uncertainties corresponding to deltaF_values

• deltaS_values - A dictionary of the form {“statei_statej”: 1D numpy array}, containing entropy change for each T in

  full_T_list, for each conformational state transition.

• deltaS uncertainty - A dictionary containing tuple of 1D numpy arrays of lower/upper uncertainties corresponding to deltaS_values

• deltaU_values - A dictionary of the form {“statei_statej”: 1D numpy array}, containing enthalpy change for each T in

  full_T_list, for each conformational state transition.

• deltaU uncertainty - A dictionary containing tuple of 1D numpy arrays of lower/upper of uncertainties corresponding to deltaU_values

cg_openmm.parameters.free_energy.classify_Q_states(Q, Q_folded)

This function determines the conformational state of each element of the native contacts array, given a threshold for being ‘folded/unfolded’. In the outputted array, 1 is ‘folded’ and 0 is ‘unfolded’. If Q_folded is a list, of multiple cutoffs, additional classification is performed.

Parameters

• Q (2D numpy array ( float )) – native contact fraction array of size [n_frames x n_states]

• Q_folded (float) – threshold for a native contact fraction corresponding to a folded state (Q[i,j] is folded if Q[i,j] >= Q_folded)

Returns

• array_folded_states ( 2D numpy array ( float ) ) - conformational state matrix of shape [n_frames x n_replicas]

cg_openmm.parameters.free_energy.expectations_free_energy(Q, Q_folded, temperature_list, frame_begin=0, sample_spacing=1, output_data='output/output.nc', bootstrap_energies=None, num_intermediate_states=0, array_folded_states=None)

This function calculates the free energy difference (with uncertainty) between all conformational states as a function of temperature.

Parameters

• Q (2D numpy array ( float )) – native contact fraction array of size [n_frames x n_states]

• Q_folded (float or list ( float )) – threshold for a native contact fraction corresponding to a folded state (Q[i,j] is folded if Q[i,j] >= Q_folded)

• temperature_list (List( float * simtk.unit.temperature )) – List of temperatures for the simulation data (necessary because bootstrap version doesn’t read in the file)

• frame_begin (int) – index of first frame defining the range of samples to use as a production period (default=0)

• sample_spacing (int) – spacing of uncorrelated data points, for example determined from pymbar timeseries subsampleCorrelatedData

• output_data (str) – Path to the simulation .nc file.

• num_intermediate_states (int) – Number of unsampled thermodynamic states between sampled states to include in the calculation

• bootstrap_energies (2d numpy array (float)) – a custom replica_energies array to be used for bootstrapping calculations. Used instead of the energies in the .nc file.

• array_folded_states (2d numpy array (int)) – a precomputed array classifying the different conformational states

Returns

• full_T_list - A 1D numpy array listing of all temperatures, including sampled and intermediate unsampled

• deltaF_values - A dictionary of the form {“statei_statej”: 1D numpy array}, containing free energy change for each T in

  full_T_list, for each conformational state transition.

• deltaF uncertainty - A dictionary containing 1D numpy arrays of uncertainties corresponding to deltaF_values

cg_openmm.parameters.free_energy.get_entropy_enthalpy(deltaF, temperature_list)

Compute enthalpy change and entropy change upon folding, given free energy of folding for a series of temperatures.

Parameters

• deltaF (dict{"statei_statej":1D numpy array}) – A dictionary containing free energy change for each T in full_T_list, for each conformational state transition.

• temperature_list (List( float * simtk.unit.temperature )) – List of temperatures for the simulation data.

• plotfile_entropy (str) – path to filename for entropy plot (no plot created if None)

• plotfile_enthalpy (str) – path to filename for enthalpy plot (no plot created if None)

Returns

• deltaS - dict{“statei_statej”:1D numpy array} of entropy of folding values for each temperature in temperature_list

• deltaU - dict{“statei_statej”:1D numpy array} of enthalpy of folding values for each temperature in temperature_list

cg_openmm.parameters.free_energy.get_free_energy_derivative(deltaF, temperature_list, plotfile=None)

Fit a heat capacity vs T dataset to cubic spline, and compute derivatives

Parameters

• deltaF (Quantity or numpy 1D array) – free energy of folding data series

• temperature_list – List of temperatures used in replica exchange simulations

• plotfile (str) – path to filename to output plot (default=None)

Returns

• dF_out ( 1D numpy array (float) ) - 1st derivative of free energy, from a cubic spline evaluated at each point in deltaF)

• d2F_out ( 1D numpy array (float) ) - 2nd derivative of free energy, from a cubic spline evaluated at each point in deltaF)

• spline_tck ( scipy spline object (tuple) ) - knot points (t), coefficients (c), and order of the spline (k) fit to deltaF data

cg_openmm.parameters.free_energy.plot_entropy_enthalpy(full_T_list, deltaS_values, deltaU_values, deltaS_uncertainty=None, deltaU_uncertainty=None, plotfile_entropy='entropy.pdf', plotfile_enthalpy='enthalpy.pdf')

Plot entropy and enthalpy difference data for each conformational state transition as a function of temperature.

Parameters

• full_T_list (1D numpy array) – Array listing of all temperatures, including sampled and intermediate unsampled

• deltaS_values (dict{"statei_statej":1D numpy array}) – A dictionary containing entropy change for each T in full_T_list, for each conformational state transition.

• deltaU_values (dict{"statei_statej":1D numpy array}) – A dictionary containing enthalpy change for each T in full_T_list, for each conformational state transition.

• deltaS_uncertainty (dict{"statei_statej": (1D numpy array, 1D numpy array)}) – A dictionary containing uncertainties corresponding to deltaS_values (optional)

• deltaH_uncertainty (dict{"statei_statej": (1D numpy array, 1D numpy array)}) – A dictionary containing uncertainties corresponding to deltaU_values (optional)

• plotfile_entropy (str) – name of entropy plot file, including pdf extension

• plotfile_enthalpy (str) – name of enthalpy plot file, including pdf extension

cg_openmm.parameters.free_energy.plot_free_energy_results(full_T_list, deltaF_values, deltaF_uncertainty, plotfile='free_energy_plot.pdf')

Plot free energy difference data for each conformational state transition as a function of temperature.

Parameters

• full_T_list (1D numpy array) – Array listing of all temperatures, including sampled and intermediate unsampled

• deltaF_values (dict{"statei_statej":1D numpy array}) – A dictionary containing free energy change for each T in full_T_list, for each conformational state transition.

• deltaF_uncertainty (dict{"statei_statej": (1D numpy array, 1D numpy array)} or dict{"statei_statej": (1D numpy array)}) – A dictionary containing uncertainties corresponding to deltaF_values

• plotfile (str) – name of file, including pdf extension