Parameters for fitting - vanTeeffelenLab/ExTrack Wiki

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}

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

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)

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 D (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.

The LocErr_type argument:

The LocErr_type argument allows to create a list of parameters that is most suited to the experiments: If None Localization error will not be considered as a parameter and thus won't be fitted. In this specific case, the user will have to use input_LocErr in the fitting function to inform the model about localization error for each peak (See below).

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

Parameter fitting using param_fitting

Once they have been instanciated, parameters can be fitted using extrack.tracking.param_fitting

arguments:

  • all_tracks: dictionary describing the tracks with track length as keys (number of time positions, e.g. '23') of 3D arrays: dim 0 = track, dim 1 = time position, dim 2 = x, y position. This means 15 tracks of 7 time points in 2D will correspond to an array of shape [15,7,2].
  • dt: time in between frames (s).
  • params: Parameters previously instanciated.
  • nb_states: number of states. estimated_vals, min_values, max_values should be changed accordingly to describe all states and transitions.
  • nb_substeps: number of considered transition steps in between consecutive 2 positions.
  • frame_len: number of frames for which the probability is perfectly computed. See method of the paper for more details.
  • verbose: if 1, print the intermediate values for each iteration of the fit.
  • steady_state: True if tracks are considered at steady state (fractions independent of time), this is most likely not true as tracks join and leave the FOV.
  • workers: number of workers used for the fitting, allows to speed up computation. Do not work from windows at the moment.
  • cell_dims: dimension limits (um) (default [1], can also be [1,2] for instance).
  • input_LocErr: Must be None if fitting localization error. If the user aims to imput localization error infered from a prior method based of peak shape, input_LocErr must be a dictionary of same format than all_tracks (dict with number of time positions as keys (ex. '23') of 3D arrays: dim 0 = track, dim 1 = time step, dim 2 = spatial dimensions). input_LocErr can be extracted from tables/csv or trackmate xml files just like all_tracks using the readers functions (see https://github.com/vanTeeffelenLab/ExTrack/wiki/Loading-data-sets).

outputs:

  • model_fit: lmfit model

model_fit has the class MinimizerResult from the package lmfit (see https://github.com/lmfit/lmfit-py fro more details)

model_fit has interesting attributes: model_fit.params: the most likely set of parameters found by the fitting method model_fit.residual: the likelihood of the model for the best set of parameters (highest likelihood)