Instanciating model parameters - vanTeeffelenLab/ExTrack GitHub Wiki

As we will see in this section, parameters can vary depending on the aims or the experimenter and the available data. Notably, one can treat localization error as a parameter (for all dimensions or for each dimension) or as an input for each time point of each track previously computed based on peak shape.

We have implemented 2 functions to generate the params object that is required for our model (lmfit): extrack.tracking.get_params, extrack.tracking.generate_params).

The 2 functions can be used interchangeably but the second function extrack.tracking.generate_params is likely more user-friendly as it does not require to explicitly setup each parameter (and their minimum/maximum/variation).

The output params object contains information about the different parameters that the model will try to fit.

  • LocErr: localization error (standard deviation of the probability density function of the observed positions given the real positions).
  • Di: diffusion coefficient of state i.
  • Fi: Initial fraction of state i (fraction of track that start in state i).
  • pij: transition rate per step from state i to state j (in $t^{-1}$ with $\rm{Δ}t$ the time in between subsequent images). pij can be multiplied by $\rm{Δ}t^{-1}$ to obtain the corresponding transition rate per second.

Using extrack.tracking.get_params:

vary_params = {'LocErr' : True, 'D0' : True, 'D1' : True, 'F0' : True, 'p01' : True, 'p10' : True, 'pBL' : False}
estimated_vals =  {'LocErr' : 0.025, 'D0' : 1e-20, 'D1' : 0.05, 'F0' : 0.45, 'p01' : 0.05, 'p10' : 0.05, 'pBL' : 0.1}
min_values = {'LocErr' : 0.007, 'D0' : 1e-12, 'D1' : 0.00001, 'F0' : 0.001, 'p01' : 0.001, 'p10' : 0.001, 'pBL' : 0.001}
max_values = {'LocErr' : 0.6, 'D0' : 1, 'D1' : 10, 'F0' : 0.999, 'p01' : 1., 'p10' : 1., 'pBL' : 0.99}

params = extrack.tracking.get_params(nb_states = nb_states, # number of states of the model
                                     steady_state = steady_state, # can currently only be False
                                     vary_params = vary_params,
                                     estimated_vals = estimated_vals,
                                     min_values = min_values,
                                     max_values = max_values)`

In case of more states, on can use the same technique by adding the correct elements to the vary_params, estimated_vals, min_values and max_values dictionaries.

This method allows to specify for all parameters their expected value, if they have to be varied and their boundaries. However it can be long to write when multiple states.

Using extrack.tracking.generate_params:

Arguments:

  • nb_states: Number of states of the model.
  • LocErr_type: Type of localization errors which can be specified, unique/multiple localization error parameters, input localization error for each peak based on peaks, etc. See below for more information.
  • nb_dims: Number of spatial dimensions, only matters if LocErr_type = 2, which stands for independent localization error parameters for each dimension.
  • LocErr_bounds: List of minimal and maximal values allowed for localization error parameters. e.g. [0.005, 0.1]., The initial guess on LocErr will be the geometric mean of the boundaries if estimated_LocErr = None.
  • D_max: Maximum diffusion coefficient allowed.
  • Fractions_bounds: List of minimum and maximum values for initial fractions.
  • estimated_LocErr: One can specify a list of initial guesses for localization error for each dimension. The list must contain 1 element if LocErr_type = 1, nb_dims elements if LocErr_type = 2 (for each dimension) or 2 elements if LocErr_type = 3 (the first element for x,y axes and the second for z axis).
  • estimated_Ds: List of estimated diffusion coefficients (nb_states elements), D will be arbitrary interspaced from 0 to D_max if None, otherwise input 1D array/list of Ds for each state from state 0 to nb_states - 1.
  • estimated_Fs: List of estimated initial fractions (nb_states elements). Fractions will be initialized as equal if None (1/nb_states), otherwise input 1D array/list of fractions for each state from state 0 to nb_states - 1.
  • estimated_transition_rates: Initial guess of the values for transition rate per step. can be a float (from 0 to 1), in this case all rates will be initialized with the same float value. Can also be a 1D array or list of transition rates from state i to j varying the i then the j, for instance [k01, k02, k10, k12, k20, k21] in case of a 3-state model. The number of elements must be nb_states * (nb_states -1).
  • slope_offsets_estimates: If LocErr_type = 4, list of Initial guesses for the slope and offset where the peak-wise proxi for localization error input_LocErr is linked to the actual localization error such that: localization error = slope * input_LocErr + offset. )

Output:

  • params: List of parameters to fit.

Localization error format:

  • LocErr_type = 1: For a single localization error parameter, all spatial dimensions will use the same localization error.
  • LocErr_type = 2: For a localization error parameter for each dimension. Localization error parameter for dim $i$ will be 'LocErr'+str(i).
  • LocErr_type = 3: For a shared localization error for x and y dims (the 2 first dimensions) and another for z dimension. The z dimension has to be the 3rd in the input tracks.
  • LocErr_type = 4: Can be used when the user has a measurement of the peak quality which is not exactly the localization error. It will draw an affine relationship between localization error according to ExTrack and the peak-wise input specified with input_LocErr (an estimate of localization error/quality of peak/signal to noise ratio, etc).
  • LocErr_type = None: For no localization error fits, localization error is then directly assumed from a prior peak-wise estimate of localization error specified in input_LocErr.

See https://github.com/vanTeeffelenLab/ExTrack/blob/main/Tutorials/Fitting_methods.ipynb or https://github.com/vanTeeffelenLab/ExTrack/blob/main/Tutorials/Tutorial_ExTrack.ipynb for examples on how to load tracks and localization errors on the right format.

Parameter dependencies:

If the experimenter aims to put constraints on the parameter, the object params can be modified at will.

params['LocErr'].value = 0.02 allows to change the initial value of the localization error.

params['LocErr'].vary = False for instance allows to fix the localization error to its initial value.

params.add(name = 'D1', expr = 'D0') allows D1 and D0 to share the same value. The argument expr allows to fix parameter as a function of the other parameters according to the mathematical expression contained in the string.