diffusive_distinguishability package

Submodules

diffusive_distinguishability.ndim_homogeneous_distinguishability module

diffusive_distinguishability.ndim_homogeneous_distinguishability.compare2(n_dim, d_const1, mult, n_steps, dt, n_reps, loc_std=0)[source]

For one pair of diffusion constants (d_const, d_const*mult) get KL divergence of their posteriors, where the posteriors are generated from an alpha and beta which are the median values from repeating posterior estimation n_reps times.

Parameters:
  • n_dim – number of spatial dimensions
  • d_const1 – diffusion constant (um2/s)
  • mult – multiplier to get d_const2 = mult*d_const1
  • n_steps – trajectory length (number of steps)
  • dt – timestep size (s)
  • n_reps – number of trajectory replicates
  • loc_std – standard deviation of localization error (um)
diffusive_distinguishability.ndim_homogeneous_distinguishability.error_sensitivity(d_const, n_steps_list, dt, n_reps, loc_std)[source]

Look at how the mean and median percent error of the posterior mean relative to the true value depend on the trajectory length used to generate posteriors and number of reps we run.

Parameters:
  • d_const – diffusion constants (um2/s)
  • n_steps_list – list of trajectory lengths to test
  • dt – timestep(s) used to generate trajectories (s)
  • n_reps – number(s) of reps to run to calculate mean and mediate percent error
  • loc_std – standard deviation for Gaussian localization error (um)
Returns:

three dataframes (for 1, 2, and 3 dimensions); each contains the mean percent posterior error relative to

true diffusion constant value, for all pairs of trajectory lengths and localization errors includes in these two input lists

diffusive_distinguishability.ndim_homogeneous_distinguishability.estimate_diffusion(n_dim, dt, dr, prior=<scipy.stats._distn_infrastructure.rv_frozen object>)[source]

Returns the posterior estimate for the diffusion constant given the displacement data and the prior.

Parameters:
  • n_dim – number of spatial dimensions for simulation (1, 2, or 3)
  • dt – timestep size (s)
  • dr – list of normed step sizes from a single trajectory (um)
  • prior – inverse gamma prior distribution estimate for the diffusion constant
Returns:

inverse gamma posterior distribution estimate for the diffusion constant
diffusive_distinguishability.ndim_homogeneous_distinguishability.fill_heatmap_gen(n_dim, d_const, mult_list, n_steps, dt, n_reps, loc_std=0)[source]

Generate a heatmap of KL divergence values for pairwise comparison of diffusion constant posterior distributions. Compared posteriors are generated by scanning through pairings of [d_const, mult*d_const] where mult takes on the range of values provided by mult_list and trajectory lengths. For each pair of diffusion constants, generate a trajectory of length n_steps and find the associated posterior parameter fit, repeating n_reps times to get median parameter values (alpha, beta). Use these median values of alpha and beta to select one posterior diffusion constant distribution for that diffusion constant. Repeat this process for diffusion constant d_const*mult, then calculate the KL divergence of the posteriors for (d_const, d_const*multiplier) and store in dataframe. Repeat for all pairs of (n_steps, multiplier) to fill the dataframe. The results is a heatmap of how distinguishable two diff constants are, conditional upon their relative values and the length of trajectories used.

Parameters:
  • n_dim – number of spatial dimensions
  • d_const – diffusion constant (um2/s)
  • mult_list – list of multipliers to get set of d_const2 values, where d_const2 = mult*d_const
  • n_steps – trajectory length (number of steps)
  • dt – timestep size (s)
  • n_reps – number of trajectories
  • loc_std – standard deviation of localization error (um)
Return df:

dataframe containing the pairwise KL divergences
diffusive_distinguishability.ndim_homogeneous_distinguishability.generate_posterior(n_dim, d_const, n_steps, dt, loc_std=0)[source]

Simulate a single trajectory and find the diffusion constant posterior (inverse gamma) distribution.

Parameters:
  • n_dim – number of spatial dimensions
  • d_const – diffusion constant (um2/s)
  • n_steps – trajectory length (number of steps)
  • dt – timestep size (s)
  • loc_std – standard deviation for Gaussian localization error (um)
Return alpha, beta:
 

scale and shape parameters for inverse gamma posterior for a diffusive trajectory
diffusive_distinguishability.ndim_homogeneous_distinguishability.get_dim_error(n_dim, d_const, n_steps, dt, n_reps, show_plot, loc_std=0)[source]

Given a diffusion constant, get the posterior for a trajectory of length n_steps and timestep dt. Repeat n_reps times and report/plot hist of the percent error of the mean posterior values vs true diffusivity values.

Parameters:
  • n_dim – number of spatial dimensions
  • d_const – diffusion constant (um2/s) whose estimator error we want to calculate
  • n_steps – trajectory length (number of steps)
  • dt – timestep size (s)
  • n_reps – number of trajectory replicates
  • show_plot – T/F flag of whether or not to display histograms of estimator errors
  • loc_std – standard deviation of localization error (um)
Return p_error:

array of percent error between mean posterior estimation and true value for each run with each

number of dimensions

diffusive_distinguishability.ndim_homogeneous_distinguishability.get_posterior_set(n_dim, d_const, n_steps, dt, n_reps, loc_std=0)[source]

Repeat analysis generating a posterior diffusion constant distribution per trajectory for multiple trajectories and return (1) full set and (2) median values of distribution fit parameters.

Parameters:
  • n_dim – number of spatial dimensions
  • d_const – diffusion constant (um2/s)
  • n_steps – trajectory length (number of steps)
  • dt – timestep size (s)
  • n_reps – number of trajectory replicates
  • loc_std – standard deviation for Gaussian localization error (um)
Return alpha, beta, alpha_std, beta_std, alphas, betas:
 

medians, std deviations and arrays of scale and

shape parameters for inverse gamma posteriors for n_reps diffusive trajectories

diffusive_distinguishability.ndim_homogeneous_distinguishability.get_single_error(dim, d_const, n_steps, dt, n, loc_std)[source]

Generate single posterior and calculate percent error of posterior mean relative to the true value.

Parameters:
  • dim – number of spatial dimensions
  • d_const – diffusion constant (um2/s) whose estimator error we want to calculate
  • n_steps – trajectory length (number of steps)
  • dt – timestep size (s)
  • n – trajectory number
  • loc_std – standard deviation of localization error (um)
Returns:

percent error for a single posterior mean relative to true value
diffusive_distinguishability.ndim_homogeneous_distinguishability.get_ticks(tick_values, n_round, n_ticks)[source]

Round tick values and keep only some ticks to improve readability.

Parameters:
  • tick_values – tick values
  • n_round – number of decimal places to round to
  • n_ticks – number of ticks to keep
Return ticks:

list of axis tick values to display
diffusive_distinguishability.ndim_homogeneous_distinguishability.invgamma_fullparams(dist)[source]

Return the alpha,beta parameterization of the inverse gamma distribution.

Parameters:dist – scipy inverse gamma distribution
Returns:alpha and beta parameters characterizing this inverse gamma distribution
diffusive_distinguishability.ndim_homogeneous_distinguishability.invgamma_kldiv(param1, param2)[source]

Compute KL divergence of two inverse gamma distributions (ref: https://arxiv.org/pdf/1605.01019.pdf).

Parameters:
  • param1 – list containing alpha and beta parameters characterizing inverse gamma distribution 1
  • param2 – list containing alpha and beta parameters characterizing inverse gamma distribution 2
Returns:

KL divergence of two inverse gamma distributions
diffusive_distinguishability.ndim_homogeneous_distinguishability.plot_df_results(df1, df2, n_round, n_ticks, size, title1, title2, x_lab, y_lab)[source]

Plot two df heatmaps as two subplots of one figure. They share x and y axis labels but have differing titles.

Parameters:
  • df1 – df to visualize
  • df2 – second df to visualize (often log of df1)
  • n_round – number of axis tick decimal places to round to
  • n_ticks – number of axis ticks to keep
  • size – figure size
  • title1 – plot title for left (df1) panel
  • title2 – plot title for left (df2) panel
  • x_lab – x axis label
  • y_lab – y axis label
diffusive_distinguishability.ndim_homogeneous_distinguishability.show_error_hist(n_dim, p_error)[source]
Plot figure with 3 subplots, where each subplot is a histogram of the percent errors from all runs in a given number
of spatial dimensions.
Parameters:
  • n_dim – number of spatial dimensions
  • p_error – array of percent error for all runs in each number of spatial dimensions
diffusive_distinguishability.ndim_homogeneous_distinguishability.simulate_diffusion_df(n_dim, d_const, n_steps, dt, loc_std=0)[source]

Simulate and output a single trajectory of homogeneous diffusion in a specified number of dimensions.

Parameters:
  • n_dim – number of spatial dimensions for simulation (1, 2, or 3)
  • d_const – diffusion constant (um2/s)
  • n_steps – trajectory length (number of steps)
  • dt – timestep size (s)
  • loc_std – standard deviation for Gaussian localization error (um)
Returns:

trajectory dataframe (position in n_dim dimensions, at each timepoint)
diffusive_distinguishability.ndim_homogeneous_distinguishability.trajectory_df_from_data(trajectory)[source]

If you are using experimental rather than simulated trajectories: this is an example function for how you might import your own timelapse trajectory and put into the required dataframe format, compatible with this notebook for analysis. This function will likely require edits for individual use, to make it compatible with your input trajectory format.

Parameters:trajectory – list or array of spatial positions, where each entry is the position at a single timepoint

(may be 1D, 2D or 3D) :return: dataframe containing trajectory, n-dimensional displacement vectors for each timestep, and step size magnitudes for each timestep

Module contents

Top-level package for diffusive_distinguishability.

diffusive_distinguishability.get_module_version()[source]