pykingenie.utils package

Submodules

pykingenie.utils.fitting_general module

pykingenie.utils.fitting_general.fit_single_exponential(y, t, min_log_k=-5, max_log_k=5, log_k_points=50)

Fit a single exponential to a signal.

Parameters:

• y (np.ndarray) – Signal values.

• t (np.ndarray) – Time values.

• min_log_k (float, optional) – Minimum logarithmic value for k_obs initial estimation, default is -5.

• max_log_k (float, optional) – Maximum logarithmic value for k_obs initial estimation, default is 5.

• log_k_points (int, optional) – Number of points in the logarithmic scale for k_obs initial estimation, default is 50.

Returns:

• np.ndarray – Fitted parameters (a0, a1, k_obs).

• np.ndarray – Covariance matrix of the fitted parameters.

• np.ndarray – Fitted y values.

pykingenie.utils.fitting_general.fit_double_exponential(y, t, min_log_k=-4, max_log_k=4, log_k_points=22)

Fit a double exponential to a signal.

Parameters:

• y (np.ndarray) – Signal values.

• t (np.ndarray) – Time values.

• min_log_k (float, optional) – Minimum logarithmic value for k_obs initial estimation, default is -4.

• max_log_k (float, optional) – Maximum logarithmic value for k_obs initial estimation, default is 4.

• log_k_points (int, optional) – Number of points in the logarithmic scale for k_obs initial estimation, default is 22.

Returns:

• np.ndarray – Fitted parameters (a0, a1, k_obs1, a2, k_obs2).

• np.ndarray – Covariance matrix of the fitted parameters.

• np.ndarray – Fitted y values.

pykingenie.utils.fitting_general.re_fit(fit, cov, fit_vals, fit_fx, low_bounds, high_bounds, times, **kwargs)

Re-fit data by evaluating the difference between fitted parameters and bounds.

If the difference is less than 2 percent, the bounds are relaxed by a factor of 10 and the fitting is repeated.

Parameters:

• fit (list) – Fitted parameters.

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

• fit_vals (list) – Fitted values for each signal, same dimensions as signal_lst.

• fit_fx (callable) – Function to fit the data - returns fit, cov, fit_vals.

• low_bounds (list) – Lower bounds for the parameters.

• high_bounds (list) – Upper bounds for the parameters.

• times (int) – Number of times to re-fit the data.

• **kwargs – Additional arguments to pass to the fitting function.

Returns:

• np.ndarray – Fitted parameters after re-fitting.

• np.ndarray – Covariance matrix of the fitted parameters after re-fitting.

• list – Fitted values for each signal after re-fitting.

• np.ndarray – Lower bounds for the parameters after re-fitting.

• np.ndarray – Upper bounds for the parameters after re-fitting.

pykingenie.utils.fitting_general.re_fit_2(fit, cov, fit_vals_a, fit_vals_b, fit_fx, low_bounds, high_bounds, times, **kwargs)

Re-fit data for two signals by evaluating the difference between fitted parameters and bounds.

If the difference is less than 2 percent, the bounds are relaxed by a factor of 10 and the fitting is repeated. This function is used for fitting two signals at once, e.g. fitting association and dissociation signals simultaneously.

Parameters:

• fit (list) – Fitted parameters.

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

• fit_vals_a (list) – Fitted values for the first set of signals.

• fit_vals_b (list) – Fitted values for the second set of signals.

• fit_fx (callable) – Function to fit the data - returns fit, cov, fit_vals_a, fit_vals_b.

• low_bounds (list) – Lower bounds for the parameters.

• high_bounds (list) – Upper bounds for the parameters.

• times (int) – Number of times to re-fit the data.

• **kwargs – Additional arguments to pass to the fitting function.

Returns:

• np.ndarray – Fitted parameters after re-fitting.

• np.ndarray – Covariance matrix of the fitted parameters after re-fitting.

• list – Fitted values for the first set of signals after re-fitting.

• list – Fitted values for the second set of signals after re-fitting.

• np.ndarray – Lower bounds for the parameters after re-fitting.

• np.ndarray – Upper bounds for the parameters after re-fitting.

pykingenie.utils.fitting_solution module

pykingenie.utils.fitting_solution.fit_one_site_solution(signal_lst, time_lst, ligand_conc_lst, protein_conc_lst, initial_parameters, low_bounds, high_bounds, fit_signal_E=False, fit_signal_S=False, fit_signal_ES=True, fixed_t0=True, fixed_Kd=False, Kd_value=None, fixed_koff=False, koff_value=None)

Global fit to association and dissociation traces - one-to-one binding model.

Parameters:

• signal_lst (list) – List of signals. We assume initial values as follows: E = E_tot, S = S_tot, ES = 0.

• time_lst (list) – List of time points for the association signals.

• ligand_conc_lst (list) – List of ligand concentrations, one per element in signal_lst.

• protein_conc_lst (list) – List of protein concentrations, one per element in signal_lst.

• initial_parameters (list) – Initial parameters for the fit.

• low_bounds (list) – Lower bounds for the fit parameters.

• high_bounds (list) – Upper bounds for the fit parameters.

• fit_signal_E (bool, optional) – If True, fit the signal of the free protein, default is False.

• fit_signal_S (bool, optional) – If True, fit the signal of the free ligand, default is False.

• fit_signal_ES (bool, optional) – If True, fit the signal of the complex, default is True.

• fixed_t0 (bool, optional) – If True, the initial time point is zero, default is True.

• fixed_Kd (bool, optional) – If True, the equilibrium dissociation constant is fixed, default is False.

• Kd_value (float, optional) – Value of the equilibrium dissociation constant if fixed_Kd is True.

• fixed_koff (bool, optional) – If True, the dissociation rate constant is fixed, default is False.

• koff_value (float, optional) – Value of the dissociation rate constant if fixed_koff is True.

Returns:

• list – Fitted parameters.

• np.ndarray – Covariance matrix of the fitted parameters.

• list – Fitted values for each signal, same dimensions as signal_lst.

• list – Names of the fitted parameters.

pykingenie.utils.fitting_solution.fit_induced_fit_solution(signal_lst, time_lst, ligand_conc_lst, protein_conc_lst, initial_parameters, low_bounds, high_bounds, fit_signal_E=False, fit_signal_S=False, fit_signal_ES=True, ESint_equals_ES=True, fixed_t0=True, fixed_kon=False, kon_value=None, fixed_koff=False, koff_value=None, fixed_kc=False, kc_value=None, fixed_krev=False, krev_value=None, max_nfev=None)

Global fit to association and dissociation traces - one-to-one binding model with induced fit.

Parameters:

• signal_lst (list) – List of signals. We assume initial values as follows: E = E_tot, S = S_tot, ES = 0, ESint = 0.

• time_lst (list) – List of time points for the association signals.

• ligand_conc_lst (list) – List of ligand concentrations, one per element in signal_lst.

• protein_conc_lst (list) – List of protein concentrations, one per element in signal_lst.

• initial_parameters (list) – Initial parameters for the fit.

• low_bounds (list) – Lower bounds for the fit parameters.

• high_bounds (list) – Upper bounds for the fit parameters.

• fit_signal_E (bool, optional) – If True, fit the signal of the free protein, default is False.

• fit_signal_S (bool, optional) – If True, fit the signal of the free ligand, default is False.

• fit_signal_ES (bool, optional) – If True, fit the signal of the complex, default is True.

• ESint_equals_ES (bool, optional) – If True, the signal of the intermediate complex is equal to the signal of the trapped complex, default is True.

• fixed_t0 (bool, optional) – If True, the initial time point is zero, default is True.

• fixed_kon (bool, optional) – If True, the association rate constant is fixed, default is False.

• kon_value (float, optional) – Value of the association rate constant if fixed_kon is True.

• fixed_koff (bool, optional) – If True, the dissociation rate constant is fixed, default is False.

• koff_value (float, optional) – Value of the dissociation rate constant if fixed_koff is True.

• fixed_kc (bool, optional) – If True, the induced fit rate constant is fixed, default is False.

• kc_value (float, optional) – Value of the induced fit rate constant if fixed_kc is True.

• fixed_krev (bool, optional) – If True, the reverse induced fit rate constant is fixed, default is False.

• krev_value (float, optional) – Value of the reverse induced fit rate constant if fixed_krev is True.

• max_nfev (int, optional) – Maximum number of function evaluations for the fit.

Returns:

• list – Fitted parameters.

• np.ndarray – Covariance matrix of the fitted parameters.

• list – Fitted values for each signal, same dimensions as signal_lst.

• list – Names of the fitted parameters.

Notes

The initial_parameters are given in the following order:

• signal_E if fit_signal_E (signal of the free protein)

• signal_S if fit_signal_S (signal of the free ligand)

• signal_ES if fit_signal_ES (signal of the trapped complex)

• signal_ESint if fit_signal_ES and not ESint_equals_ES (signal of the intermediate complex) if ESint_equals_ES is True, then the trapped complex signal is used for both ES and ESint

• k_on if not fixed_kon (association rate constant)

• k_off if not fixed_koff (dissociation rate constant)

• k_c if not fixed_kc (induced fit rate constant)

• k_rev if not fixed_krev (reverse induced fit rate constant)

• t0_1 if not fixed_t0 (initial time point for the first signal array, default is 0)

• t0_2 if not fixed_t0 (initial time point for the second signal array, default is 0)

pykingenie.utils.fitting_solution.find_initial_parameters_induced_fit_solution(signal_lst, time_lst, ligand_conc_lst, protein_conc_lst, fit_signal_E=False, fit_signal_S=False, fit_signal_ES=True, ESint_equals_ES=True, fixed_t0=True, np_linspace_low=-2, np_linspace_high=2, np_linspace_num=5)

Find initial parameters for the global fit to association and dissociation traces - one-to-one binding model with induced fit.

Heuristic algorithm to explore a range of fixed kc and krev values, and fit kon and koff. This function is used to find the initial parameters for the fit_induced_fit_solution function.

Parameters:

• signal_lst (list) – List of signals. We assume initial values as follows: E = E_tot, S = S_tot, ES = 0, ESint = 0.

• time_lst (list) – List of time points for the association signals.

• ligand_conc_lst (list) – List of ligand concentrations, one per element in signal_lst.

• protein_conc_lst (list) – List of protein concentrations, one per element in signal_lst.

• fit_signal_E (bool, optional) – If True, fit the signal of the free protein, default is False.

• fit_signal_S (bool, optional) – If True, fit the signal of the free ligand, default is False.

• fit_signal_ES (bool, optional) – If True, fit the signal of the complex, default is True.

• ESint_equals_ES (bool, optional) – If True, the signal of the intermediate complex is equal to the signal of the trapped complex, default is True.

• fixed_t0 (bool, optional) – If True, the initial time point is zero, default is True.

• np_linspace_low (float, optional) – Lower bound for the logarithmic space to sample kc and krev, default is -2.

• np_linspace_high (float, optional) – Upper bound for the logarithmic space to sample kc and krev, default is 2.

• np_linspace_num (int, optional) – Number of points to sample in the logarithmic space, default is 5.

Returns:

Best initial parameters found by the heuristic algorithm.

Return type:

np.ndarray

pykingenie.utils.fitting_surface module

pykingenie.utils.fitting_surface.guess_initial_signal(assoc_time_lst, assoc_signal_lst, time_limit=30)

Guess the initial signal for each signal in the list by fitting single exponentials.

Used only for the one-to-one binding model in case one of the steps is not present.

Parameters:

• assoc_time_lst (list) – List of association time arrays.

• assoc_signal_lst (list) – List of association signal arrays.

• time_limit (float, optional) – Time limit to consider for the fit, default is 30 seconds.

Returns:

List of initial signals for each association signal.

Return type:

list

pykingenie.utils.fitting_surface.fit_steady_state_one_site(signal_lst, ligand_lst, initial_parameters, low_bounds, high_bounds, fixed_Kd=False, Kd_value=None)

Fit a one-site binding model to a set of steady state signals.

Parameters:

• signal_lst (list) – List of signals to fit, each signal is a numpy array.

• ligand_lst (list) – List of ligand concentrations, each concentration is a numpy array.

• initial_parameters (list) – Initial guess for the parameters.

• low_bounds (list) – Lower bounds for the parameters.

• high_bounds (list) – Upper bounds for the parameters.

• fixed_Kd (bool, optional) – If True, Kd is fixed to Kd_value, default is False.

• Kd_value (float, optional) – Value of Kd to use if fixed_Kd is True.

Returns:

• list – Fitted parameters.

• np.ndarray – Covariance matrix of the fitted parameters.

• list – Fitted values for each signal, same dimensions as signal_lst.

pykingenie.utils.fitting_surface.steady_state_one_site_asymmetric_ci95(kd_estimated, signal_lst, ligand_lst, initial_parameters, low_bounds, high_bounds, rss_desired)

Calculate the asymmetric confidence interval for the steady-state signal.

Parameters:

• kd_estimated (float) – Estimated Kd value.

• signal_lst (list) – List of signals to fit, each signal is a numpy array.

• ligand_lst (list) – List of ligand concentrations, each concentration is a numpy array.

• initial_parameters (list) – Initial guess for the parameters (without the Kd!).

• low_bounds (list) – Lower bounds for the parameters (without the Kd!).

• high_bounds (list) – Upper bounds for the parameters (without the Kd!).

• rss_desired (float) – Maximum residual sum of squares.

Returns:

95% asymmetric confidence interval for the Kd value [lower_bound, upper_bound].

Return type:

np.ndarray

pykingenie.utils.fitting_surface.fit_one_site_association(signal_lst, time_lst, analyte_conc_lst, initial_parameters, low_bounds, high_bounds, smax_idx=None, shared_smax=False, fixed_t0=True, fixed_Kd=False, Kd_value=None, fixed_koff=False, koff_value=None)

Global fit to a list of association traces - one-to-one binding model.

Parameters:

• signal_lst (list) – List of signals to fit, each signal is a numpy array.

• time_lst (list) – List of time arrays.

• analyte_conc_lst (list) – List of analyte concentrations, each element is a numpy array.

• initial_parameters (list) – Initial guess for the parameters.

• low_bounds (list) – Lower bounds for the parameters.

• high_bounds (list) – Upper bounds for the parameters.

• smax_idx (list, optional) – List of indices for the s_max parameters, used if shared_smax is True.

• shared_smax (bool, optional) – If True, the s_max parameters are shared between the signals, default is False.

• fixed_t0 (bool, optional) – If True, t0 is fixed to 0, otherwise we fit it, default is True.

• fixed_Kd (bool, optional) – If True, Kd is fixed to Kd_value, default is False.

• Kd_value (float, optional) – Value of Kd to use if fixed_Kd is True.

• fixed_koff (bool, optional) – If True, koff is fixed to koff_value, default is False.

• koff_value (float, optional) – Value of koff to use if fixed_koff is True.

Returns:

• list – Fitted parameters.

• np.ndarray – Covariance matrix of the fitted parameters.

• list – Fitted values for each signal, same dimensions as signal_lst.

pykingenie.utils.fitting_surface.fit_one_site_dissociation(signal_lst, time_lst, initial_parameters, low_bounds, high_bounds, fixed_t0=True, fixed_koff=False, koff_value=None, fit_s0=True)

Global fit to a list of dissociation traces - one-to-one binding model.

Parameters:

• signal_lst (list) – List of signals to fit, each signal is a numpy array.

• time_lst (list) – List of time arrays.

• initial_parameters (list) – Initial guess for the parameters.

• low_bounds (list) – Lower bounds for the parameters.

• high_bounds (list) – Upper bounds for the parameters.

• fixed_t0 (bool, optional) – If True, t0 is fixed to 0, otherwise we fit it, default is True.

• fixed_koff (bool, optional) – If True, koff is fixed to koff_value, default is False.

• koff_value (float, optional) – Value of koff to use if fixed_koff is True.

• fit_s0 (bool, optional) – If True, s0 is fitted, otherwise it is fixed to the first value of the signal, default is True.

Returns:

• list – Fitted parameters.

• np.ndarray – Covariance matrix of the fitted parameters.

• list – Fitted values for each signal, same dimensions as signal_lst.

pykingenie.utils.fitting_surface.fit_one_site_assoc_and_disso(assoc_signal_lst, assoc_time_lst, analyte_conc_lst, disso_signal_lst, disso_time_lst, initial_parameters, low_bounds, high_bounds, smax_idx=None, shared_smax=False, fixed_t0=True, fixed_Kd=False, Kd_value=None, fixed_koff=False, koff_value=None)

Global fit to a set of association and dissociation traces - one-to-one binding model.

Parameters:

• assoc_signal_lst (list) – List of association signals to fit, each signal is a numpy array.

• assoc_time_lst (list) – List of association time arrays.

• analyte_conc_lst (list) – List of analyte concentrations, each element is a numpy array.

• disso_signal_lst (list) – List of dissociation signals to fit, each signal is a numpy array.

• disso_time_lst (list) – List of dissociation time arrays.

• initial_parameters (list) – Initial guess for the parameters.

• low_bounds (list) – Lower bounds for the parameters.

• high_bounds (list) – Upper bounds for the parameters.

• smax_idx (list, optional) – List of indices for the s_max parameters, used if shared_smax is True.

• shared_smax (bool, optional) – If True, the s_max parameters are shared between traces, default is False.

• fixed_t0 (bool, optional) – If True, t0 is fixed to 0, otherwise we fit it, default is True.

• fixed_Kd (bool, optional) – If True, Kd is fixed to Kd_value, default is False.

• Kd_value (float, optional) – Value of Kd to use if fixed_Kd is True.

• fixed_koff (bool, optional) – If True, koff is fixed to koff_value, default is False.

• koff_value (float, optional) – Value of koff to use if fixed_koff is True.

Returns:

• list – Fitted parameters.

• np.ndarray – Covariance matrix of the fitted parameters.

• list – Fitted values for each association signal, same dimensions as assoc_signal_lst.

• list – Fitted values for each dissociation signal, same dimensions as disso_signal_lst.

pykingenie.utils.fitting_surface.fit_induced_fit_sites_assoc_and_disso(assoc_signal_lst, assoc_time_lst, analyte_conc_lst, disso_signal_lst, disso_time_lst, initial_parameters, low_bounds, high_bounds, smax_idx=None, shared_smax=False, fixed_t0=True, fixed_kon1=False, kon1_value=None, fixed_koff1=False, koff1_value=None, fixed_kon2=False, kon2_value=None, fixed_koff2=False, koff2_value=None, max_nfev=None)

Global fit to association and dissociation traces - one-to-one binding model with induced fit.

Parameters:

• assoc_signal_lst (list) – List of association signals to fit, each signal is a numpy array.

• assoc_time_lst (list) – List of association time arrays.

• analyte_conc_lst (list) – List of analyte concentrations, each element is a numpy array.

• disso_signal_lst (list) – List of dissociation signals to fit, each signal is a numpy array.

• disso_time_lst (list) – List of dissociation time arrays.

• initial_parameters (list) – Initial guess for the parameters.

• low_bounds (list) – Lower bounds for the parameters.

• high_bounds (list) – Upper bounds for the parameters.

• smax_idx (list, optional) – List of indices for the s_max parameters, used if shared_smax is True.

• shared_smax (bool, optional) – If True, the s_max parameters are shared between traces, default is False.

• fixed_t0 (bool, optional) – If True, t0 is fixed to 0, otherwise we fit it, default is True.

• fixed_kon1 (bool, optional) – If True, kon1 is fixed to kon1_value, default is False.

• kon1_value (float, optional) – Value of kon1 to use if fixed_kon1 is True.

• fixed_koff1 (bool, optional) – If True, koff1 is fixed to koff1_value, default is False.

• koff1_value (float, optional) – Value of koff1 to use if fixed_koff1 is True.

• fixed_kon2 (bool, optional) – If True, kon2 is fixed to kon2_value, default is False.

• kon2_value (float, optional) – Value of kon2 to use if fixed_kon2 is True.

• fixed_koff2 (bool, optional) – If True, koff2 is fixed to koff2_value, default is False.

• koff2_value (float, optional) – Value of koff2 to use if fixed_koff2 is True.

• max_nfev (int, optional) – Maximum number of function evaluations.

Returns:

• list – Fitted parameters.

• np.ndarray – Covariance matrix of the fitted parameters.

• list – Fitted values for each association signal, same dimensions as assoc_signal_lst.

• list – Fitted values for each dissociation signal, same dimensions as disso_signal_lst.

pykingenie.utils.fitting_surface.fit_one_site_assoc_and_disso_ktr(assoc_signal_lst, assoc_time_lst, analyte_conc_lst, disso_signal_lst, disso_time_lst, initial_parameters, low_bounds, high_bounds, smax_idx=None, shared_smax=False, fixed_t0=True, fixed_Kd=False, Kd_value=None, fixed_koff=False, koff_value=None)

Global fit to a set of association and dissociation traces - one-to-one with mass transport limitation binding model.

Parameters:

• assoc_signal_lst (list) – List of association signals to fit, each signal is a numpy array.

• assoc_time_lst (list) – List of association time arrays.

• analyte_conc_lst (list) – List of analyte concentrations, each element is a numpy array.

• disso_signal_lst (list) – List of dissociation signals to fit, each signal is a numpy array.

• disso_time_lst (list) – List of dissociation time arrays.

• initial_parameters (list) – Initial guess for the parameters.

• low_bounds (list) – Lower bounds for the parameters.

• high_bounds (list) – Upper bounds for the parameters.

• smax_idx (list, optional) – List of indices for the s_max parameters, used if shared_smax is True.

• shared_smax (bool, optional) – If True, the s_max parameters are shared between traces, default is False.

• fixed_t0 (bool, optional) – If True, t0 is fixed to 0, otherwise we fit it, default is True.

• fixed_Kd (bool, optional) – If True, Kd is fixed to Kd_value, default is False.

• Kd_value (float, optional) – Value of Kd to use if fixed_Kd is True.

• fixed_koff (bool, optional) – If True, koff is fixed to koff_value, default is False.

• koff_value (float, optional) – Value of koff to use if fixed_koff is True.

Returns:

• list – Fitted parameters.

• np.ndarray – Covariance matrix of the fitted parameters.

• list – Fitted values for each association signal, same dimensions as assoc_signal_lst.

• list – Fitted values for each dissociation signal, same dimensions as disso_signal_lst.

pykingenie.utils.fitting_surface.one_site_assoc_and_disso_asymmetric_ci95(kd_estimated, rss_desired, assoc_signal_lst, assoc_time_lst, analyte_conc_lst, disso_signal_lst, disso_time_lst, initial_parameters, low_bounds, high_bounds, smax_idx=None, shared_smax=False, fixed_t0=True, fixed_koff=False, koff_value=None)

Calculate the asymmetric confidence interval for the Kd value, given a desired RSS value.

Parameters:

• kd_estimated (float) – Estimated Kd value.

• rss_desired (float) – Desired RSS value.

• assoc_signal_lst (list) – List of association signals to fit, each signal is a numpy array.

• assoc_time_lst (list) – List of association time arrays.

• analyte_conc_lst (list) – List of analyte concentrations, each element is a numpy array.

• disso_signal_lst (list) – List of dissociation signals to fit, each signal is a numpy array.

• disso_time_lst (list) – List of dissociation time arrays.

• initial_parameters (list) – Initial guess for the parameters, without the Kd value!

• low_bounds (list) – Lower bounds for the parameters, without the Kd value!

• high_bounds (list) – Upper bounds for the parameters, without the Kd value!

• smax_idx (list, optional) – List of indices for the s_max parameters, used if shared_smax is True.

• shared_smax (bool, optional) – If True, the s_max parameters are shared between traces, default is False.

• fixed_t0 (bool, optional) – If True, t0 is fixed to 0, otherwise we fit it, default is True.

• fixed_koff (bool, optional) – If True, koff is fixed to koff_value, default is False.

• koff_value (float, optional) – Value of koff to use if fixed_koff is True.

Returns:

• float – Minimum Kd value for the 95% confidence interval.

• float – Maximum Kd value for the 95% confidence interval.

pykingenie.utils.fitting_surface.one_site_assoc_and_disso_asymmetric_ci95_koff(koff_estimated, rss_desired, assoc_signal_lst, assoc_time_lst, analyte_conc_lst, disso_signal_lst, disso_time_lst, initial_parameters, low_bounds, high_bounds, smax_idx=None, shared_smax=False, fixed_t0=True)

Calculate the asymmetric confidence interval for the koff value, given a desired RSS value.

Parameters:

• koff_estimated (float) – Estimated koff value.

• rss_desired (float) – Desired RSS value.

• assoc_signal_lst (list) – List of association signals to fit, each signal is a numpy array.

• assoc_time_lst (list) – List of association time arrays.

• analyte_conc_lst (list) – List of analyte concentrations, each element is a numpy array.

• disso_signal_lst (list) – List of dissociation signals to fit, each signal is a numpy array.

• disso_time_lst (list) – List of dissociation time arrays.

• initial_parameters (list) – Initial guess for the parameters, without the Kd value!

• low_bounds (list) – Lower bounds for the parameters, without the Kd value!

• high_bounds (list) – Upper bounds for the parameters, without the Kd value!

• smax_idx (list, optional) – List of indices for the s_max parameters, used if shared_smax is TRUE

• shared_smax (bool, optional) – If True, the s_max parameters are shared between traces

• fixed_t0 (bool, optional) – If True, t0 is fixed to 0, otherwise we fit it, default is True

Returns:

• float – Minimum koff value for the 95% confidence interval.

• float – Maximum koff value for the 95% confidence interval.

pykingenie.utils.fitting_surface.get_smax_upper_bound_factor(Kd_ss)

Get a factor to determine the upper bound for Smax based on Kd_ss value.

Parameters:

Kd_ss (float) – Steady state Kd value.

Returns:

Factor to multiply for setting Smax upper bound, or None if no matching range found.

Return type:

float or None

pykingenie.utils.math module

pykingenie.utils.math.single_exponential(t, a0, a1, kobs)

Single exponential function for fitting.

Parameters:

• t (np.ndarray) – Time values.

• a0 (float) – Offset.

• a1 (float) – Amplitude.

• kobs (float) – Observed rate constant.

Returns:

Computed values of the single exponential function.

Return type:

np.ndarray

pykingenie.utils.math.double_exponential(t, a0, a1, kobs1, a2, kobs2)

Double exponential function for fitting.

Parameters:

• t (np.ndarray) – Time values.

• a0 (float) – Offset.

• a1 (float) – Amplitude of the first exponential.

• kobs1 (float) – Observed rate constant of the first exponential.

• a2 (float) – Amplitude of the second exponential.

• kobs2 (float) – Observed rate constant of the second exponential.

Returns:

Computed values of the double exponential function.

Return type:

np.ndarray

pykingenie.utils.math.median_filter(y, x, rolling_window)

Compute the median filter of the input signal using a rolling window.

The x vector is converted into an integer vector and then into a time variable to take advantage of pandas rolling().median(). Returns the y vector passed through the median filter.

Parameters:

• y (np.ndarray) – Input signal values.

• x (np.ndarray) – Time or index values corresponding to the signal.

• rolling_window (int or float) – Size of the median filter window.

Returns:

Filtered signal.

Return type:

np.ndarray

pykingenie.utils.math.rss_p(rrs0, n, p, alfa)

Compute the desired residual sum of squares for a 1-alpha confidence interval.

Given the residuals of the best fitted model, this is used to compute asymmetric confidence intervals for the fitted parameters.

Parameters:

• rrs0 (float) – Residual sum of squares of the model with the best fit.

• n (int) – Number of data points.

• p (int) – Number of parameters.

• alfa (float) – Desired confidence interval (1 - alpha).

Returns:

Residual sum of squares for the desired confidence interval.

Return type:

float

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

Compute the residual sum of squares.

Parameters:

• y (np.ndarray) – Observed values.

• y_fit (np.ndarray) – Fitted values.

Returns:

Residual sum of squares.

Return type:

float

pykingenie.utils.math.get_desired_rss(y, y_fit, n, p, alpha=0.05)

Find the residual sum of squares required for a 1-alpha confidence interval.

Given the observed and fitted data, computes the RSS for the desired confidence interval.

Parameters:

• y (np.ndarray) – Observed values.

• y_fit (np.ndarray) – Fitted values.

• n (int) – Number of data points.

• p (int) – Number of parameters.

• alpha (float, optional) – Desired confidence interval (default is 0.05).

Returns:

Residual sum of squares for the desired confidence interval.

Return type:

float

pykingenie.utils.palettes module

Color palettes for plotting.

This module provides color palettes that can be used for visualizing data in plots. These palettes are collections of colors represented as hex values.

pykingenie.utils.palettes.VIRIDIS = ['#440154', '#471063', '#481d6f', '#472a7a', '#414487', '#3c4f8a', '#375a8c', '#32648e', '#2a788e', '#26828e', '#228b8d', '#1f958b', '#22a884', '#2cb17e', '#3bbb75', '#4ec36b', '#7ad151', '#95d840', '#b0dd2f', '#cae11f', '#fde725']

Viridis color palette.

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

pykingenie.utils.palettes.set1_colors = ['#e41a1c', '#377eb8', '#4daf4a', '#984ea3', '#ff7f00', '#ffff33', '#a65628', '#f781bf', '#999999']

Set1 color palette.

A qualitative color palette suitable for categorical data. Contains 9 distinct colors that are visually distinguishable.

pykingenie.utils.palettes.set3_colors = ['#8dd3c7', '#ffffb3', '#bebada', '#fb8072', '#80b1d3', '#fdb462', '#b3de69', '#fccde5', '#d9d9d9', '#bc80bd', '#ccebc5', '#ffed6f']

Set3 color palette.

A qualitative color palette with softer, pastel-like colors. Contains 12 distinct colors suitable for categorical data with many categories.

pykingenie.utils.plotting module

pykingenie.utils.plotting.config_fig(fig, name_for_download, export_format=None, plot_width=10, plot_height=6, scale_factor=50, save=False)

Configure Plotly figure size and optionally save to file.

Parameters:

• fig (go.Figure) – The Plotly figure.

• name_for_download (str) – Base name for saving the figure.

• export_format (str, optional) – ‘png’, ‘svg’, ‘pdf’, etc. (if saving).

• plot_width (int, optional) – Width in arbitrary units. Default is 10.

• plot_height (int, optional) – Height in arbitrary units. Default is 6.

• scale_factor (int, optional) – Multiply width/height to get actual pixels. Default is 50.

• save (bool, optional) – Whether to save the figure as a file. Default is False.

Returns:

The updated figure.

Return type:

go.Figure

pykingenie.utils.plotting.plot_plate_info(pyKinetics, experiment_name, font_size=18)

Plot the plate layout information from a KineticsAnalyzer experiment.

Parameters:

• pyKinetics (KineticsAnalyzer) – The KineticsAnalyzer instance containing the experiment data.

• experiment_name (str) – The name of the experiment to plot.

• font_size (int, optional) – Font size for the plot. Default is 18.

Returns:

A Plotly figure containing the plate layout.

Return type:

go.Figure

pykingenie.utils.plotting.plot_traces(xs, ys, legends, colors, show, marker_size=1, line_width=2)

Plot sensor traces for a set of sensors.

Parameters:

• xs (list of np.ndarray) – List of x-axis arrays (time) for each sensor.

• ys (list of np.ndarray) – List of y-axis arrays (signal) for each sensor.

• legends (list of str) – List of legend labels for each sensor.

• colors (list of str) – List of colors for each sensor trace.

• show (list of bool) – List indicating whether to show each sensor trace.

• marker_size (int, optional) – Size of the markers. Default is 1.

• line_width (int, optional) – Width of the lines. Default is 2.

Returns:

A Plotly figure containing the sensor traces.

Return type:

go.Figure

pykingenie.utils.plotting.plot_traces_all(pyKinetics, legends_df, plot_width=16, plot_height=14, plot_type='png', font_size=18, show_grid_x=False, show_grid_y=False, marker_size=1, line_width=2, vertical_spacing=0.08)

Plot all sensor traces in subplots for a KineticsAnalyzer experiment.

Parameters:

• pyKinetics (KineticsAnalyzer) – The KineticsAnalyzer instance containing the experiment data.

• legends_df (pandas.DataFrame) – DataFrame containing legend, color, and show information for each sensor.

• plot_width (int, optional) – Width of the plot. Default is 16.

• plot_height (int, optional) – Height of the plot. Default is 14.

• plot_type (str, optional) – Type of plot to export (‘png’, ‘svg’, etc.). Default is ‘png’.

• font_size (int, optional) – Font size for plot text. Default is 18.

• show_grid_x (bool, optional) – Whether to show grid lines on the x-axis. Default is False.

• show_grid_y (bool, optional) – Whether to show grid lines on the y-axis. Default is False.

• marker_size (int, optional) – Size of the markers. Default is 1.

• line_width (int, optional) – Width of the lines. Default is 2.

• vertical_spacing (float, optional) – Vertical spacing between subplots. Default is 0.08.

Returns:

A Plotly figure containing all sensor traces in subplots.

Return type:

go.Figure

pykingenie.utils.plotting.plot_steady_state(pyKinetics, plot_width=30, plot_height=20, plot_type='png', font_size=18, show_grid_x=True, show_grid_y=True, marker_size=5, line_width=2, plot_fit=False)

Plot steady-state data for a KineticsAnalyzer experiment.

Parameters:

• pyKinetics (KineticsAnalyzer) – The KineticsAnalyzer instance containing the experiment data.

• plot_width (int, optional) – Width of the plot. Default is 30.

• plot_height (int, optional) – Height of the plot. Default is 20.

• plot_type (str, optional) – Type of plot to export (‘png’, ‘svg’, etc.). Default is ‘png’.

• font_size (int, optional) – Font size for plot text. Default is 18.

• show_grid_x (bool, optional) – Whether to show grid lines on the x-axis. Default is True.

• show_grid_y (bool, optional) – Whether to show grid lines on the y-axis. Default is True.

• marker_size (int, optional) – Size of the markers. Default is 5.

• line_width (int, optional) – Width of the lines. Default is 2.

• plot_fit (bool, optional) – Whether to plot fitted curves. Default is False.

Returns:

A Plotly figure containing steady-state plots.

Return type:

go.Figure

pykingenie.utils.plotting.plot_association_dissociation(pyKinetics, plot_width=26, plot_height=20, plot_type='png', font_size=14, show_grid_x=False, show_grid_y=False, marker_size=4, line_width=2, split_by_smax_id=True, max_points_per_plot=2000, smooth_curves_fit=False, rolling_window=0.1, vertical_spacing=0.08)

Plot association and dissociation traces for a KineticsAnalyzer experiment.

Parameters:

• pyKinetics (KineticsAnalyzer) – The KineticsAnalyzer instance containing the experiment data.

• plot_width (int, optional) – Width of the plot. Default is 26.

• plot_height (int, optional) – Height of the plot. Default is 20.

• plot_type (str, optional) – Type of plot to export (‘png’, ‘svg’, etc.). Default is ‘png’.

• font_size (int, optional) – Font size for plot text. Default is 14.

• show_grid_x (bool, optional) – Whether to show grid lines on the x-axis. Default is False.

• show_grid_y (bool, optional) – Whether to show grid lines on the y-axis. Default is False.

• marker_size (int, optional) – Size of the markers. Default is 4.

• line_width (int, optional) – Width of the lines. Default is 2.

• split_by_smax_id (bool, optional) – Whether to split subplots by Smax ID. Default is True.

• max_points_per_plot (int, optional) – Maximum number of points per subplot. Default is 2000.

• smooth_curves_fit (bool, optional) – Whether to apply median filter smoothing. Default is False.

• rolling_window (float, optional) – Window size for smoothing. Default is 0.1.

• vertical_spacing (float, optional) – Vertical spacing between subplots. Default is 0.08.

Returns:

A Plotly figure containing association-dissociation traces.

Return type:

go.Figure

pykingenie.utils.processing module

pykingenie.utils.processing.guess_experiment_name(frd_file)

Given a certain frd file, try to guess the experiment name.

The frd file is the format exported by the Biacore software.

Parameters:

frd_file (str) – Path to the FRD file.

Returns:

Experiment name extracted from the file, or ‘Experiment’ if no name is found.

Return type:

str

pykingenie.utils.processing.etree_to_dict(tree)

Converts XML tree to dictionary.

Parameters:

tree (ElementTree) – XML tree to convert.

Returns:

Dictionary representation of the XML tree.

Return type:

dict

pykingenie.utils.processing.combine_dicts(list_dicts)

Combines dictionaries with the same keys into a dictionary with lists as values.

Parameters:

list_dicts (list) – List of dictionaries to combine.

Returns:

Combined dictionary with lists as values.

Return type:

dict

Notes

All dictionaries must have the same keys.

pykingenie.utils.processing.guess_experiment_type(files)

Given file paths, try to guess if they correspond to surface-based or solution-based binding experiments.

Parameters:

files (str or list) – Path or list of paths to the experiment files.

Returns:

‘surface’ or ‘solution’ indicating the experiment type.

Return type:

str

pykingenie.utils.processing.detect_time_list_continuos(assoc_time_lst, disso_time_lst, tolerance=3)

Detect which association steps come directly after a dissociation step.

Useful for single-cycle kinetics.

Parameters:

• assoc_time_lst (list) – List of association time arrays.

• disso_time_lst (list) – List of dissociation time arrays.

• tolerance (float, optional) – Tolerance for the time difference (in seconds), default is 3.

Returns:

List of booleans indicating if the association phase has a dissociation phase just before.

Return type:

list

pykingenie.utils.processing.find_loading_column(df, step_number)

Find the loading column before the given step number.

Parameters:

• df (pd.DataFrame) – DataFrame containing the columns ‘Column’, ‘Type’ and ‘StepNumber’.

• step_number (int) – The step number to find the loading column before.

Returns:

The name of the loading column before the given step number, or None if no loading column is found.

Return type:

str or None

pykingenie.utils.processing.concat_signal_lst(signal_lst)

Concatenate a list of signals into a single array.

Parameters:

signal_lst (list) – List of signals to concatenate, each signal is a numpy array.

Returns:

Concatenated signal.

Return type:

np.ndarray

pykingenie.utils.processing.expand_parameter_list(parameter_lst, id_list)

Expand a parameter list based on ID mapping.

Given a list of n-parameters, such as [1,3] and another list containing IDs, such as [0,0,0,0,0,1,1], create a new list where the elements are repeated according to the IDs. In this case: [1,1,1,1,1,3,3]

Parameters:

• parameter_lst (list) – List of n-Parameters.

• id_list (list) – List of m-IDs mapping to parameter indices.

Returns:

m-Parameters list expanded according to the IDs.

Return type:

list

pykingenie.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

pykingenie.utils.processing.get_palette(n_colors)

Get a color palette with the specified number of colors.

Parameters:

n_colors (int) – Number of colors to include in the palette.

Returns:

List of hex color codes.

Return type:

list

Notes

Uses Set1 from ColorBrewer for n_colors <= 9, Set3 for n_colors <= 12, and interpolated colors for n_colors > 12.

pykingenie.utils.processing.get_plotting_df(ID, labels=None)

Create a DataFrame for plotting purposes with colors and labels.

Parameters:

• ID (list) – List of unique identifiers for each entry.

• labels (list, optional) – List of labels corresponding to each ID. Defaults to None, in which case the ID values are used as labels.

Returns:

DataFrame containing Internal_ID, Color, Legend, and Show columns.

Return type:

pd.DataFrame

pykingenie.utils.processing.subset_data(data, max_points=200)

Subset data to a maximum number of points for plotting.

Parameters:

• data (list or np.ndarray) – Data to be subsetted.

• max_points (int, optional) – Maximum number of points to retain, default is 200.

Returns:

Subsetted data with at most max_points points.

Return type:

list or np.ndarray

pykingenie.utils.processing.sample_type_to_letter(string)

Convert sample type string to a single letter code.

Parameters:

string (str) – Sample type string.

Returns:

Single letter code representing the sample type.

Return type:

str

Notes

Mapping: - KSAMPLE/SAMPLE -> S - LOADING/KLOADING -> L - NEUTRALIZATION -> N - REGENERATION -> R - BASELINE/BUFFER -> B - Others -> First letter of the string

pykingenie.utils.processing.get_colors_from_numeric_values(values, min_val, max_val, use_log_scale=True)

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

pykingenie.utils.processing.if_string_to_list(string_or_list)

Convert a string to a list if necessary.

Parameters:

string_or_list (str or list) – Input string or list to convert.

Returns:

Converted list.

Return type:

list

Raises:

TypeError – If input is neither a string nor a list.

pykingenie.utils.processing.find_index_of_previous_step_type(df_steps, step_index, step_type)

Find the index of the first step of a given type before a specified step index.

Parameters:

• df_steps (pd.DataFrame) – DataFrame containing step information with a ‘Type’ column.

• step_index (int) – Current step index.

• step_type (str) – Type of step to search for.

Returns:

Index of the first step of the specified type before the given step index, or None if no matching step is found.

Return type:

int or None

pykingenie.utils.signal_solution module

pykingenie.utils.signal_solution.ode_one_site_insolution(t, complex_conc, koff, Kd, a_total, b_total)

ODE for the one binding site model in solution.

Parameters:

• t (float) – Time.

• complex_conc (float) – Concentration of the complex.

• koff (float) – Off rate constant.

• Kd (float) – Equilibrium dissociation constant.

• a_total (float) – Total concentration of the ligand.

• b_total (float) – Total concentration of the receptor.

Returns:

Rate of change of complex concentration.

Return type:

float

pykingenie.utils.signal_solution.solve_ode_one_site_insolution(t, koff, Kd, a_total, b_total, t0=0)

Solve the ODE for the one binding site model in solution.

Assumes that the initial concentration of the complex is zero.

Parameters:

• t (np.ndarray) – Time points to calculate the complex concentration.

• koff (float) – Off rate constant.

• Kd (float) – Equilibrium dissociation constant.

• a_total (float) – Total concentration of the ligand.

• b_total (float) – Total concentration of the receptor.

• t0 (float, optional) – Initial time, default is 0.

Returns:

Complex concentration over time.

Return type:

np.ndarray

pykingenie.utils.signal_solution.signal_ode_one_site_insolution(t, koff, Kd, a_total, b_total, t0=0, signal_a=0, signal_b=0, signal_complex=0)

Solve the ODE for the one binding site model and compute the signal.

Parameters:

• t (np.ndarray) – Time.

• koff (float) – Off rate constant.

• Kd (float) – Equilibrium dissociation constant.

• a_total (float) – Total concentration of the ligand.

• b_total (float) – Total concentration of the receptor.

• t0 (float, optional) – Initial time, default is 0.

• signal_a (float, optional) – Signal for the ligand, default is 0.

• signal_b (float, optional) – Signal for the receptor, default is 0.

• signal_complex (float, optional) – Signal for the complex, default is 0.

Returns:

Signal over time.

Return type:

np.ndarray

pykingenie.utils.signal_solution.ode_induced_fit_insolution(t, y, k1, k_minus1, k2, k_minus2, E_tot, S_tot)

Reduced ODEs for induced fit model using conservation of E and S.

Parameters:

• t (float) – Time.

• y (list) – Concentrations of E·S and ES.

• k1 (float) – Rate constant for E + S -> E·S.

• k_minus1 (float) – Rate constant for E·S -> E + S.

• k2 (float) – Rate constant for E·S -> ES.

• k_minus2 (float) – Rate constant for ES -> E·S.

• E_tot (float) – Total concentration of the enzyme.

• S_tot (float) – Total concentration of the substrate.

Returns:

[dE_S, dES] - Rate of change for concentrations of E·S and ES.

Return type:

list

pykingenie.utils.signal_solution.solve_ode_induced_fit_insolution(t, y0, k1, k_minus1, k2, k_minus2, E_tot, S_tot, t0=0)

Solve the reduced ODE for the induced fit model in solution.

Parameters:

• t (np.ndarray) – Time points to calculate the complex concentration.

• y0 (list) – Initial concentrations of E·S and ES.

• k1 (float) – Rate constant for E + S -> E·S.

• k_minus1 (float) – Rate constant for E·S -> E + S.

• k2 (float) – Rate constant for E·S -> ES.

• k_minus2 (float) – Rate constant for ES -> E·S.

• E_tot (float) – Total concentration of the enzyme.

• S_tot (float) – Total concentration of the substrate.

• t0 (float, optional) – Initial time, default is 0.

Returns:

Solution of the ODE, contains the concentration of E, S, E·S and ES.

Return type:

np.ndarray

pykingenie.utils.signal_solution.signal_ode_induced_fit_insolution(t, y, k1, k_minus1, k2, k_minus2, E_tot, S_tot, t0=0, signal_E=0, signal_S=0, signal_ES_int=0, signal_ES=0)

Solve the reduced ODE for the induced fit model and compute the signal.

Parameters:

• t (np.ndarray) – Time.

• y (list) – Concentrations of E·S and ES.

• k1 (float) – Rate constant for E + S -> E·S.

• k_minus1 (float) – Rate constant for E·S -> E + S.

• k2 (float) – Rate constant for E·S -> ES.

• k_minus2 (float) – Rate constant for ES -> E·S.

• E_tot (float) – Total concentration of the enzyme.

• S_tot (float) – Total concentration of the substrate.

• t0 (float, optional) – Initial time, default is 0.

• signal_E (float, optional) – Signal for E, default is 0.

• signal_S (float, optional) – Signal for S, default is 0.

• signal_ES_int (float, optional) – Signal for E·S, default is 0.

• signal_ES (float, optional) – Signal for ES, default is 0.

Returns:

Signal over time.

Return type:

np.ndarray

pykingenie.utils.signal_solution.ode_conformational_selection_insolution(t, y, k1, k_minus1, k2, k_minus2)

ODE for the conformational selection model.

Species:

E1: Free enzyme in state 1 E2: Free enzyme in state 2 S: Free substrate E2S: Complex

ODE for the conformational selection model:

E1 <-> E2 (conformational change) E2 + S <-> E2S (binding)

Parameters:

• t (float) – Time.

• y (list) – Concentrations of E1, E2, S, and E2S.

• k1 (float) – Rate constant for E1 -> E2.

• k_minus1 (float) – Rate constant for E2 -> E1.

• k2 (float) – Rate constant for E2 + S -> E2S.

• k_minus2 (float) – Rate constant for E2S -> E2 + S.

Returns:

[dE1, dE2, dS, dE2S] - Rate of change for concentrations of E1, E2, S, E2S.

Return type:

list

Notes

Example values taken from Fabian Paul, Thomas R. Weikl, 2016:

k+ = 100 / (μM*s) k+ equals k2 in our notation k− = 1 / s k- equals k_minus2 in our notation ke = 10 / s ke equals k1 in our notation kr = 100 / s kr equals k_minus1 in our notation

Protein concentration = 0.5 μM Ligand concentration = 1.8 μM

pykingenie.utils.signal_solution.solve_ode_conformational_selection_insolution(t, y, k1, k_minus1, k2, k_minus2, t0=0)

Solve ODE for the conformational selection model.

Parameters:

• t (np.ndarray) – Time points to calculate the complex concentration.

• y (list) – Initial concentrations of E1, E2, S, and E2S.

• k1 (float) – Rate constant for E1 -> E2.

• k_minus1 (float) – Rate constant for E2 -> E1.

• k2 (float) – Rate constant for E2 + S -> E2S.

• k_minus2 (float) – Rate constant for E2S -> E2 + S.

• t0 (float, optional) – Initial time, default is 0.

Returns:

Solution of the ODE, contains the concentration of E1, E2, S, E2S.

Return type:

np.ndarray

pykingenie.utils.signal_solution.signal_ode_conformational_selection_insolution(t, y, k1, k_minus1, k2, k_minus2, t0=0, signal_E1=0, signal_E2=0, signal_S=0, signal_E2S=0)

Solve the ODE for the conformational selection model and compute the signal.

Parameters:

• t (np.ndarray) – Time.

• y (list) – Concentrations of E1, E2, S, and E2S.

• k1 (float) – Rate constant for E1 -> E2 (aka kc).

• k_minus1 (float) – Rate constant for E2 -> E1 (aka krev).

• k2 (float) – Rate constant for E2 + S -> E2S (aka kon).

• k_minus2 (float) – Rate constant for E2S -> E2 + S (aka koff).

• t0 (float, optional) – Initial time, default is 0.

• signal_E1 (float, optional) – Signal for E1, default is 0.

• signal_E2 (float, optional) – Signal for E2, default is 0.

• signal_S (float, optional) – Signal for S, default is 0.

• signal_E2S (float, optional) – Signal for E2S, default is 0.

Returns:

Signal over time.

Return type:

np.ndarray

pykingenie.utils.signal_solution.get_initial_concentration_conformational_selection(total_protein, k1, k_minus1)

Obtain the equilibrium concentrations of E1 and E2 for the conformational selection model.

Assumes absence of ligand.

Parameters:

• total_protein (float) – Total concentration of the protein.

• k1 (float) – Rate constant for E1 -> E2.

• k_minus1 (float) – Rate constant for E2 -> E1.

Returns:

[E1, E2] - Equilibrium concentrations of E1 and E2.

Return type:

list

pykingenie.utils.signal_solution.get_kobs_induced_fit(tot_lig, tot_prot, kr, ke, kon, koff, dominant=True)

Calculate the observed rate constant (relaxation rate) for the induced fit model in solution.

Parameters:

• tot_lig (float) – Total concentration of the ligand.

• tot_prot (float) – Total concentration of the protein.

• kr (float) – Rate constant for E2S -> E1S.

• ke (float) – Rate constant for E1S -> E2S.

• kon (float) – Rate constant for E1 + S -> E1S.

• koff (float) – Rate constant for E1S -> E1 + S.

• dominant (bool, optional) – If True, calculate the dominant relaxation rate, otherwise calculate the non-dominant relaxation rate, default is True.

Returns:

Observed rate constant (in 1/s).

Return type:

float

pykingenie.utils.signal_solution.get_kobs_conformational_selection(tot_lig, tot_prot, kr, ke, kon, koff, dominant=True)

Calculate the observed rate constant (relaxation rate) for the conformational selection model in solution.

Parameters:

• tot_lig (float) – Total concentration of the ligand.

• tot_prot (float) – Total concentration of the protein.

• kr (float) – Rate constant for E2 -> E1.

• ke (float) – Rate constant for E1 -> E2.

• kon (float) – Rate constant for E2 + S -> E2S.

• koff (float) – Rate constant for E2S -> E2 + S.

• dominant (bool, optional) – If True, calculate the dominant relaxation rate, otherwise calculate the non-dominant relaxation rate, default is True.

Returns:

Observed rate constant (in 1/s).

Return type:

float

pykingenie.utils.signal_surface module

pykingenie.utils.signal_surface.steady_state_one_site(C, Rmax, Kd)

Calculate the steady state signal for a given concentration of ligand.

If the concentration is zero, the signal is zero. If the concentration is infinite, the signal is Rmax. The units of Kd must match the units of C (ligand concentration). Rmax depends on the amount of loaded receptor.

Parameters:

• C (np.ndarray) – Concentration of the analyte.

• Rmax (float) – Maximum response of the analyte.

• Kd (float) – Equilibrium dissociation constant.

Returns:

Steady state signal, according to the given parameters.

Return type:

np.ndarray

pykingenie.utils.signal_surface.one_site_association_analytical(t, s0, s_max, k_off, Kd, A, t0=0)

Analytical solution for the one site association model.

Parameters:

• t (np.ndarray) – Time variable.

• s0 (float) – Initial signal.

• s_max (float) – Maximum signal.

• k_off (float) – Dissociation rate constant.

• Kd (float) – Equilibrium dissociation constant.

• A (float) – Concentration of the analyte.

• t0 (float, optional) – Initial time offset, default is 0.

Returns:

Signal over time.

Return type:

np.ndarray

pykingenie.utils.signal_surface.one_site_dissociation_analytical(t, s0, k_off, t0=0)

Analytical solution for the one site model - dissociation phase.

Parameters:

• t (np.ndarray) – Time variable.

• s0 (float) – Initial signal.

• k_off (float) – Dissociation rate constant.

• t0 (float, optional) – Initial time offset, default is 0.

Returns:

Signal over time.

Return type:

np.ndarray

pykingenie.utils.signal_surface.ode_one_site_mass_transport_association(t, y, params, analyte_conc)

ODE for Mass Transport-limited binding.

See https://www.cell.com/AJHG/fulltext/S0006-3495(07)70982-7

Parameters:

• t (float) – Time variable.

• y (list) – List of the state variables [s1,cs].

• params (list) – List of the parameters [K_d, k_off, k_tr, s_max].

• analyte_conc (float) – Concentration of the analyte.

Returns:

[ds1_dt, dcs_dt] representing the signal and analyte surface concentration derivatives.

Return type:

list

pykingenie.utils.signal_surface.ode_one_site_mass_transport_dissociation(t, s1, params)

ODE for Mass Transport-limited binding - dissociation phase.

See Equation 7 from https://pmc.ncbi.nlm.nih.gov/articles/PMC4134667/

Parameters:

• t (float) – Time variable.

• s1 (float) – The state variable representing the signal.

• params (list) – List of the parameters [K_d, k_off, k_tr, s_max].

Returns:

The derivative of signal over time.

Return type:

float

pykingenie.utils.signal_surface.solve_ode_one_site_mass_transport_association(t, s1_0, cs_0, analyte_conc, K_d, k_off, k_tr, s_max, t0=0)

Solves the ODE for the one site mass transport model - association phase.

Parameters:

• t (np.ndarray) – Time variable.

• s1_0 (float) – Initial signal.

• cs_0 (float) – Initial analyte surface concentration.

• analyte_conc (float) – Concentration of the analyte.

• K_d (float) – Equilibrium dissociation constant.

• k_off (float) – Dissociation rate constant.

• k_tr (float) – Mass transport rate constant.

• s_max (float) – Maximum signal.

• t0 (float, optional) – Initial time offset, default is 0.

Returns:

Signal over time.

Return type:

np.ndarray

pykingenie.utils.signal_surface.solve_ode_one_site_mass_transport_dissociation(t, s1_0, K_d, k_off, k_tr, s_max, t0=0)

Solves the ODE for the one site mass transport model - dissociation phase.

Parameters:

• t (np.ndarray) – Time variable.

• s1_0 (float) – Initial signal.

• K_d (float) – Equilibrium dissociation constant.

• k_off (float) – Dissociation rate constant.

• k_tr (float) – Mass transport rate constant.

• s_max (float) – Maximum signal.

• t0 (float, optional) – Initial time offset, default is 0.

Returns:

Signal over time.

Return type:

np.ndarray

pykingenie.utils.signal_surface.differential_matrix_association_induced_fit(koff, kon, kc, krev, a)

Association step set of differential equations for the induced fit model.

Differential equations for -dS/dt and dS1/dt where: S = R([E2S] + [E1S]) ; Total signal S1 = R[E2S] ; Signal produced by E2S Smax = R([Et]) ; Maximum signal

Note: E is here the molecule attached to the surface, S is the substrate. The signal produced by E2S and E1S is the same.

Parameters:

• koff (float) – Rate constant for E2S -> E2 + S.

• kon (float) – Rate constant for E2 + S -> E2S.

• kc (float) – Rate constant for E1 -> E2.

• krev (float) – Rate constant for E2 -> E1.

• a (float) – Concentration of the analyte (molecule being flown).

Returns:

Differential matrix.

Return type:

np.ndarray

pykingenie.utils.signal_surface.differential_matrix_association_conformational_selection(koff, kon, kc, krev, a)

Conformational selection model for the association step.

E1 <-> E2 E2 + S <-> E2S

Set of differential equations for (d[E1]*R)/dt and d[E2S]*R/dt. The signal is only given by E2S.

Parameters:

• koff (float) – Rate constant for E2S -> E2 + S.

• kon (float) – Rate constant for E2 + S -> E2S.

• kc (float) – Rate constant for E1 -> E2.

• krev (float) – Rate constant for E2 -> E1.

• a (float) – Concentration of the analyte (molecule being flown).

Returns:

Differential matrix.

Return type:

np.ndarray

pykingenie.utils.signal_surface.differential_matrix_dissociation_induced_fit(koff, kc, krev)

Dissociation step set of differential equations for the induced fit model.

Differential equations for -ds/dt and ds1/dt.

Parameters:

• koff (float) – Rate constant for E2S -> E2 + S.

• kc (float) – Rate constant for E1 -> E2.

• krev (float) – Rate constant for E2 -> E1.

Returns:

Differential matrix.

Return type:

np.ndarray

pykingenie.utils.signal_surface.differential_matrix_dissociation_conformational_selection(koff, kc, krev)

Dissociation step set of differential equations for the conformational selection model.

Differential equations for (d[E1]*R)/dt and d[E2S]*R/dt. The signal is only proportional to E2S.

Parameters:

• koff (float) – Rate constant for E2S -> E2 + S.

• kc (float) – Rate constant for E1 -> E2.

• krev (float) – Rate constant for E2 -> E1.

Returns:

Differential matrix.

Return type:

np.ndarray

pykingenie.utils.signal_surface.constant_vector_induced_fit(koff, a, kc)

Calculate the constant vector for the induced fit model.

Parameters:

• koff (float) – Rate constant for E·S -> E + S.

• a (float) – Concentration of the analyte (molecule being flown).

• kc (float) – Rate constant for E·S -> ES, induced fit step.

Returns:

Constant vector.

Return type:

np.ndarray

pykingenie.utils.signal_surface.constant_vector_conformational_selection(kon, smax, krev, a)

Calculate the constant vector for the conformational selection model.

Parameters:

• kon (float) – Rate constant for E2 + S -> E2S.

• smax (float) – Signal proportional to the complex (E2S).

• krev (float) – Rate constant for E2 -> E1.

• a (float) – Concentration of the analyte (molecule being flown).

Returns:

Constant vector.

Return type:

np.ndarray

pykingenie.utils.signal_surface.solve_steady_state(A, b)

Calculate the steady state solution of the system of equations.

Parameters:

• A (np.ndarray) – Differential matrix.

• b (np.ndarray) – Constant vector.

Returns:

Steady state solution.

Return type:

np.ndarray

pykingenie.utils.signal_surface.solve_all_states_fast(time, A, initial_conditions, steady_state_value)

Solve the system of differential equations for all time points using matrix exponentiation.

Parameters:

• time (np.ndarray) – Array of time points to solve the system for.

• A (np.ndarray) – Differential matrix of the system.

• initial_conditions (np.ndarray) – Initial conditions for the system.

• steady_state_value (np.ndarray) – Steady state solution of the system.

Returns:

Array of shape (len(time), len(initial_conditions)) containing the state of the system at each time point.

Return type:

np.ndarray

pykingenie.utils.signal_surface.solve_induced_fit_association(time, a_conc, kon, koff, kc, krev, sP1L=0, sP2L=0, smax=0)

Obtain the signal for the induced fit model (surface-based).

We assume that the signal is given by the complex E·S and ES is the same. In other words, the complex before and after the conformational change produces the same signal.

Parameters:

• time (np.ndarray) – Time array.

• a_conc (float) – Concentration of the analyte (molecule being flown).

• kon (float) – Rate constant for E + S -> E·S.

• koff (float) – Rate constant for E·S -> E + S.

• kc (float) – Rate constant for E·S -> ES.

• krev (float) – Rate constant for ES -> E·S.

• sP1L (float, optional) – Initial concentration of E·S, default is 0.

• sP2L (float, optional) – Initial concentration of ES, default is 0.

• smax (float, optional) – Signal proportional to the complex (E·S or ES), default is 0.

Returns:

Signal over time.

Return type:

np.ndarray

pykingenie.utils.signal_surface.solve_conformational_selection_association(time, a_conc, kon, koff, kc, krev, smax=0, sP1=0, sP2L=0)

Obtain the signal for the conformational selection model (surface-based).

We assume that the signal is given by the complex E2S only.

Parameters:

• time (np.ndarray) – Time array.

• a_conc (float) – Concentration of the analyte (molecule being flown).

• kon (float) – Rate constant for E2 + S -> E2S.

• koff (float) – Rate constant for E2S -> E2 + S.

• kc (float) – Rate constant for E1 -> E2.

• krev (float) – Rate constant for E2 -> E1.

• smax (float, optional) – Maximum signal that the complex (E2S) can produce, default is 0.

• sP1 (float, optional) – Initial concentration of E1, default is 0.

• sP2L (float, optional) – Initial concentration of E2S, default is 0.

Returns:

Signal over time, with columns for the signal, sP1, and sP2.

Return type:

np.ndarray

pykingenie.utils.signal_surface.solve_induced_fit_dissociation(time, koff, kc, krev, s0=0, sP2L=0, smax=0)

Obtain the dissociation signal for the induced fit model (surface-based).

We assume that the signal given by the complex E·S and ES is the same. In other words, the complex before and after the conformational change produces the same signal.

Parameters:

• time (np.ndarray) – Time array.

• koff (float) – Rate constant for E·S -> E + S.

• kc (float) – Rate constant for E·S -> ES.

• krev (float) – Rate constant for ES -> E·S.

• s0 (float, optional) – Initial signal, default is 0.

• sP2L (float, optional) – Initial concentration of ES, default is 0.

• smax (float, optional) – Signal proportional to the complex (E·S or ES), default is 0.

Returns:

Signal over time, with columns for total signal, signal produced by E·S, and signal produced by ES.

Return type:

np.ndarray

pykingenie.utils.signal_surface.solve_conformational_selection_dissociation(time, koff, kc, krev, smax=0, sP1=0, sP2L=0)

Obtain the signal for the conformational selection model (surface-based) during dissociation.

We assume that the signal is given by the complex E2S only.

Parameters:

• time (np.ndarray) – Time array.

• koff (float) – Rate constant for E2S -> E2 + S.

• kc (float) – Rate constant for E1 -> E2.

• krev (float) – Rate constant for E2 -> E1.

• smax (float, optional) – Signal proportional to the complex (E2S), default is 0.

• sP1 (float, optional) – Initial concentration of E1, default is 0.

• sP2L (float, optional) – Initial concentration of E2S, default is 0.

Returns:

Array with columns for signal (produced by E2S), sP1 (E1 concentration), and sP2 (E2 concentration).

Return type:

np.ndarray

pykingenie.utils.signal_surface.ode_mixture_analyte_association(t, Ris, C_TOT, Fis, Ris_max, koffs, Kds)

We assume a Langmuir 1:1 interaction between each analyte (Ai) and the ligand (L):

Ai + L <-> AiL, ∀i in [1,N]

Based on https://doi.org/10.1038/s41598-022-18450-y

This model is equivalent to the heterogenous analyte model

The parameters to fit are the factor weights (Fis), the maximum response of each analyte (Ris_max), the dissociation rate constants (koffs), and the equilibrium dissociation constants (Kds)

Parameters:

• t (np.ndarray) – Time variable.

• Ris (list) – Response of each analyte.

• C_TOT (float) – Total concentration of the analyte mixture.

• Fis (np.ndarray) – Factor weights.

• Ris_max (np.ndarray) – Maximum response of each analyte.

• koffs (np.ndarray) – Dissociation rate constants.

• Kds (np.ndarray) – Equilibrium dissociation constants.

Returns:

Rate of change of the response of each analyte.

Return type:

np.ndarray

pykingenie.utils.signal_surface.solve_ode_mixture_analyte_association(t, Ris0, C_TOT, Fis, Ris_max, koffs, Kds, t0=0)

Solves the ODE for the mixture analyte model - association phase

Parameters:

• t (np.ndarray) – Time variable.

• Ris0 (list) – Initial response of each analyte.

• C_TOT (float) – Total concentration of the analyte mixture.

• Fis (np.ndarray) – Factor weights.

• Ris_max (np.ndarray) – Maximum response of each analyte.

• koffs (np.ndarray) – Dissociation rate constants.

• Kds (np.ndarray) – Equilibrium dissociation constants.

• t0 (float, optional) – Initial time offset, default is 0.

Returns:

Response of EACH ANALYTE over time.

Return type:

np.ndarray

pykingenie.utils.signal_surface.ode_mixture_analyte_dissociation(t, Ris, koffs)

We assume a Langmuir 1:1 interaction between each analyte (Ai) and the ligand (L):

Ai + L <-> AiL, ∀i in [1,N]

Based on https://doi.org/10.1038/s41598-022-18450-y

This model is equivalent to the heterogenous analyte model

The parameters to fit are the dissociation rate constants (koffs)

Parameters:

• t (np.ndarray) – Time variable.

• Ris (list) – Response of each analyte.

• koffs (np.ndarray) – Dissociation rate constants.

Returns:

Rate of change of the response of each analyte.

Return type:

np.ndarray

pykingenie.utils.signal_surface.solve_ode_mixture_analyte_dissociation(t, Ris0, koffs, t0=0)

Solves the ODE for the mixture analyte model - dissociation phase

Parameters:

• t (np.ndarray) – Time variable.

• Ris0 (list) – Initial response of each analyte.

• koffs (np.ndarray) – Dissociation rate constants.

• t0 (float, optional) – Initial time offset, default is 0.

Returns:

Response of EACH ANALYTE over time.

Return type:

np.ndarray