DwelltimeModel

lumicks.pylake.DwelltimeModel

class DwelltimeModel(dwelltimes, n_components=1, *, min_observation_time=0, max_observation_time=inf, discretization_timestep=None, tol=None, max_iter=None, use_jacobian=True)

Exponential mixture model optimization for dwelltime analysis.

Warning

This is early access alpha functionality. While usable, this has not yet been tested in a large number of different scenarios. The API can still be subject to change without any prior deprecation notice! If you use this functionality keep a close eye on the changelog for any changes that may affect your analysis.

Parameters:

• dwelltimes (numpy.ndarray) – observations on which the model was trained. Note: the units of the optimized lifetime will be in the units of the dwelltime data. If the dwelltimes are calculated as the number of frames, these then need to be multiplied by the frame time in order to obtain the physically relevant parameter.

• n_components (int) – number of components in the model.

• min_observation_time (float or numpy.ndarray) – minimum experimental observation time. This can either be a scalar or a numpy array with the same length as dwelltimes.

• max_observation_time (float or numpy.ndarray) – maximum experimental observation time. This can either be a scalar or a numpy array with the same length as dwelltimes.

• discretization_timestep (float or np.ndarray, optional) – providing this argument results in taking into account temporal discretization with the given timestep. Omitting this parameter or passing None results in using a continuous probability density function to fit the data.

• tol (float) – The tolerance for optimization convergence. This parameter is forwarded as the ftol argument to scipy.optimize.minimize(method="SLSQP").

• max_iter (int) – The maximum number of iterations to perform. This parameter is forwarded as the maxiter argument to scipy.optimize.minimize(method="SLSQP").

• use_jacobian (bool) – use Jacobian matrix when optimizing (greatly enhances performance)

Raises:

• ValueError – if min_observation_time or max_observation_time is not a scalar and is not the same length as dwelltimes.

• ValueError – if discretization_time is provided and is bigger than the min_observation_time. A minimum observation time shorter than the discretization step does not make sense under this model.

calculate_bootstrap(iterations=500)

Calculate a bootstrap distribution for the model.

Parameters:

iterations (int) – Number of iterations to sample for the distribution.

hist(n_bins=25, bin_spacing='linear', hist_kwargs=None, component_kwargs=None, fit_kwargs=None, xscale=None, yscale=None)

Plot the dwelltime distribution histogram and overlayed model density.

Parameters:

• n_bins (int) – number of bins in the histogram

• bin_spacing ({"log", "linear"}) – determines how bin edges are spaced apart

• hist_kwargs (Optional[dict]) – dictionary of plotting kwargs applied to histogram

• component_kwargs (Optional[dict]) – dictionary of plotting kwargs applied to the line plot for each component

• fit_kwargs (Optional[dict]) – dictionary of plotting kwargs applied to line plot for the total fit

• xscale ({"log", "linear", None}) – scaling for the x-axis; when None default is “linear”

• yscale ({"log", "linear", None}) – scaling for the y-axis; when None default is same as bin_spacing

pdf(x)

Probability Distribution Function (states as rows).

Parameters:

x (np.array) – array of independent variable values at which to calculate the PDF.

plot(n_bins=25, bin_spacing='linear', hist_kwargs=None, component_kwargs=None, fit_kwargs=None, xscale=None, yscale=None)

Deprecated since version 0.12.0: This method has been renamed to more closely match its behavior. Use DwelltimeModel.hist() instead.

profile_likelihood(*, alpha=0.05, num_steps=150, min_step=1e-07, max_step=1.0, min_chi2_step=0.01, max_chi2_step=0.1, verbose=False) → DwelltimeProfiles

Calculate likelihood profiles for this model.

This method traces an optimal path through parameter space in order to estimate parameter confidence intervals. It iteratively performs a step for the profiled parameter, then fixes that parameter and re-optimizes all the other parameters [2] [3].

For each profile likelihood point, the profiled parameter is changed such that the fit error goes up by an amount between min_chi2_step and max_chi2_step. After step size determination, the step is applied and the other parameters are re-optimized.

To prevent step sizes from becoming too small, a minimal step size can be set. When the step size goes below the minimum step size a warning is issued. When this happens, check to verify that the profile likelihood curve is smooth.

Parameters:

• alpha (float) – Significance level. Confidence intervals are calculated as 100 * (1 - alpha)%, default: 0.05

• num_steps (int) – Number of steps to take, default: 150.

• min_step (float) – Minimum step size used during step size determination. Any step size lower will be clamped to this value and a warning will be issued. Default: 1e-7.

• max_step (float) – Maximum step size used during step size determination. Any step size larger will be clamped to this value. Default: 1.0

• min_chi2_step (float) – Minimal desired step in terms of chi squared change prior to re-optimization. When the step results in a fit change smaller than this threshold, the step-size will be increased, default: 0.01.

• max_chi2_step (float) – Minimal desired step in terms of chi squared change prior to re-optimization. When the step results in a fit change bigger than this threshold, the step-size will be reduced. Default: 0.1.

• verbose (bool) – Controls the verbosity of the output. Default: False.

References

[2]

Raue, A., Kreutz, C., Maiwald, T., Bachmann, J., Schilling, M., Klingmüller, U., & Timmer, J. (2009). Structural and practical identifiability analysis of partially observed dynamical models by exploiting the profile likelihood. Bioinformatics, 25(15), 1923-1929.

[3]

Maiwald, T., Hass, H., Steiert, B., Vanlier, J., Engesser, R., Raue, A., Kipkeew, F., Bock, H.H., Kaschek, D., Kreutz, C. and Timmer, J., 2016. Driving the model to its limit: profile likelihood based model reduction. PloS one, 11(9).

property aic: float

Akaike Information Criterion

\[\mathrm{AIC} = 2 k - 2 \ln{(L)}\]

Where \(k\) is the number of parameters minus the number of equality constraints and \(L\) is the maximized value of the likelihood function [1].

The emphasis of this criterion is future prediction. It does not lead to consistent model selection and is more prone to over-fitting than the Bayesian Information Criterion.

References

[1]

Cavanaugh, J.E., 1997. Unifying the derivations for the Akaike and corrected Akaike information criteria. Statistics & Probability Letters, 33(2), pp.201-208.

property amplitudes

Fractional amplitude of each model component.

property bic: float

Bayesian Information Criterion

\[\mathrm{BIC} = k \ln{(n)} - 2 \ln{(L)}\]

Where \(k\) is the number of parameters minus the number of equality constraints, \(n\) is the number of observations (data points), and \(L\) is the maximized value of the likelihood function.

The emphasis of the BIC is put on parsimonious models. As such it is less prone to over-fitting. Selection via BIC leads to a consistent model selection procedure, meaning that as the number of data points tends to infinity, BIC will select the true model assuming the true model is in the set of models.

property bootstrap

Bootstrap distribution.

Deprecated since version 0.13.3: This property will be removed in a future release. Use the class population.dwelltime.DwelltimeBootstrap returned from calculate_bootstrap() instead.

property lifetimes

Lifetime parameter (in time units) of each model component.

property rate_constants

First order rate constant (units of per time) of each model component.