Analysis Library¶

Analysis Methods¶

The analysis library supports MSD analysis as well as ADC analysis. ADC analysis generalises MSD analysis by introducing a time dependant apparent diffusion coefficient \(D_\mathrm{app}(t)\) and takes into account the localisation imprecision as well as the microsope’s illumination mode.

MSD analysis includes a linear model as well as a generic power law model. ADC analysis includes predefined models for brownian, confined, hop, and immobile diffusion as well as the possibility to add custom models.

Single Track¶

Simple single-track import and analysis can be done using the Track class.

class trait2d.analysis.Track(x=None, y=None, t=None, id=None)¶

Create a track that can hold trajectory and analysis information.

Parameters:	x (array_like) – x coordinates of trajectory. y (array_like) – y coordinates of trajectory. t (array_like) – time coordinates of trajectory.

adc_analysis(R: float = 0.16666666666666666, fraction_fit_points: float = 0.25, fit_max_time: float = None, maxfev=1000, enable_log_sampling=False, log_sampling_dist=0.2, weighting='error')¶

Revised analysis using the apparent diffusion coefficient. Supposes equal time interval between localizations.

Parameters:	R (float) – Point scanning across the field of view. fraction_fit_points (float) – Fraction of points to use for fitting. Defaults to 25 %. fit_max_time (float) – Maximum time in fit range. Will override fraction_fit_points. maxfev (int) – Maximum function evaluations by scipy.optimize.curve_fit. The fit will fail if this number is exceeded. enable_log_sampling (bool) – Only sample logarithmically spaced time points for analysis. log_sampling_dist (float) – Exponent of logarithmic sampling (base 10). weighting (str) – Weighting of the datapoints used in the fit residual calculation. Can be error (weight by inverse standard deviation), inverse_variance (weight by inverse variance), variance (weight by variance) or disabled (no weighting). Default is error.
Returns:	adc_analysis_results – Dictionary containing all analysis results. Can also be retreived using Track.get_adc_analysis_results().
Return type:	dict

calculate_msd()¶: Calculates the track’s mean squared displacement (msd) and stores it in ‘track’ object. Also deletes temporary values and colelcts them. Furthermore, calculates the standard deviation per point of the MSD array (msd_error) and the standard error of the mean (SEM) [legacy version].

delete_adc_analysis_results()¶: Delete the ADC analysis results.

delete_msd_analysis_results()¶: Delete the MSD analysis results.

classmethod from_dataframe(df, col_name_x='x', col_name_y='y', col_name_t='t', col_name_id='id', unit_length='metres', unit_time='seconds', id=None)¶

Create a single track from a DataFrame. Currently only supports ‘.csv’ tracks. The DataFrame must contain the fields ‘x’, ‘y’, ‘t’ as well as ‘id’. Different column names can also be specified using the appropriate arguments.

Parameters:

df (pandas.DataFrame) – DataFrame containing the data.
col_name_x (str) – Column title of x positions.
col_name_y (str) – Column title of y positions.
col_name_t (str) – Column title of time.
col_name_id (str) – Column title of track IDs.
unit_length (str) – Length unit of track data. Either ‘metres’, ‘millimetres’, ‘micrometres’ or ‘nanometres’.
unit_time (str) – Time unit of track data. Either ‘seconds’, ‘milliseconds’, ‘microseconds’ or ‘nanoseconds’.
id (int) – Track ID in case the file contains more than one track.

Raises:

LoadTrackIdNotFoundError – When no track with the given id is found
LodTrackIdMissingError – When the file contains multiple tracks but no id is specified.

classmethod from_dict(dict)¶: Create a track from a dictionary. :param dict: Dictionary of the track. Has to contain the fields “x”, “y” and “t”. :type dict: dict

classmethod from_file(filename, format=None, col_name_x='x', col_name_y='y', col_name_t='t', col_name_id='id', unit_length='metres', unit_time='seconds', id=None)¶

Create a single track from a file. Currently only supports ‘.csv’ tracks. The DataFrame must contain the fields ‘x’, ‘y’, ‘t’ as well as ‘id’. Different column names can also be specified using the appropriate arguments.

Parameters:

filename (str) – Name of the file.
format (str) – Either ‘csv’ or ‘json’ or ‘pcl’. Only csv is implemented at the moment.
col_name_x (str) – Column title of x positions.
col_name_y (str) – Column title of y positions.
col_name_t (str) – Column title of time.
col_name_id (str) – Column title of track IDs.
unit_length (str) – Length unit of track data. Either ‘metres’, ‘millimetres’, ‘micrometres’ or ‘nanometres’.
unit_time (str) – Time unit of track data. Either ‘seconds’, ‘milliseconds’, ‘microseconds’ or ‘nanoseconds’.
id (int) – Track ID in case the file contains more than one track.

Raises:

LoadTrackIdNotFoundError – When no track with the given id is found
LodTrackIdMissingError – When the file contains multiple tracks but no id is specified.

get_adc_analysis_results()¶: Returns the ADC analysis results.

get_id()¶: Return ID of the track.

get_msd()¶: Returns the MSD values of the track.

get_msd_SEM()¶: Returns the MSD SEM of the track.

get_msd_analysis_results()¶: Returns the MSD analysis results.

get_msd_error()¶: Returns the MSD error values of the track.

get_size()¶: Return number of points of the trajectory.

get_t()¶: Return time coordinates of trajectory.

get_trajectory()¶: Returns the trajectory as a dictionary.

get_x()¶: Return x coordinates of trajectory.

get_y()¶: Return y coordinates of trajectory.

is_msd_calculated()¶: Returns True if the MSD of this track has already been calculated.

msd_analysis(fraction_fit_points: float = 0.25, n_fit_points: int = None, fit_max_time: float = None, initial_guesses={}, maxfev=1000, R: float = 0)¶

Classical Mean Squared Displacement Analysis for single track Supposes equal time interval between localizations.

Parameters:	fraction_fit_points (float) – Fraction of points to use for fitting if n_fit_points is not specified. n_fit_points (int) – Number of points to user for fitting. Will override fraction_fit_points. fit_max_time (float) – Maximum time in fit range. Will override fraction_fit_points and n_fit_points. initial_guesses (dict) – Dictionary containing initial guesses for the parameters. Keys can be “model1” and “model2”. All values default to 1. maxfev (int) – Maximum function evaluations by scipy.optimize.curve_fit. The fit will fail if this number is exceeded. R (float) – Point scanning across the field of view.
Returns:	msd_analysis_results – Dictionary containing all MSD analysis results. Can also be retreived using Track.get_msd_analysis_results().
Return type:	dict

normalized(normalize_t=True, normalize_xy=True)¶

Normalize the track.

Parameters:	normalize_t (bool) – Normalize the time component of the track by setting the first time in the track to zero. normalize_xy (bool) – Normalize the x and y coordinates of the track by setting the initial position in the track to zero.
Returns:
Return type:	Instance of NormalizedTrack containing the normalized track data.

plot_adc_analysis_results()¶

Plot the ADC analysis results.

Raises:	ValueError – Track has not been analyzed using ADC analysis yet.

plot_msd_analysis_results(scale: str = 'log')¶

Plot the MSD analysis results.

Parameters:	scale (str) – How to scale the plot over time. Possible values: ‘log’, ‘linear’.
Raises:	ValueError – Track has not been analyzed using MSD analysis yet.

plot_trajectory(cmap='plasma')¶

Plot the trajectory.

Parameters:	cmap (str) – Name of the colormap to use (see https://matplotlib.org/tutorials/colors/colormaps.html for a list of possible values)

class trait2d.analysis.MSDTrack(msd, msd_err, t, id=None)¶: A special track class that holds an MSD curve but no trajectory data. Can be used for analysis like an ordinary trait2d.analysis.Track object but certain functions might not be available.

Multiple Tracks¶

If multiple tracks have to be imported and analysed in bulk, the ListOfTracks class can be used.

class trait2d.analysis.ListOfTracks(tracks: list = None)¶

Create an object that can hold multiple tracks and analyze them in bulk.

Parameters:	tracks (list) – A Python list containing the tracks as Track objects.

adc_analysis(**kwargs)¶

Analyze all tracks using ADC analysis.

Parameters:	**kwargs – Keyword arguments to be used by adc_analysis for each track.
Returns:	List containing the indices of the tracks for which the analysis failed.
Return type:	list_failed

adc_summary(ensemble_average=False, avg_only_params=False, interpolation=False, plot_msd=False, plot_dapp=False, plot_pie_chart=False)¶

Average tracks by model and optionally of the whole ensemble and optionally plot the results.

Parameters:	ensemble_average (bool) – averages the MSD and D_app, but not the parameters, for all the tracks and adds it to the results avg_only_params (bool) – Only average the model parameters but not D_app and MSD interpolation (bool) – User linear interpolation of averaging. Has to be used when not all tracks have the same uniform time step size. plot_msd (bool) – Plot the averaged MSD for each model. plot_dapp (bool) – Plot the averaged D_app for each model. plot_pie_chart (bool) – Plot a pie chart showing the relative fractions of each model.
Returns:	results – Relative shares and averaged values of each model.
Return type:	dict

average(interpolation=False)¶

Get the mean squared displacement averaged over all tracks.

Parameters:	interpolation (bool) – Linearly interpolate all msd values over the time points of the first track. Use when working with differently spaced tracks. use_averaged_msd (bool) – Initialize the track with a MSD curve which is the average of all MSD curves in the list. This is not neccessarily equal to the result of performing calculate_msd on the averaged track.
Returns:	track – A single track containing the average
Return type:	Track

classmethod from_file(filename, format=None, col_name_x='x', col_name_y='y', col_name_t='t', col_name_id='id', unit_length='metres', unit_time='seconds')¶

Create a ListOfTracks from a file containing multiple tracks. Currently only supports ‘.csv’ files. The file must contain the fields ‘x’, ‘y’, ‘t’ as well as ‘id’. Different column names can also be specified using the appropriate arguments.

Parameters:

filename (str) – Name of the file.
format (str) – Either ‘csv’ or ‘json’ or ‘pcl’. Only csv is implemented at the moment.
col_name_x (str) – Column title of x positions.
col_name_y (str) – Column title of y positions.
col_name_t (str) – Column title of time.
col_name_id (str) – Column title of track IDs.
unit_length (str) – Length unit of track data. Either ‘metres’, ‘millimetres’, ‘micrometres’ or ‘nanometres’.
unit_time (str) – Time unit of track data. Either ‘seconds’, ‘milliseconds’, ‘microseconds’ or ‘nanoseconds’.
id (int) – Track ID in case the file contains more than one track.

Raises:

LoadTrackIdNotFoundError – When no track with the given id is found
LodTrackIdMissingError – When the file contains multiple tracks but no id is specified.

get_dapp(interpolation=False)¶

Get the apparent diffusion coefficient averaged over all tracks.

Parameters:	interpolation (bool) – Linearly interpolate all D_app values over the time points of the first track. Use when working with differently spaced tracks.
Returns:	t (ndarray) – 1-dimensional array containing time points at which msd was sampled average_dapp (ndarray) – 1-dimensional array containing averaged D_app values

get_msd(interpolation=False)¶

Get the mean squared displacement averaged over all tracks.

Parameters:	interpolation (bool) – Linearly interpolate all msd values over the time points of the first track. Use when working with differently spaced tracks.
Returns:	t (ndarray) – 1-dimensional array containing time points at which msd was sampled msd (ndarray) – 1-dimensional array containing averaged msd values

get_sublist(model)¶

Return a new ListOfTracks containing only tracks categorized as the specified model using ADC analysis.

Parameters:	model – Class (not an instance) of the model the tracks should be categorized as. Predefined models can be found at trait2d.analysis.models.
Returns:	track_list – ListOfTracks containing the tracks that meet the criteria. Note: The tracks in the new list will still be references to to the tracks in the original list.
Return type:	ListOfTracks

get_track(idx)¶

Return a single track at the specified index.

Parameters:	idx (int) – Index of track.
Returns:	track – Track at index idx.
Return type:	Track

get_track_by_id(id)¶

Return a single track with the specified ID. If there are multiple tracks with the same ID, only the first track is returned.

Parameters:	id (int) – ID of the track.
Returns:	track – Track with the specified ID.
Return type:	Track

get_tracks()¶

Return a Python list that contains the tracks.

Returns:	tracks – List of tracks. Each element will be a Track object.
Return type:	list

msd_analysis(**kwargs)¶

Analyze all tracks using MSD analysis.

Parameters:	**kwargs – Keyword arguments to be used by msd_analysis for each track.
Returns:	List containing the indices of the tracks for which the analysis failed.
Return type:	list_failed

normalize(**kwargs)¶

Normalize all tracks. All Track instances of the ListOfTracks will be replaced by NormalizedTrack instances containing individual information about the normalization.

Parameters:	arguments to be used by Track.normalized() for each track. (Keyword) –

plot_dapp()¶

Plot the apparent diffusion coefficient averaged over all tracks.

Parameters:	interpolation (bool) – Linearly interpolate all D_app values over the time points of the first track. Use when working with differently spaced tracks.

plot_msd(interpolation=False)¶

Plot the mean squared displacement averaged over all tracks.

Parameters:	interpolation (bool) – Linearly interpolate all msd values over the time points of the first track. Use when working with differently spaced tracks.

plot_trajectories(cmap='plasma')¶

Plot all trajectories.

Parameters:	cmap (str) – Name of the colormap to use (see https://matplotlib.org/tutorials/colors/colormaps.html for a list of possible values)

ModelDB¶

ModelDB allows managing which models are used for ADC analysis. You can define your own models or use predefined models (see the Models section).

class trait2d.analysis.ModelDB¶

Singleton class holding all models that should be used in analysis.

add_model(model)¶

Add a new model class to the ModelDB.

Parameters:	model – Model class (not an instance) to add. There are predefined models available in trait2d.analysis.models. Example usage: from trait2d.analysis.models import ModelConfined ModelDB().add_model(ModelConfined)

cleanup()¶: Remove all models from ModelDB. It is good practice to call this at the end of your scripts since other scripts might share the same instance.

get_model(model)¶

Return the model instance from ModelDB.

Parameters:	model – Model class (not and instance) to remove. Example usage: from trait2d.analysis.models import ModelConfined ModelDB().get_model(ModelConfined).initial = [1.0e-12, 1.0e-9, 0.5e-3]

remove_model(model)¶

Remove a model from ModelDB.

Parameters:	model – Model class (not an instance) to remove. Example usage: from trait2d.analysis.models import ModelConfined ModelDB().remove_model(ModelConfined)

Models¶

There are some predefined models available for analysis. Some of these are only used for MSD analysis internally and should not be used for ADC analysis. For more information on adding or removing models to the analysis, see the ModelDB section.

In the model formulas, \(\delta\) refers to the time-invariable localisation imprecision and \(dt\) is the dicretisation time step of the track.

Be aware that \(R\) is not a fit parameter but a constant value which describes the point scanning across the field of view depending on the microscope’s illumination mode. It can be set in the analysis GUI or supplied as a keyword parameter to the trait2d.analysis.Track.adc_analysis() method.

class trait2d.analysis.models.ModelBrownian¶: Model for free, unrestricted diffusion.

\[D_\mathrm{app} = D + \frac{\delta^2}{2 t (1 - 2 R (dt / t))}\]

class trait2d.analysis.models.ModelConfined¶: Model for confined diffusion.

\[D_\mathrm{app} = D_\mu \cdot \frac{\tau}{t} \left( 1 - \exp \left( - \frac{\tau}{t} \right) \right) + \frac{\delta}{2 t (1 - 2 R (dt / t))}\]

class trait2d.analysis.models.ModelHop¶: Model for hop diffusion.

\[D_\mathrm{app} = D_M + D_\mu \cdot \frac{\tau}{t} \left( 1 - \exp \left( - \frac{\tau}{t} \right) \right) + \frac{\delta}{2 t (1 - 2 R (dt / t))}\]

class trait2d.analysis.models.ModelHopModified¶: Modified model for hop diffusion.

\[D_\mathrm{app} = \alpha \cdot D_\mathrm{M} + (1 - \alpha) \cdot D_\mu \left(1 - \exp \left(- \frac{t}{\tau}\right)\right)\]

class trait2d.analysis.models.ModelImmobile¶: Model for immobile diffusion.

\[D_\mathrm{app} = \frac{\delta}{2 t (1 - 2 R (dt / t))}\]

class trait2d.analysis.models.ModelLinear¶: Linear model for MSD analysis.

class trait2d.analysis.models.ModelPower¶: Generic power law model for MSD analysis.