pychemelt.utils package

Submodules

pychemelt.utils.constants module

pychemelt.utils.files module

This module contains helper functions to parse Differential Scanning Fluorimetry files from different instrument providers Author: Osvaldo Burastero

All functions that import files should return: - signal_data_dic: dictionary with the signal data, one entry per signal - temp_data_dic: dictionary with the temperature data, one entry per signal - conditions: list with the names of the samples - signals: list with the names of the signals

A signal can be “350nm”, “330nm”, “Scattering”, “Ratio”, “Turbidity”, “Ratio 350nm/330nm”, etc. The length of the lists in signal_data_dic and temp_data_dic should be the same as the length of conditions

pychemelt.utils.files.load_csv_file(file)

Load a CSV file containing temperature and signal columns and return structured data.

Parameters:

file (str) – Path to the csv file

Returns:

• signal_data_dic (dict) – Dictionary mapping signal names to lists of 1D numpy arrays (one array per condition)

• temp_data_dic (dict) – Dictionary mapping signal names to lists of temperature arrays corresponding to the signals

• conditions (list) – List of condition names

• signals (numpy.ndarray) – Array of signal name strings

pychemelt.utils.files.load_aunty_xlsx(file_path)

Load AUNTY-format multi-sheet Excel file where each sheet is a condition.

Parameters:

file_path (str) – Path to the AUNTY xlsx file

pychemelt.utils.files.load_quantstudio_txt(QSfile)

Load QuantStudio TXT files (.txt) exported from QuantStudio instruments.

Parameters:

QSfile (str) – Path to the QuantStudio txt file

Returns:

• signal_data_dic (dict) – Dictionary with signal data (key: ‘Fluorescence’)

• temp_data_dic (dict) – Dictionary with temperature arrays per condition

• conditions (list) – List of condition names (well identifiers)

• signals (numpy.ndarray) – Array with signal name(s)

pychemelt.utils.files.load_thermofluor_xlsx(thermofluor_file)

Load DSF Thermofluor xls file and extract data.

Parameters:

thermofluor_file (str) – Path to the xls file

Returns:

• signal_data_dic (dict) – Dictionary with signal data

• temp_data_dic (dict) – Dictionary with temperature data

• conditions (list) – List of conditions

pychemelt.utils.files.load_nanoDSF_xlsx(processed_dsf_file)

Load nanotemper processed xlsx file and extract relevant data.

Parameters:

processed_dsf_file (str) – Path to the processed xlsx file

Returns:

• signal_data_dic (dict) – Dictionary with signal data

• temp_data_dic (dict) – Dictionary with temperature data

• conditions (list) – List of conditions

• signals (numpy.ndarray) – Array of signal names

pychemelt.utils.files.load_panta_xlsx(pantaFile)

Load the xlsx file generated by a Prometheus Panta instrument.

Parameters:

pantaFile (str) – Path to the xlsx file

Returns:

• signal_data_dic (dict) – Dictionary with signal data

• temp_data_dic (dict) – Dictionary with temperature data

• conditions (list) – List of conditions

• signals (numpy.ndarray) – List of signal names, such as 330nm and 350nm

pychemelt.utils.files.load_uncle_multi_channel(uncle_file)

Function to load the data from the UNCLE instrument.

Parameters:

uncle_file (str) – Path to the xlsx file

Returns:

• signal_data_dic (dict) – Dictionary with signal data (keys: wavelength strings like ‘350 nm’)

• temp_data_dic (dict) – Dictionary with temperature arrays per condition

• conditions (list) – List of sample names

• signals (list) – List of wavelength strings

pychemelt.utils.files.load_mx3005p_txt(filename)

Load Agilent MX3005P qPCR txt file and extract data

Parameters:

filename (str) – Path to the MX3005P txt file. The second column has the fluorescence data, and the third column the temperature. Wells are separated by rows containing a sentence like this one: ‘Segment 2 Plateau 1 Well 1’

Returns:

• signal_data_dic (dict) – Dictionary with signal data

• temp_data_dic (dict) – Dictionary with temperature data

• conditions (list) – List of conditions (well numbers)

• signals (numpy.ndarray) – List of signal names

pychemelt.utils.files.detect_file_type(file)

Detect the type of file based on its extension and content.

Parameters:

file (str) – Path to the file

Returns:

Type of file (e.g., ‘supr’, ‘csv’, ‘prometheus’, ‘panta’, ‘uncle’, ‘mx3005p’, ‘quantstudio’, etc.) or None if unknown

Return type:

str or None

pychemelt.utils.files.detect_encoding(file_path)

Detect the encoding of a file by trying common encodings.

Parameters:

file_path (str) – Path to the file

Returns:

Detected encoding or the string ‘Unknown encoding’

Return type:

str

pychemelt.utils.files.read_jasco_thermal_ramp(file)

Given a JASCO file with a thermal ramp, this function reads the data

The data is given in chuncks:

Channel 1

4.94 14.93 25.08 35.02 45.03 55.07 64.99 75.04 85.08 95.03

250 -0.310564 -0.112003 0.0199744 -0.217282 -0.238716 -0.173046 0.00129784 -0.394731 -0.687165 -1.40543

Parameters:

file (str) – Path to the JASCO thermal ramp file

Returns:

• signal_data_dic (dict) – Dictionary with signal data (key: wavelength string like ‘250 nm’)

• temp_data_dic (dict) – Dictionary with temperature arrays per condition (only one condition in this case)

• conditions (list) – File name as condition

• wavelength_data (list) – List of wavelength strings (e.g., ‘250 nm’, ‘255 nm’, etc.)

pychemelt.utils.fitting module

This module contains helper functions to fit unfolding data Author: Osvaldo Burastero

pychemelt.utils.fitting.fit_line_robust(x, y)

Fit a line to the data using robust fitting

Parameters:

• x (array-like) – x data

• y (array-like) – y data

Returns:

• m (float) – Slope of the fitted line

• b (float) – Intercept of the fitted line

pychemelt.utils.fitting.fit_quadratic_robust(x, y)

Fit a quadratic equation to the data using robust fitting

Parameters:

• x (array-like) – x data

• y (array-like) – y data

Returns:

• a (float) – Quadratic coefficient of the fitted polynomial

• b (float) – Linear coefficient of the fitted polynomial

• c (float) – Constant coefficient of the fitted polynomial

pychemelt.utils.fitting.fit_exponential_robust(x, y)

Fit an exponential function to the data using robust fitting.

Notes

Temperatures should be shifted to the reference (Tref) before calling this function.

Parameters:

• x (array-like) – x data

• y (array-like) – y data

Returns:

• a (float) – Baseline

• c (float) – Pre-exponential factor

• alpha (float) – Exponential factor

pychemelt.utils.fitting.fit_thermal_unfolding(list_of_temperatures, list_of_signals, initial_parameters, low_bounds, high_bounds, signal_fx, baseline_native_fx, baseline_unfolded_fx, Cp, gas_cst=0.001987, list_of_oligomer_conc=None)

Fit the thermal unfolding profile of many curves at the same time.

This performs global fitting of shared thermodynamic parameters with per-curve baselines.

Parameters:

• list_of_temperatures (list of array-like) – List of temperature arrays for each dataset

• list_of_signals (list of array-like) – List of signal arrays for each dataset

• initial_parameters (array-like) – Initial guess for the parameters

• low_bounds (array-like) – Lower bounds for the parameters

• high_bounds (array-like) – Upper bounds for the parameters

• signal_fx (callable) – Function to calculate the signal based on the parameters

• baseline_native_fx (callable) – function to calculate the native state baseline

• baseline_unfolded_fx (callable) – function to calculate the unfolded state baseline

• Cp (float) – Heat capacity change (passed to signal_fx)

• list_of_oligomer_conc (list, optional) – List of oligomer concentrations for each dataset (if applicable)

Returns:

• global_fit_params (numpy.ndarray) – Fitted global parameters

• cov (numpy.ndarray) – Covariance matrix of the fitted parameters

• predicted_lst (list of numpy.ndarray) – Predicted signals for each dataset based on the fitted parameters

pychemelt.utils.fitting.fit_tc_unfolding_single_slopes(list_of_temperatures, list_of_signals, denaturant_concentrations, initial_parameters, low_bounds, high_bounds, signal_fx, baseline_native_fx, baseline_unfolded_fx, fit_m1=False, cp_value=None, tm_value=None, dh_value=None, method='least_squares', gas_cst=0.001987)

Vectorized and optimized version of global thermal unfolding fitting.

Parameters:

list_of_temperatureslist of array-like

Temperature arrays for each dataset

list_of_signalslist of array-like

Signal arrays for each dataset

denaturant_concentrationslist

Denaturant concentrations (one per dataset)

initial_parametersarray-like

Initial guess for parameters

low_boundsarray-like

Lower bounds for parameters

high_boundsarray-like

Upper bounds for parameters

signal_fxcallable

Signal model function

baseline_native_fxcallable

function to calculate the native state baseline

baseline_unfolded_fxcallable

function to calculate the unfolded state baseline

fit_m1bool, optional

Whether to fit temperature dependence of m-value

cp_value, tm_value, dh_valuefloat or None, optional

Optional fixed thermodynamic parameters

methodstr, optional

Optimization method (‘least_sq’ or ‘curve_fit’)

:returns: * **global_fit_params (numpy.ndarray) – Fitted global parameters**

• cov (numpy.ndarray) – Covariance matrix

• predicted_lst (list of numpy.ndarray) – Predicted signals per dataset

pychemelt.utils.fitting.fit_tc_unfolding_shared_slopes_many_signals(list_of_temperatures, list_of_signals, signal_ids, denaturant_concentrations, initial_parameters, low_bounds, high_bounds, signal_fx, baseline_native_fx, baseline_unfolded_fx, fit_m1=False, cp_value=None, tm_value=None, dh_value=None, method='least_squares', gas_cst=0.001987)

Vectorized fitting of thermochemical unfolding curves for multiple signal types sharing thermodynamic parameters and slopes, using lmfit.

Parameters:

• list_of_temperatures (list of array-like) – Temperature arrays for each dataset

• list_of_signals (list of array-like) – Signal arrays for each dataset

• signal_ids (list of int) – Signal-type id for each dataset (0..n_signals-1)

• denaturant_concentrations (list) – Denaturant concentrations for each dataset (flattened across signals)

• initial_parameters (array-like) – Initial guess for the parameters

• low_bounds (array-like) – Lower bounds for the parameters

• high_bounds (array-like) – Upper bounds for the parameters

• signal_fx (callable) –

  Signal model function baseline_native_fx : callable

  function to calculate the baseline for the native state

• baseline_unfolded_fx (callable) – function to calculate the baseline for the unfolded state

• fit_m1 (bool, optional) – Whether to fit temperature dependence of m-value

• cp_value (float or None, optional) – Optional fixed thermodynamic parameters

• tm_value (float or None, optional) – Optional fixed thermodynamic parameters

• dh_value (float or None, optional) – Optional fixed thermodynamic parameters

• method (str, optional) – Optimization method for lmfit minimizer. Defaults to ‘least_squares’.

Returns:

• global_fit_params (numpy.ndarray) – Fitted global parameters

• cov (numpy.ndarray) – Covariance matrix

• predicted_lst (list of numpy.ndarray) – Predicted signals per dataset

• result (lmfit.minimizer.MinimizerResult) – lmfit minimization result object

• minimizer (lmfit.minimizer.Minimizer) – lmfit minimizer object

pychemelt.utils.fitting.fit_tc_unfolding_many_signals(list_of_temperatures, list_of_signals, signal_ids, denaturant_concentrations, initial_parameters, low_bounds, high_bounds, signal_fx, baseline_native_fx, baseline_unfolded_fx, fit_m1=False, model_scale_factor=False, scale_factor_exclude_ids=[], cp_value=None, method='least_squares', fit_native_den_slope=True, fit_unfolded_den_slope=True, gas_cst=0.001987)

Fit thermochemical unfolding curves for many signals using lmfit.

Parameters:

• list_of_temperatures (list of array-like) – Temperature arrays for each dataset.

• list_of_signals (list of array-like) – Signal arrays for each dataset.

• signal_ids (list of int) – Signal-type id for each dataset (0..n_signals-1)

• denaturant_concentrations (list) – Denaturant concentrations for each dataset (flattened across signals)

• initial_parameters (array-like) – Initial guess for the parameters

• low_bounds (array-like) – Lower bounds for the parameters

• high_bounds (array-like) – Upper bounds for the parameters

• signal_fx (callable) – Signal model function

• baseline_native_fx (callable) – function to calculate the native state baseline

• baseline_unfolded_fx (callable) – function to calculate the unfolded state baseline

• fit_m1 (bool, optional) – Whether to include and fit temperature dependence of the m-value (m1)

• model_scale_factor (bool, optional) – If True, include a per-denaturant concentration scale factor to account for intensity differences

• scale_factor_exclude_ids (list, optional) – IDs of scale factors to exclude / fix to 1

• cp_value (float or None, optional) – If provided, Cp is fixed to this value and not fitted

• method (str, optional) – Optimization method for lmfit minimizer. Defaults to ‘least_squares’.

• fit_native_den_slope (bool, optional) – Whether to fit denaturant dependence of baselines.

• fit_unfolded_den_slope (bool, optional) – Whether to fit denaturant dependence of baselines.

Returns:

• global_fit_params (numpy.ndarray) – Fitted global parameters

• cov (numpy.ndarray) – Covariance matrix

• predicted_lst (list of numpy.ndarray) – Predicted signals per dataset

• result (lmfit.minimizer.MinimizerResult) – lmfit minimization result object

• minimizer (lmfit.minimizer.Minimizer) – lmfit minimizer object

pychemelt.utils.fitting.fit_oligomer_unfolding_single_slopes(list_of_temperatures, list_of_signals, oligomer_concentrations, initial_parameters, low_bounds, high_bounds, signal_fx, baseline_native_fx, baseline_unfolded_fx, cp_value=None, tm_value=None, dh_value=None, method='least_squares', gas_cst=0.001987)

Vectorized and optimized version of global thermal unfolding fitting. of oligomers

Parameters:

• list_of_temperatures (list of array-like) – Temperature arrays for each dataset

• list_of_signals (list of array-like) – Signal arrays for each dataset

• oligomer_concentrations (list) – sample concentrations of the oligomeric complex (one per dataset)

• initial_parameters (array-like) – Initial guess for parameters

• low_bounds (array-like) – Lower bounds for parameters

• high_bounds (array-like) – Upper bounds for parameters

• signal_fx (callable) – Signal model function

• baseline_native_fx (callable) – function to calculate the native state baseline

• baseline_unfolded_fx (callable) – function to calculate the unfolded state baseline

• cp_value (float or None, optional) – Optional fixed thermodynamic parameters

• tm_value (float or None, optional) – Optional fixed thermodynamic parameters

• dh_value (float or None, optional) – Optional fixed thermodynamic parameters

Returns:

• global_fit_params (numpy.ndarray) – Fitted global parameters

• cov (numpy.ndarray) – Covariance matrix

• predicted_lst (list of numpy.ndarray) – Predicted signals per dataset

• result (lmfit.minimizer.MinimizerResult) – lmfit minimization result object

• minimizer (lmfit.minimizer.Minimizer) – lmfit minimizer object

pychemelt.utils.fitting.fit_oligomer_unfolding_shared_slopes_many_signals(list_of_temperatures, list_of_signals, signal_ids, oligomer_concentrations, initial_parameters, low_bounds, high_bounds, signal_fx, baseline_native_fx, baseline_unfolded_fx, cp_value=None, tm_value=None, dh_value=None, method='least_squares', gas_cst=0.001987)

Vectorized fitting of oligomer thermal unfolding curves for multiple signal types sharing thermodynamic parameters and slopes, using lmfit.

Parameters:

• list_of_temperatures (list of array-like) – Temperature arrays for each dataset.

• list_of_signals (list of array-like) – Signal arrays for each dataset.

• signal_ids (list of int) – Signal-type id for each dataset (0..n_signals-1)

• oligomer_concentrations (list) – sample concentrations of the oligomeric complex for each dataset (flattened across signals)

• initial_parameters (array-like) – Initial guess for the parameters

• low_bounds (array-like) – Lower bounds for the parameters

• high_bounds (array-like) – Upper bounds for the parameters

• signal_fx (callable) –

  Signal model function baseline_native_fx : callable

  function to calculate the baseline for the native state

• baseline_unfolded_fx (callable) – function to calculate the baseline for the unfolded state

• cp_value (float or None, optional) – Optional fixed thermodynamic parameters

• tm_value (float or None, optional) – Optional fixed thermodynamic parameters

• dh_value (float or None, optional) – Optional fixed thermodynamic parameters

Returns:

• global_fit_params (numpy.ndarray) – Fitted global parameters

• cov (numpy.ndarray) – Covariance matrix

• predicted_lst (list of numpy.ndarray) – Predicted signals per dataset

• result (lmfit.minimizer.MinimizerResult) – lmfit minimization result object

• minimizer (lmfit.minimizer.Minimizer) – lmfit minimizer object

pychemelt.utils.fitting.fit_oligomer_unfolding_many_signals(list_of_temperatures, list_of_signals, signal_ids, oligomer_concentrations, initial_parameters, low_bounds, high_bounds, signal_fx, baseline_native_fx, baseline_unfolded_fx, model_scale_factor=False, scale_factor_exclude_ids=[], cp_value=None, method='least_squares', gas_cst=0.001987)

Fit thermal unfolding curves of oligomers for many signals (optimized variant).

Parameters:

list_of_temperatureslist of array-like

Temperature arrays for each dataset

list_of_signalslist of array-like

Signal arrays for each dataset

signal_idslist of int

Signal-type id for each dataset (0..n_signals-1)

oligomer_concentrationslist

sample concentrations of the oligomeric complex for each dataset (flattened across signals)

initial_parametersarray-like

Initial guess for the parameters

low_boundsarray-like

Lower bounds for the parameters

high_boundsarray-like

Upper bounds for the parameters

signal_fxcallable

Signal model function

baseline_native_fxcallable

function to calculate the native state baseline

baseline_unfolded_fxcallable

function to calculate the unfolded state baseline

model_scale_factorbool, optional

If True, include a per-oligomeric concentration scale factor to account for intensity differences

scale_factor_exclude_idslist, optional

IDs of scale factors to exclude / fix to 1

cp_valuefloat or None, optional

If provided, Cp is fixed to this value and not fitted

Returns:

global_fit_paramsnumpy.ndarray

Fitted global parameters

covnumpy.ndarray

Covariance matrix

predicted_lstlist of numpy.ndarray

Predicted signals per dataset

resultlmfit.minimizer.MinimizerResult

lmfit minimization result object

minimizerlmfit.minimizer.Minimizer

lmfit minimizer object

pychemelt.utils.fitting.fit_oligomer_unfolding_three_states_single_slopes(list_of_temperatures, list_of_signals, oligomer_concentrations, initial_parameters, low_bounds, high_bounds, signal_fx, baseline_native_fx, baseline_unfolded_fx, t1=None, t2=None, dh1=None, dh2=None, CpTh_value=None, method='least_squares', max_nfev=None, gas_cst=0.001987)

Vectorized and optimized version of global thermal unfolding fitting of oligomers.

Returns:

• global_fit_params (numpy.ndarray)

• cov (numpy.ndarray)

• predicted_lst (list of numpy.ndarray)

• result (lmfit.minimizer.MinimizerResult)

• minimizer (lmfit.minimizer.Minimizer)

Note

Dear dev/user. Fitting Cp1 will probably not work in the case of monomers, given that changing Cp does not change the shape of the unfolding curve.

pychemelt.utils.fitting.fit_oligomer_unfolding_three_states_shared_slopes_many_signals(list_of_temperatures, list_of_signals, signal_ids, oligomer_concentrations, initial_parameters, low_bounds, high_bounds, signal_fx, baseline_native_fx, baseline_unfolded_fx, t1=None, t2=None, dh1=None, dh2=None, CpTh_value=None, method='least_squares', gas_cst=0.001987)

Vectorized fitting of oligomer thermal unfolding curves for multiple signal types sharing thermodynamic parameters and slopes, using lmfit.

Parameters:

• list_of_temperatures (list of array-like) – Temperature arrays for each dataset.

• list_of_signals (list of array-like) – Signal arrays for each dataset.

• signal_ids (list of int) – Signal-type id for each dataset (0..n_signals-1)

• oligomer_concentrations (list) – Oligomer concentrations for each dataset (flattened across signals)

• initial_parameters (array-like) – Initial guess for the parameters

• low_bounds (array-like) – Lower bounds for the parameters

• high_bounds (array-like) – Upper bounds for the parameters

• signal_fx (callable) –

  Signal model function baseline_native_fx : callable

  function to calculate the baseline for the native state

• baseline_unfolded_fx (callable) – function to calculate the baseline for the unfolded state

• t1 (float, optional) – Values for the unfolding temperatures one and two

• t2 (float, optional) – Values for the unfolding temperatures one and two

• dh1 (float, optional) – Values for the unfolding enthalpy one and two

• dh2 (float, optional) – Values for the unfolding enthalpy one and two

• CpTh_value (float, optional) – Value for the total Cp of the system, enabling fitting of Cp1

Returns:

• global_fit_params (numpy.ndarray) – Fitted global parameters

• cov (numpy.ndarray) – Covariance matrix

• predicted_lst (list of numpy.ndarray) – Predicted signals per dataset

• result (lmfit.minimizer.MinimizerResult)

• minimizer (lmfit.minimizer.Minimizer)

pychemelt.utils.fractions module

This module contains helper functions to obtain the amount of folded/intermediate/unfolded (etc.) protein Author: Osvaldo Burastero

pychemelt.utils.fractions.fn_two_state_monomer(K)

Given the equilibrium constant K of N <-> U, return the fraction of folded protein.

Parameters:

K (float) – Equilibrium constant of the reaction N <-> U

Returns:

Fraction of folded protein

Return type:

float

pychemelt.utils.fractions.fu_two_state_dimer(K, C)

Given the equilibrium constant K, of N2 <-> 2U, and the concentration of dimer equivalent C, return the fraction of unfolded protein

Parameters:

• K (float) – Equilibrium constant of the reaction N2 <-> 2U

• C (float) – Total concentration of the protein in dimer equivalents

Returns:

Fraction of unfolded protein

Return type:

float

pychemelt.utils.fractions.fu_two_state_trimer(K, C)

Given the equilibrium constant K, of N3 <-> 3U, and the concentration of trimer equivalent C, return the fraction of unfolded protein

Parameters:

• K (float) – Equilibrium constant of the reaction N3 <-> 3U

• C (float) – Total concentration of the protein in trimer equivalents

Returns:

Fraction of unfolded protein

Return type:

float

pychemelt.utils.fractions.fu_two_state_tetramer(K, C)

Given the equilibrium constant K, of N4 <-> 4U, and the concentration of tetramer equivalent C, return the fraction of folded protein

Parameters:

• K (float) – Equilibrium constant of the reaction N4 <-> 4U

• C (float) – Total concentration of the protein in tetramer equivalents

Returns:

Fraction of unfolded protein

Return type:

float

pychemelt.utils.fractions.fi_three_state_tetramer_monomeric_intermediate(K1, K2, Ct)

Given the equilibrium constant K1, of N4 <-> 4I, K2, of I <-> U, and the concentration of tetramer equivalent Ct, return the fraction of intermediate

pychemelt.utils.fractions.fi_three_state_dimer_monomeric_intermediate(K1, K2, C)

Given the equilibrium constant K1, of N2 <-> 2I, K2, of 2I <-> 2U and the concentration of dimer equivalent C, return the fraction of intermediate

pychemelt.utils.fractions.fu_three_state_dimer_dimeric_intermediate(K1, K2, C)

Given the equilibrium constant K1, of N2 <-> I2, K2, of I2 <-> 2U and the concentration of dimer equivalent C, return the fraction of unfolded protein

pychemelt.utils.fractions.fi_three_state_dimer_dimeric_intermediate(fu, K2, C)

Given the fraction of unfolded protein fu, the equilibrium constant K2, of I2 <-> 2U, and the concentration of dimer equivalent C, return the fraction of intermediate

pychemelt.utils.fractions.fi_three_state_trimer_monomeric_intermediate(K1, K2, C)

Given the equilibrium constant K1, of N3 <-> 3I, K2, of 3I <-> 3U and the concentration of trimer equivalent C, return the fraction of unfolded protein

pychemelt.utils.fractions.fu_three_state_trimer_trimeric_intermediate(K1, K2, C)

Given the equilibrium constant K1, of N3 <-> I3, K2, of I3 <-> 3U and the concentration of trimer equivalent C, return the fraction of unfolded protein

pychemelt.utils.fractions.fi_three_state_trimer_trimeric_intermediate(fu, K2, C)

Given the fraction of unfolded protein fu, the equilibrium constant K2, of I3 <-> 3U, and the concentration of trimer equivalent C, return the fraction of intermediate

pychemelt.utils.math module

This module contains helper functions for mathematical operations Author: Osvaldo Burastero

pychemelt.utils.math.temperature_to_kelvin(T)

Convert temperature from Celsius to Kelvin if necessary.

Parameters:

T (array-like) – Temperature values

Returns:

Temperature values in Kelvin

Return type:

array-like

pychemelt.utils.math.temperature_to_celsius(T)

Convert temperature from Kelvin to Celsius if necessary.

Parameters:

T (array-like) – Temperature values

Returns:

Temperature values in Celsius

Return type:

array-like

pychemelt.utils.math.shift_temperature(T)

Shift temperature to be relative to Tref_cst in Kelvin.

Parameters:

T (array-like) – Temperature values

Returns:

Shifted temperature values

Return type:

array-like

pychemelt.utils.math.constant_baseline(dt, d, den_slope, a, *args)

Baseline function with no dependence on temperature and dependence on denaturant concentration

Parameters:

• dt (float) – delta temperature, not used here but required for compatibility with other baseline functions

• d (float) – denaturant concentration

• den_slope (float) – linear dependence of signal on denaturant concentration

• a (float) – intercept of the baseline

Returns:

Baseline signal

Return type:

float

pychemelt.utils.math.linear_baseline(dt, d, den_slope, a, b, *args)

Baseline function with linear dependence on temperature and linear dependence on denaturant concentration

Parameters:

• dt (float) – delta temperature, not used here but required for compatibility with other baseline functions

• d (float) – denaturant concentration

• den_slope (float) – linear dependence of signal on denaturant concentration

• a (float) – intercept of the baseline

• b (float) – linear dependence of signal on temperature

Returns:

Baseline signal

Return type:

float

pychemelt.utils.math.quadratic_baseline(dt, d, den_slope, a, b, c)

Baseline function with quadratic dependence on temperature and linear dependence on denaturant concentration

Parameters:

• dt (float) – delta temperature, not used here but required for compatibility with other baseline functions

• d (float) – denaturant concentration

• den_slope (float) – linear dependence of signal on denaturant concentration

• a (float) – intercept of the baseline

• b (float) – linear dependence of signal on temperature

• c (float) – quadratic dependence of signal on temperature

Returns:

Baseline signal

Return type:

float

pychemelt.utils.math.exponential_baseline(dt, d, den_slope, a, c, alpha)

Baseline function with exponential dependence on temperature and linear dependence on denaturant concentration

Parameters:

• dt (float) – delta temperature, not used here but required for compatibility with other baseline functions

• d (float) – denaturant concentration

• den_slope (float) – linear dependence of signal on denaturant concentration

• a (float) – intercept of the baseline

• b (float) – pre-exponential factor for the dependence on temperature

• c (float) – exponential coefficient for the dependence on temperature

Returns:

Baseline signal

Return type:

float

pychemelt.utils.math.constant_baseline_only_temp(dt, a, *args)

Baseline function with no dependence on temperature or denaturant concentration

Parameters:

• dt (float) – delta temperature, not used here but required for compatibility with other baseline functions

• a (float) – intercept of the baseline

Returns:

Baseline signal

Return type:

float

pychemelt.utils.math.linear_baseline_only_temp(dt, a, b, *args)

Baseline function with linear dependence on temperature and no dependence on denaturant concentration

Parameters:

• dt (float) – delta temperature

• a (float) – intercept of the baseline

• b (float) – linear dependence of signal on temperature

Returns:

Baseline signal

Return type:

float

pychemelt.utils.math.quadratic_baseline_only_temp(dt, a, b, c)

Baseline function with quadratic dependence on temperature and no dependence on denaturant concentration

Parameters:

• dt (float) – delta temperature

• a (float) – intercept of the baseline

• b (float) – linear dependence of signal on temperature

• c (float) – quadratic dependence of signal on temperature

Returns:

Baseline signal

Return type:

float

pychemelt.utils.math.exponential_baseline_only_temp(dt, a, c, alpha)

Baseline function with exponential dependence on temperature and no dependence on denaturant concentration

Parameters:

• dt (float) – delta temperature

• a (float) – intercept of the baseline

• c (float) – pre-exponential factor for the dependence on temperature

• alpha (float) – exponential coefficient for the dependence on temperature

Returns:

Baseline signal

Return type:

float

pychemelt.utils.math.is_evenly_spaced(x, tol=0.0001)

Check if x is evenly spaced within a given tolerance.

Parameters:

• x (array-like) – x data

• tol (float, optional) – Tolerance for considering spacing equal (default: 1e-4)

Returns:

True if x is evenly spaced, False otherwise

Return type:

bool

pychemelt.utils.math.first_derivative_savgol(x, y, window_length=5, polyorder=4)

Estimate the first derivative using Savitzky-Golay filtering.

Parameters:

• x (array-like) – x data (must be evenly spaced)

• y (array-like) – y data

• window_length (int, optional) – Length of the filter window, in temperature units (default: 5)

• polyorder (int, optional) – Order of the polynomial used to fit the samples (default: 4)

Returns:

First derivative of y with respect to x

Return type:

numpy.ndarray

Notes

This function will raise a ValueError if x is not evenly spaced.

pychemelt.utils.math.relative_errors(params, cov)

Calculate the relative errors of the fitted parameters.

Parameters:

• params (numpy.ndarray) – Fitted parameters

• cov (numpy.ndarray) – Covariance matrix of the fitted parameters

Returns:

Relative errors of the fitted parameters (in percent)

Return type:

numpy.ndarray

pychemelt.utils.math.find_line_outliers(m, b, x, y, sigma=2.5)

Find outliers in a linear fit using the sigma rule.

Parameters:

• m (float) – Slope of the line

• b (float) – Intercept of the line

• x (array-like) – x data

• y (array-like) – y data

• sigma (float, optional) – Number of standard deviations to use for outlier detection (default: 2.5)

Returns:

Indices of the outliers

Return type:

numpy.ndarray

pychemelt.utils.math.get_rss(y, y_fit)

Compute the residual sum of squares.

Parameters:

• y (array-like) – Observed values

• y_fit (array-like) – Fitted values

Returns:

Residual sum of squares

Return type:

float

pychemelt.utils.math.solve_one_root_quadratic(a, b, c)

Solution to one root quadratic: a * X**2 + b * X + c = 0

Parameters:

• a (number type) – parameter a

• b (number type) – parameter b

• c (number type) – parameter c

Returns:

Solution of the formula

Return type:

float

pychemelt.utils.math.solve_one_root_depressed_cubic(p, q)

Solution to one root depressed cubic: X**3 + p * X + q = 0

Parameters:

• p (number type) – parameter p

• q (number type) – parameter q

Returns:

Solution of the formula

Return type:

float

pychemelt.utils.math.aic_bic_eff(result, neff)

Calculate the AIC and BIC for a fitted model, accounting for the effective number of data points.

Parameters:

• result (OptimizeResult) – The result object returned by the fitting procedure, which contains the chi-squared value and the number of parameters.

• neff (int) – The effective number of data points, which may be less than the total number of data points due to correlations or other factors.

Returns:

A tuple containing the AIC and BIC values (AIC, BIC).

Return type:

tuple

pychemelt.utils.math.extended_bic(result, neff, gamma=0.5)

Calculate the Extended Bayesian Information Criterion (EBIC) for a fitted model, accounting for the effective number of data points.

The EBIC adds an additional penalty term to BIC to help with model selection in high-dimensional settings. When gamma=0, EBIC reduces to standard BIC. Higher gamma values impose stronger penalties for model complexity.

Parameters:

• result (OptimizeResult) – The result object returned by the fitting procedure, which contains the chi-squared value and the number of parameters.

• neff (int) – The effective number of data points, which may be less than the total number of data points due to correlations or other factors.

• gamma (float, optional) – Tuning parameter for the extended penalty term, typically between 0 and 1 (default: 0.5). gamma=0 gives standard BIC, gamma=1 gives maximum penalty.

Returns:

The EBIC value.

Return type:

float

Notes

EBIC = n * log(chisq / n) + k * log(n) + 2 * gamma * log(C(n, k)) where C(n, k) is the binomial coefficient.

pychemelt.utils.palette module

Viridis color palette.

A perceptually uniform color map that is readable by those with colorblindness. Contains hex color values transitioning from dark purple to yellow.

pychemelt.utils.plotting module

class pychemelt.utils.plotting.PlotConfig(width: int = 1000, height: int = 800, type: str = 'png', font_size: int = 16, marker_size: int = 8, line_width: int = 3)

Bases: object

General plot configuration

width: int = 1000

height: int = 800

type: str = 'png'

font_size: int = 16

marker_size: int = 8

line_width: int = 3

class pychemelt.utils.plotting.AxisConfig(showgrid_x: bool = True, showgrid_y: bool = True, n_y_axis_ticks: int = 5, linewidth: int = 1, tickwidth: int = 1, ticklen: int = 5, gridwidth: int = 1)

Bases: object

Axis styling configuration

showgrid_x: bool = True

showgrid_y: bool = True

n_y_axis_ticks: int = 5

linewidth: int = 1

tickwidth: int = 1

ticklen: int = 5

gridwidth: int = 1

class pychemelt.utils.plotting.LayoutConfig(show_subplot_titles: bool = False, vertical_spacing: float = 0.1)

Bases: object

Layout and spacing configuration

show_subplot_titles: bool = False

vertical_spacing: float = 0.1

class pychemelt.utils.plotting.LegendConfig

Bases: object

Legend and labeling configuration

color_bar_length = 0.4

color_bar_orientation = 'v'

color_bar_x_pos = 1.05

color_bar_y_pos = 0.5

pychemelt.utils.plotting.config_fig(fig, plot_width=800, plot_height=600, plot_type='png', plot_title_for_download='plot')

Configure plotly figure with download options and toolbar settings.

Parameters:

• fig (go.Figure) – Plotly figure object

• plot_width (int, default 800) – Width of the plot in pixels

• plot_height (int, default 600) – Height of the plot in pixels

• plot_type (str, default "png") – Format for downloading the plot (e.g., “png”, “jpeg”)

• plot_title_for_download (str, default "plot") – Title for the downloaded plot file

Returns:

Configured plotly figure

Return type:

go.Figure

pychemelt.utils.plotting.plot_unfolding(pychemelt_sample, plot_derivative=False, plot_baseline_df=False, plot_config: PlotConfig = None, axis_config: AxisConfig = None, layout_config: LayoutConfig = None, legend_config: LegendConfig = None, use_scaled_data=False)

Plot the unfolding curves, including the signal and the predicted curves

Parameters:

• pychemelt_sample – pychemelt.Sample object

• plot_derivative (bool) – Whether to plot the derivative of the signal

• plot_baseline_df (bool) – Whether to overlay baselines from pychemelt_sample.baseline_df (if available)

• plot_config (PlotConfig, optional) – Configuration for the overall plot

• axis_config (AxisConfig, optional) – Configuration for the axes

• layout_config (LayoutConfig, optional) – Configuration for the layout

• legend_config (LegendConfig, optional) – Configuration for the legend

• use_scaled_data (bool) – Whether to use the scaled data for plotting (if True, the scaled signal and predicted curves will be plotted instead of the raw data) The scaling is obtained from the scale factor of the global-global-global fit

pychemelt.utils.plotting.plot_residuals(pychemelt_sample, individual_curves=False, plot_config: PlotConfig = None, axis_config: AxisConfig = None, layout_config: LayoutConfig = None, legend_config: LegendConfig = None)

Plot the residuals (experimental - fitted) of the unfolding curves

Parameters:

• pychemelt_sample – pychemelt.Sample object (must have fitted data)

• individual_curves (bool, optional) – If False (default), group all denaturant concentrations per signal in one subplot. If True, plot each combination of signal and denaturant concentration in separate subplots.

• plot_config (PlotConfig, optional) – Configuration for the overall plot

• axis_config (AxisConfig, optional) – Configuration for the axes

• layout_config (LayoutConfig, optional) – Configuration for the layout

• legend_config (LegendConfig, optional) – configuration for the legend

Returns:

fig – Plotly figure object with residual plots

Return type:

go.Figure

Raises:

ValueError – If no fitting has been performed on the sample

pychemelt.utils.plotting.plot_baselines(pychemelt_sample, plot_config: PlotConfig = None, axis_config: AxisConfig = None, layout_config: LayoutConfig = None, legend_config: LegendConfig = None)

Plot the fitted native and unfolded baseline curves on the data

Parameters:

• pychemelt_sample – pychemelt.Sample object

• plot_config (PlotConfig, optional) – Configuration for the overall plot

• axis_config (AxisConfig, optional) – Configuration for the axes

• layout_config (LayoutConfig, optional) – Configuration for the layout

• legend_config (LegendConfig, optional) – configuration for the legend

pychemelt.utils.processing module

This module contains helper functions to process data Author: Osvaldo Burastero

pychemelt.utils.processing.set_param_bounds(p0, param_names)

Generate heuristic lower and upper bounds for fitting parameters based on initial guesses.

Parameters:

• p0 (array-like) – Initial parameter guesses.

• param_names (list of str) – Names of the parameters to apply specific logic (e.g., non-negative constraints).

Returns:

(low_bounds, high_bounds) as lists of numeric values.

Return type:

tuple

pychemelt.utils.processing.expand_temperature_list(temp_lst, signal_lst)

Expand the temperature list to match the length of the signal list.

Parameters:

• temp_lst (list) – List of temperatures

• signal_lst (list) – List of signals

Returns:

Expanded temperature list

Return type:

list

pychemelt.utils.processing.clean_conditions_labels(conditions)

Clean the conditions labels by removing unwanted characters and patterns.

Parameters:

conditions (list) – List of condition strings.

Returns:

List of cleaned condition strings.

Return type:

list

pychemelt.utils.processing.subset_signal_by_temperature(signal_lst, temp_lst, min_temp, max_temp)

Subset the signal and temperature lists based on the specified temperature range.

Parameters:

• signal_lst (list) – List of signal arrays.

• temp_lst (list) – List of temperature arrays.

• min_temp (float) – Minimum temperature for subsetting.

• max_temp (float) – Maximum temperature for subsetting.

Returns:

Tuple containing the subsetted signal and temperature lists.

Return type:

tuple

pychemelt.utils.processing.guess_Tm_from_derivative(temp_lst, deriv_lst, x1, x2)

Estimate the melting temperature (Tm) by finding the extremum of the first derivative.

Parameters:

• temp_lst (list of np.ndarray) – Temperature arrays for each dataset.

• deriv_lst (list of np.ndarray) – First derivative of the signal for each dataset.

• x1 (float) – Lower buffer from the temperature edges to exclude noise/artifacts.

• x2 (float) – Upper buffer from the temperature edges to define the baseline median window.

Returns:

Estimated Tm values for each dataset.

Return type:

list of float

pychemelt.utils.processing.estimate_signal_baseline_params(signal_lst, temp_lst, native_baseline_type, unfolded_baseline_type, window_range_native=12, window_range_unfolded=12, oligomer_number=1)

Estimate the baseline parameters for the sample

Parameters:

• signal_lst (list of np.ndarray) – List of signal arrays

• temp_lst (list of np.ndarray) – List of temperature arrays

• window_range_native (float or tuple(float, float)) – If scalar, use temperatures lower than min(temp) + window_range_native. If tuple, use only temperatures inside (low, high).

• window_range_unfolded (float or tuple(float, float)) – If scalar, use temperatures higher than max(temp) - window_range_unfolded. If tuple, use only temperatures inside (low, high).

• native_baseline_type (str) – options: ‘constant’, ‘linear’, ‘quadratic’, ‘exponential’

• unfolded_baseline_type (str) – options: ‘constant’, ‘linear’, ‘quadratic’, ‘exponential’

• oligomer_number (int) – number of subunits in the oligomer

Returns:

Lists of estimated parameters (p1Ns, p1Us, p2Ns, p2Us, p3Ns, p3Us).

Return type:

tuple

pychemelt.utils.processing.fit_local_thermal_unfolding_to_signal_lst(signal_lst, temp_lst, t_melting_init, p1_Ns, p1_Us, p2_Ns, p2_Us, p3_Ns, p3_Us, baseline_native_fx, baseline_unfolded_fx, gas_cst=0.001987)

Perform individual (local) fits for each signal curve in a list.

Parameters:

• signal_lst (list of np.ndarray) – List of signals.

• temp_lst (list of np.ndarray) – List of temperatures.

• t_melting_init (list of float) – Initial Tm guesses.

• p1_Ns (list of float) – Estimated baseline parameters for each curve.

• p1_Us (list of float) – Estimated baseline parameters for each curve.

• p2_Ns (list of float) – Estimated baseline parameters for each curve.

• p2_Us (list of float) – Estimated baseline parameters for each curve.

• p3_Ns (list of float) – Estimated baseline parameters for each curve.

• p3_Us (list of float) – Estimated baseline parameters for each curve.

• baseline_native_fx (callable) – Function to calculate the native baseline.

• baseline_unfolded_fx (callable) – Function to calculate the unfolded baseline.

• gas_cst (float, optional) – Gas constant to use in calculations (default is R_gas).

Returns:

(Tms, dHs, predicted_lst) containing fitted parameters and signal arrays.

Return type:

tuple

pychemelt.utils.processing.re_arrange_predictions(predicted_lst, n_signals, n_denaturants)

Re-arrange the flattened predictions to match the original signal list with sublists.

Parameters:

• predicted_lst (list) – Flattened list of predicted signals of length n_signals * n_denaturants.

• n_signals (int) – Number of signal types (e.g., different wavelengths).

• n_denaturants (int) – Number of denaturant concentrations or conditions per signal.

Returns:

Re-arranged list of predicted signals of length n_signals, where each element is a sublist of length n_denaturants.

Return type:

list

pychemelt.utils.processing.re_arrange_params(params, n_signals)

Re-arrange flattened parameters into a list of sublists grouped by signal.

Parameters:

• params (list or np.ndarray) – Flattened list of parameters.

• n_signals (int) – Number of signal types to group parameters by.

Returns:

Re-arranged list of parameters of length n_signals containing parameter arrays for each signal.

Return type:

list of np.ndarray

pychemelt.utils.processing.subset_data(data, max_points)

Reduces the number of data points by repeated striding until the size is below a threshold.

Parameters:

• data (np.ndarray) – Input data array to be subsetted.

• max_points (int) – The maximum number of points allowed in the resulting array.

Returns:

Subsetted data array containing every $2^n$-th point of the original.

Return type:

np.ndarray

pychemelt.utils.processing.get_colors_from_numeric_values(values, min_val, max_val, use_log_scale=False)

Map numeric values to colors in the VIRIDIS palette based on a specified range.

Parameters:

• values (list or np.ndarray) – Numeric values to map to colors.

• min_val (float) – Minimum value of the range.

• max_val (float) – Maximum value of the range.

• use_log_scale (bool, optional) – Whether to use logarithmic scaling for the values, default is True.

Returns:

List of hex color codes corresponding to the input values.

Return type:

list

pychemelt.utils.processing.combine_sequences(seq1, seq2)

Combine two sequences to generate all possible combinations of their elements.

Parameters:

• seq1 (list) – First sequence of elements.

• seq2 (list) – Second sequence of elements.

Returns:

A list of tuples, where each tuple contains one element from seq1 and one from seq2.

Return type:

list

pychemelt.utils.processing.adjust_value_to_interval(value, lower_bound, upper_bound, shift)

Verify that a value is within the specified bounds. If the value is outside the bounds, adjust it to the nearest bound. :param value: The value to be adjusted. :type value: float :param lower_bound: The lower bound of the interval. :type lower_bound: float :param upper_bound: The upper bound of the interval. :type upper_bound: float :param shift: How much to shift the value if it is outside the bounds. :type shift: float

pychemelt.utils.processing.oligomer_number(model)

Get the number of subunits in the oligomer based on the model.

Returns:

The number of subunits (2 for ‘Dimer’, 3 for ‘Trimer’, 4 for ‘Tetramer’, 1 otherwise).

Return type:

int

pychemelt.utils.processing.parse_number(s)

Parse a string as a float, handling: - European decimal (comma) - Optional thousands separators - Standard decimal point

Parameters:

s (str) – The string to parse

Return type:

float The parsed number

Raises:

ValueError If the string cannot be parsed as a float –

pychemelt.utils.processing.are_all_strings_numeric(lst)

Parameters:

lst (list of str) – List of strings to check

Returns:

True if all strings in the list are numeric (can contain digits, ‘.’, ‘-’, ‘,’), False otherwise

Return type:

bool

pychemelt.utils.processing.is_float(element)

pychemelt.utils.processing.transform_to_list(element_or_list)

Parameters:

element_or_list (bool, str, int, float, list, or numpy array) – The input element or list to be transformed into a list.

Returns:

A list containing the input element if it is not already a list, or the input itself if it is None, a numpy array, or a list.

Return type:

list or None

Raises:

ValueError – If the input is not a boolean, string, integer, float, list, numpy array

pychemelt.utils.processing.ci_dict_to_summary_df(ci_dict, percentage=0.95, energy_units_str='kcal', n_digits=3)

Convert lmfit confidence interval dictionary into a summary DataFrame.

Parameters:

• ci_dict (dict) – Dictionary containing confidence intervals for fitted parameters, typically in the format returned by lmfit.

• percentage (float, optional) – Confidence level for the intervals (default is 0.95 for 95% confidence intervals).

• energy_units_str (str, optional) – Units format for the parameters, either ‘kcal’ or ‘kJ’ (default is ‘kcal’).

Returns:

DataFrame summarizing the confidence intervals for each parameter, with columns: - Parameter: Name of the fitted parameter - Lower_CI: Lower bound of the confidence interval - Value: Best-fit value of the parameter - Upper_CI: Upper bound of the confidence interval

Return type:

pd.DataFrame

pychemelt.utils.processing.re_arrange_loo_initial_params(model, native_baseline_type, unfolded_baseline_type, i, id_start, params, low_bounds, high_bounds, nr_signals, n_corr)

pychemelt.utils.processing.find_baseline_params(params_df, mode='native')

Find the native baseline parameters in a DataFrame of fitted parameters.

Parameters:

params_df (pd.DataFrame) – DataFrame containing fitted parameters with a ‘Parameter’ column.

Returns:

For each signal, the parameters at the lowest or highest denaturant concentration, depending on the mode (‘native’ or ‘unfolded’).

Return type:

dict

pychemelt.utils.rates module

This module contains helper functions to obtain equilibrium constants Author: Osvaldo Burastero

Useful references for unfolding models:

• Rumfeldt, Jessica AO, et al. “Conformational stability and folding mechanisms of dimeric proteins.” Progress in biophysics and molecular biology 98.1 (2008): 61-84.

• Bedouelle, Hugues. “Principles and equations for measuring and interpreting protein stability: From monomer to tetramer.” Biochimie 121 (2016): 29-37.

• Mazurenko, Stanislav, et al. “Exploration of protein unfolding by modelling calorimetry data from reheating.” Scientific reports 7.1 (2017): 16321.

All thermodynamic parameters are used in kcal mol units

Unfolding functions for monomers have an argument called ‘extra_arg’ that is not used. This is because unfolding functions for oligomers require the protein concentration in that position

pychemelt.utils.rates.eq_constant_thermo(T, DH1, T1, Cp, gas_cst=0.001987)

T1 is the temperature at which ΔG(T) = 0 ΔH1, the variation of enthalpy between the two considered states at T1 Cp the variation of calorific capacity between the two states

Parameters:

• T (array-like) – Temperature (Kelvin)

• DH1 (float) – Variation of enthalpy between the two considered states at T1 (kcal/mol)

• T1 (float) – Temperature at which the equilibrium constant equals one (Kelvin)

• Cp (float) – Variation of heat capacity between the two states (kcal/mol/K)

Returns:

Equilibrium constant at the given temperature

Return type:

numpy.ndarray

pychemelt.utils.rates.eq_constant_termochem(T, D, DHm, Tm, Cp0, m0, m1, gas_cst=0.001987)

Ref: Louise Hamborg et al., 2020. Global analysis of protein stability by temperature and chemical denaturation

Parameters:

• T (array-like) – Temperature (Kelvin only!)

• D (float) – Denaturant concentration (M)

• DHm (float) – Enthalpy change at Tm (kcal/mol)

• Tm (float) – Melting temperature where ΔG = 0 (Kelvin only!)

• Cp0 (float) – Heat capacity change (kcal/mol/K)

• m0 (float) – m-value at the reference temperature

• m1 (float) – Temperature dependence of the m-value

Returns:

Equilibrium constant at a certain temperature and denaturant agent concentration

Return type:

numpy.ndarray

pychemelt.utils.signals module

This module contains helper functions to obtain the signal, given certain parameters Author: Osvaldo Burastero

Note: One could move dT outside the signal functions but the speedup was not significant.

pychemelt.utils.signals.signal_two_state_tc_unfolding(T, D, DHm, Tm, Cp0, m0, m1, p1_N, p2_N, p3_N, p4_N, p1_U, p2_U, p3_U, p4_U, baseline_N_fx, baseline_U_fx, gas_cst=0.001987, extra_arg=None)

Ref: Louise Hamborg et al., 2020. Global analysis of protein stability by temperature and chemical denaturation

Parameters:

• T (array-like) – Temperature in Kelvin units

• D (array-like) – Denaturant agent concentration

• DHm (float) – Variation of enthalpy between the two considered states at Tm

• Tm (float) – Temperature at which the equilibrium constant equals one, in Kelvin units

• Cp0 (float) – Variation of calorific capacity between the two states

• m0 (float) – m-value at the reference temperature (Tref)

• m1 (float) – Variation of m-value with temperature

• p1_N (float) – parameters describing the native-state baseline

• p2_N (float) – parameters describing the native-state baseline

• p3_N (float) – parameters describing the native-state baseline

• p4_N (float) – parameters describing the native-state baseline

• p1_U (float) – parameters describing the unfolded-state baseline

• p2_U (float) – parameters describing the unfolded-state baseline

• p3_U (float) – parameters describing the unfolded-state baseline

• p4_U (float) – parameters describing the unfolded-state baseline

• baseline_N_fx (function) – for the native-state baseline

• baseline_U_fx (function) – for the unfolded-state baseline

• extra_arg (None, optional) – Not used but present for API compatibility with oligomeric models

Returns:

Signal at the given temperatures and denaturant agent concentration, given the parameters

Return type:

numpy.ndarray

pychemelt.utils.signals.signal_two_state_t_unfolding(T, Tm, dHm, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, Cp=0, gas_cst=0.001987, extra_arg=None)

Two-state temperature unfolding (monomer).

Parameters:

• T (array-like) – Temperature

• Tm (float) – Temperature at which the equilibrium constant equals one

• dHm (float) – Variation of enthalpy between the two considered states at Tm

• p1_N (float) – baseline parameters for the native-state baseline

• p2_N (float) – baseline parameters for the native-state baseline

• p3_N (float) – baseline parameters for the native-state baseline

• p1_U (float) – baseline parameters for the unfolded-state baseline

• p2_U (float) – baseline parameters for the unfolded-state baseline

• p3_U (float) – baseline parameters for the unfolded-state baseline

• baseline_N_fx (callable) – function to calculate the baseline for the native state

• baseline_U_fx (callable) – function to calculate the baseline for the unfolded state

• Cp (float, optional) – Variation of heat capacity between the two states (default: 0)

• extra_arg (None, optional) – Not used but present for compatibility

Returns:

Signal at the given temperatures, given the parameters

Return type:

numpy.ndarray

pychemelt.utils.signals.two_state_thermal_unfold_curve(T, C, Tm, dHm, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, Cp=0, gas_cst=0.001987)

Two-state temperature unfolding (monomer). N ⇔ U

Parameters:

• T (array-like) – Temperature

• C (array-like) – Oligomer sample concentration - only for compatibility with oligomeric models, not used in the monomeric model

• Tm (float) – Temperature at which the equilibrium constant equals one

• dHm (float) – Variation of enthalpy between the two considered states at Tm

• p1_N (float) – baseline parameters for the native-state baseline

• p2_N (float) – baseline parameters for the native-state baseline

• p3_N (float) – baseline parameters for the native-state baseline

• p1_U (float) – baseline parameters for the unfolded-state baseline

• p2_U (float) – baseline parameters for the unfolded-state baseline

• p3_U (float) – baseline parameters for the unfolded-state baseline

• baseline_N_fx (callable) – function to calculate the baseline for the native state

• baseline_U_fx (callable) – function to calculate the baseline for the unfolded state

• Cp (float, optional) – Variation of heat capacity between the two states (default: 0)

Returns:

Signal at the given temperatures, given the parameters

Return type:

numpy.ndarray

pychemelt.utils.signals.two_state_thermal_unfold_curve_dimer(T, C, Tm, dHm, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, Cp=0, gas_cst=0.001987)

Two-state temperature unfolding (dimer). N2 ⇔ 2U C is the total concentration (M) of the protein in dimer equivalent.

Parameters:

• T (array-like) – Temperature

• C (array-like) – Oligomer sample concentration

• Tm (float) – Temperature at which the equilibrium constant equals one

• dHm (float) – Variation of enthalpy between the two considered states at Tm

• p1_N (float) – baseline parameters for the native-state baseline

• p2_N (float) – baseline parameters for the native-state baseline

• p3_N (float) – baseline parameters for the native-state baseline

• p1_U (float) – baseline parameters for the unfolded-state baseline

• p2_U (float) – baseline parameters for the unfolded-state baseline

• p3_U (float) – baseline parameters for the unfolded-state baseline

• baseline_N_fx (callable) – function to calculate the baseline for the native state

• baseline_U_fx (callable) – function to calculate the baseline for the unfolded state

• Cp (float, optional) – Variation of heat capacity between the two states (default: 0)

Returns:

Signal at the given temperatures, given the parameters

Return type:

numpy.ndarray

Notes

C is the total concentration (M) of the protein in dimer equivalent.

pychemelt.utils.signals.two_state_thermal_unfold_curve_trimer(T, C, Tm, dHm, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, Cp=0, gas_cst=0.001987)

Two-state temperature unfolding (trimer). N3 ⇔ 3U

Parameters:

• T (array-like) – Temperature

• C (array-like) – Oligomer sample concentration

• Tm (float) – Temperature at which the equilibrium constant equals one

• dHm (float) – Variation of enthalpy between the two considered states at Tm

• p1_N (float) – baseline parameters for the native-state baseline

• p2_N (float) – baseline parameters for the native-state baseline

• p3_N (float) – baseline parameters for the native-state baseline

• p1_U (float) – baseline parameters for the unfolded-state baseline

• p2_U (float) – baseline parameters for the unfolded-state baseline

• p3_U (float) – baseline parameters for the unfolded-state baseline

• baseline_N_fx (callable) – function to calculate the baseline for the native state

• baseline_U_fx (callable) – function to calculate the baseline for the unfolded state

• Cp (float, optional) – Variation of heat capacity between the two states (default: 0)

Returns:

Signal at the given temperatures, given the parameters

Return type:

numpy.ndarray

Notes

C is the total concentration (M) of the protein in trimer equivalent.

pychemelt.utils.signals.two_state_thermal_unfold_curve_tetramer(T, C, Tm, dHm, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, Cp=0, gas_cst=0.001987, extra_arg=None)

Two-state temperature unfolding (tetramer). N4 ⇔ 4U

Parameters:

• T (array-like) – Temperature

• C (array-like) – Oligomer sample concentration

• Tm (float) – Temperature at which the equilibrium constant equals one

• dHm (float) – Variation of enthalpy between the two considered states at Tm

• p1_N (float) – baseline parameters for the native-state baseline

• p2_N (float) – baseline parameters for the native-state baseline

• p3_N (float) – baseline parameters for the native-state baseline

• p1_U (float) – baseline parameters for the unfolded-state baseline

• p2_U (float) – baseline parameters for the unfolded-state baseline

• p3_U (float) – baseline parameters for the unfolded-state baseline

• baseline_N_fx (callable) – function to calculate the baseline for the native state

• baseline_U_fx (callable) – function to calculate the baseline for the unfolded state

• Cp (float, optional) – Variation of heat capacity between the two states (default: 0)

Returns:

Signal at the given temperatures, given the parameters

Return type:

numpy.ndarray

Notes

C is the total concentration (M) of the protein in tetramer equivalent.

pychemelt.utils.signals.unfolding_curve_monomer_monomeric_intermediate(T, C, T1, DH1, T2, DH2, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, bI, Cp1=0, CpTh=0, gas_cst=0.001987)

Three states reversible unfolding N <-> I <-> U

pychemelt.utils.signals.unfolding_curve_dimer_monomeric_intermediate(T, C, T1, DH1, T2, DH2, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, bI, Cp1=0, CpTh=0, gas_cst=0.001987)

N2 ⇔ 2Ι ⇔ 2U Three-state unfolding with a monomeric intermediate C = concentration in dimer equivalent CpTotal = Cp1 + 2*Cp2

pychemelt.utils.signals.unfolding_curve_trimer_monomeric_intermediate(T, C, T1, DH1, T2, DH2, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, bI, Cp1=0, CpTh=0, gas_cst=0.001987)

N3 ⇔ 3Ι ⇔ 3U Three-state unfolding with a monomeric intermediate C = concentration of the trimer equivalent

pychemelt.utils.signals.unfolding_curve_tetramer_monomeric_intermediate(T, C, T1, DH1, T2, DH2, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, bI, Cp1=0, CpTh=0, gas_cst=0.001987)

N4 ⇔ 4Ι ⇔ 4U Three-state unfolding with a monomeric intermediate C = concentration of the tetramermer equivalent

pychemelt.utils.signals.unfolding_curve_trimer_trimeric_intermediate(T, C, T1, DH1, T2, DH2, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, bI, Cp1=0, CpTh=0, gas_cst=0.001987)

N3 ⇔ Ι3 ⇔ 3U Three-state unfolding with a trimeric intermediate C = concentration of the trimer equivalent

pychemelt.utils.signals.unfolding_curve_dimer_dimeric_intermediate(T, C, T1, DH1, T2, DH2, p1_N, p2_N, p3_N, p1_U, p2_U, p3_U, baseline_N_fx, baseline_U_fx, bI, Cp1=0, CpTh=0, gas_cst=0.001987)

N2 ⇔ Ι2 ⇔ 2U Three-state unfolding with a monomeric intermediate C = molar concentration in dimer equivalent CpTotal = Cp1 + Cp2

pychemelt.utils.signals.map_two_state_model_to_signal_fx(model)

Maps the model string to the signal type

Parameters:

model (str,) – string representation of model type.

Returns:

signal function corresponding to the string

Return type:

function

pychemelt.utils.signals.map_three_state_model_to_signal_fx(model)

pychemelt.utils.svd module

Module containing functions to perform Singular Value Decomposition (SVD) and Principal Component Analysis (PCA) on spectral data, along with utilities for manipulating basis spectra and coefficients.

Author: Osvaldo Burastero

pychemelt.utils.svd.apply_svd(X)

Perform Singular Value Decomposition (SVD) on the input data matrix X.

Parameters:

X (numpy array of shape (n_wavelengths, n_measurements)) – The input data matrix to decompose.

Returns:

• explained_variance (numpy array) – The cumulative explained variance for each component.

• basis_spectra (numpy array) – The left singular vectors (U matrix) representing the basis spectra.

• coefficients (numpy array) – The coefficients associated with each basis spectrum.

pychemelt.utils.svd.filter_basis_spectra(explained_variance, basis_spectra_all, coefficients_all, explained_variance_threshold=99)

Filter the basis spectra and coefficients based on the explained variance threshold :param explained_variance: The cumulative explained variance for each component. :type explained_variance: numpy array :param basis_spectra_all: The left singular vectors (U matrix) representing the basis spectra. :type basis_spectra_all: numpy array :param coefficients_all: The coefficients associated with each basis spectrum. :type coefficients_all: numpy array :param explained_variance_threshold: The threshold for explained variance to filter components. Default is 99. :type explained_variance_threshold: float, optional

Returns:

• basis_spectra (numpy array) – The filtered basis spectra.

• coefficients (numpy array) – The filtered coefficients.

• k (int) – The number of components that meet the explained variance threshold.

pychemelt.utils.svd.align_basis_spectra_and_coefficients(X, basis_spectra, coefficients)

Align the basis spectra peaks to the original data :param X: The input data matrix. :type X: numpy array of shape (n_samples, n_features) :param basis_spectra: The basis spectra obtained from SVD. :type basis_spectra: numpy array :param coefficients: The coefficients associated with each basis spectrum. :type coefficients: numpy array

Returns:

• basis_spectra (numpy array) – The aligned basis spectra.

• coefficients (numpy array) – The adjusted coefficients.

pychemelt.utils.svd.angle_from_cathets(adjacent_leg, opposite_leg)

Calculate the angle between the hypotenuse and the adjacent leg of a right triangle. :param adjacent_leg: Length of the adjacent leg. :type adjacent_leg: float :param opposite_leg: Length of the opposite leg. :type opposite_leg: float

Returns:

angle_in_radians – Angle in radians between the hypotenuse and the adjacent leg.

Return type:

float

pychemelt.utils.svd.get_2d_counterclockwise_rot_matrix(angle_in_radians)

Obtain the rotation matrix for a 2d coordinates system using a counterclockwise direction :param angle_in_radians: Angle in radians for the rotation. :type angle_in_radians: float

Returns:

rotM – 2x2 rotation matrix.

Return type:

numpy array

pychemelt.utils.svd.get_3d_counterclockwise_rot_matrix_around_z_axis(angle_in_radians)

Obtain the rotation matrix for a 3d coordinates system around the z axis using a counterclockwise direction :param angle_in_radians: Angle in radians for the rotation. :type angle_in_radians: float

Returns:

rotM – 3x3 rotation matrix.

Return type:

numpy array

pychemelt.utils.svd.get_3d_clockwise_rot_matrix_around_y_axis(angle_in_radians)

Obtain the rotation matrix for a 3d coordinates system around the y axis using a clockwise direction :param angle_in_radians: Angle in radians for the rotation. :type angle_in_radians: float

Returns:

rotM – 3x3 rotation matrix.

Return type:

numpy array

pychemelt.utils.svd.rotate_two_basis_spectra(X, basis_spectra, pca_based=False)

Create a new basis spectra using a linear combination of the first and second basis spectra

Parameters:

• X (numpy array) – The raw data matrix of size n*m, where ‘n’ is the number of measured wavelengths and ‘m’ is the number of acquired spectra.

• basis_spectra (numpy array) – The matrix containing the set of basis spectra.

• pca_based (bool, optional) – Boolean to decide if we need to center the matrix X. Default is False.

Returns:

• basis_spectra_new (numpy array) – The new set of basis spectra.

• coefficients (numpy array) – The new set of associated coefficients.

pychemelt.utils.svd.rotate_three_basis_spectra(X, basis_spectra, pca_based=False)

Create a new basis spectra using a linear combination from the first, second and third basis spectra

Parameters:

• X (numpy array) – The raw data matrix of size n*m, where ‘n’ is the number of measured wavelengths and ‘m’ is the number of acquired spectra.

• basis_spectra (numpy array) – The matrix containing the set of basis spectra.

• pca_based (bool, optional) – Boolean to decide if we need to center the matrix X. Default is False.

Returns:

• basis_spectra_new (numpy array) – The new set of basis spectra.

• coefficients_subset (numpy array) – The new set of associated coefficients.

pychemelt.utils.svd.reconstruct_spectra(basis_spectra, coefficients, X=None, pca_based=False)

Reconstruct the original spectra based on the set of basis spectra and the associated coefficients

Parameters:

• basis_spectra (numpy array) – The matrix containing the set of basis spectra.

• coefficients (numpy array) – The associated coefficients of each basis spectrum.

• X (numpy array, optional) – Only used if pca_based equals TRUE! X is the raw data matrix of size n*m, where ‘n’ is the number of measured wavelengths and ‘m’ is the number of acquired spectra.

• pca_based (bool, optional) – Boolean to decide if we need to extract the mean from the the X raw data matrix. Default is False.

• Returns

• -------

• fitted (numpy array) – The reconstructed matrix which should be close the original raw data.

pychemelt.utils.svd.explained_variance_from_orthogonal_vectors(vectors, coefficients, total_variance)

Useful to get the percentage of variance, not in the coordinate space provided by PCA/SVD, but against a different set of (rotated) vectors.

Parameters:

• vectors (numpy array) – The set of orthogonal vectors.

• coefficients (numpy array) – The associated coefficients of each orthogonal vector.

• total_variance (float) – The total variance of the original data (mean subtracted if we performed PCA…).

Returns:

explained_variance – The amount of explained variance by each orthogonal vector.

Return type:

list

pychemelt.utils.svd.apply_pca(X)

Perform Principal Component Analysis (PCA) on the input data matrix X. :param X: The input data matrix to decompose. :type X: numpy array of shape (n_wavelengths, n_measurements)

Returns:

• cum_sum_eigenvalues (numpy array) – The cumulative explained variance for each principal component.

• principal_components (numpy array) – The principal components (eigenvectors) representing the basis spectra.

• coefficients (numpy array) – The coefficients associated with each principal component.

pychemelt.utils.svd.recalc_explained_variance(basis_spectra, coefficients, X, pca_based=False)

Recalculate the explained variance of a set of basis spectra and associated coefficients :param basis_spectra: The basis spectra. :type basis_spectra: numpy array :param coefficients: The associated coefficients of each basis spectrum. :type coefficients: numpy array :param X: The raw data matrix of size n*m, where ‘n’ is the number of measured wavelengths

and ‘m’ is the number of acquired spectra.

Parameters:

pca_based (bool, optional) – Boolean to decide if we need to center the matrix X. Default is False.

Returns:

explained_variance – The cumulative explained variance for each component.

Return type:

numpy array