tobac.analysis.cell_analysis#

Description

Perform analysis on the properties of tracked cells

tobac.analysis.cell_analysis.calculate_overlap(track_1, track_2, min_sum_inv_distance=None, min_mean_inv_distance=None)#

Count the number of time frames in which the individual cells of two tracks are present together and calculate their mean and summed inverse distance.

Parameters:

  • track_1 (pandas.DataFrame) – The tracks conaining the cells to analyze.

  • track_2 (pandas.DataFrame) – The tracks conaining the cells to analyze.

  • min_sum_inv_distance (float, optional) – Minimum of the inverse net distance for two cells to be counted as overlapping. Default is None.

  • min_mean_inv_distance (float, optional) – Minimum of the inverse mean distance for two cells to be counted as overlapping. Default is None.

Returns:

overlap – DataFrame containing the columns cell_1 and cell_2 with the index of the cells from the tracks, n_overlap with the number of frames both cells are present in, mean_inv_distance with the mean inverse distance and sum_inv_distance with the summed inverse distance of the cells.

Return type:

pandas.DataFrame

tobac.analysis.cell_analysis.cell_statistics(input_cubes, track, mask, aggregators, cell, output_path='./', output_name='Profiles', width=10000, z_coord='model_level_number', dimensions=['x', 'y'], **kwargs)#
Parameters:

  • input_cubes (iris.cube.Cube)

  • track (dask.dataframe.DataFrame)

  • mask (iris.cube.Cube) – Cube containing mask (int id for tracked volumes 0 everywhere else).

  • list (aggregators) – list of iris.analysis.Aggregator instances

  • cell (int) – Integer id of cell to create masked cube for output.

  • output_path (str, optional) – Default is ‘./’.

  • output_name (str, optional) – Default is ‘Profiles’.

  • width (int, optional) – Default is 10000.

  • z_coord (str, optional) – Name of the vertical coordinate in the cube. Default is ‘model_level_number’.

  • dimensions (list of str, optional) – Default is [‘x’, ‘y’].

  • **kwargs

Return type:

None

tobac.analysis.cell_analysis.cell_statistics_all(input_cubes, track, mask, aggregators, output_path='./', cell_selection=None, output_name='Profiles', width=10000, z_coord='model_level_number', dimensions=['x', 'y'], **kwargs)#
Parameters:

  • input_cubes (iris.cube.Cube)

  • track (dask.dataframe.DataFrame)

  • mask (iris.cube.Cube) – Cube containing mask (int id for tracked volumes 0 everywhere else).

  • aggregators (list) – list of iris.analysis.Aggregator instances

  • output_path (str, optional) – Default is ‘./’.

  • cell_selection (optional) – Default is None.

  • output_name (str, optional) – Default is ‘Profiles’.

  • width (int, optional) – Default is 10000.

  • z_coord (str, optional) – Name of the vertical coordinate in the cube. Default is ‘model_level_number’.

  • dimensions (list of str, optional) – Default is [‘x’, ‘y’].

  • **kwargs

Return type:

None

tobac.analysis.cell_analysis.cog_cell(cell, Tracks=None, M_total=None, M_liquid=None, M_frozen=None, Mask=None, savedir=None)#
Parameters:

  • cell (int) – Integer id of cell to create masked cube for output.

  • Tracks (optional) – Default is None.

  • M_total (subset of cube, optional) – Default is None.

  • M_liquid (subset of cube, optional) – Default is None.

  • M_frozen (subset of cube, optional) – Default is None.

  • savedir (str) – Default is None.

Return type:

None

tobac.analysis.cell_analysis.histogram_cellwise(Track, variable=None, bin_edges=None, quantity='max', density=False)#

Create a histogram of the maximum, minimum or mean of a variable for the cells (series of features linked together over multiple timesteps) of a track. Essentially a wrapper of the numpy.histogram() method.

Parameters:

  • Track (pandas.DataFrame) – The track containing the variable to create the histogram from.

  • variable (string, optional) – Column of the DataFrame with the variable on which the histogram is to be based on. Default is None.

  • bin_edges (int or ndarray, optional) – If bin_edges is an int, it defines the number of equal-width bins in the given range. If bins is a ndarray, it defines a monotonically increasing array of bin edges, including the rightmost edge.

  • quantity ({'max', 'min', 'mean'}, optional) – Flag determining wether to use maximum, minimum or mean of a variable from all timeframes the cell covers. Default is ‘max’.

  • density (bool, optional) – If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. Default is False.

Returns:

  • hist (ndarray) – The values of the histogram

  • bin_edges (ndarray) – The edges of the histogram

  • bin_centers (ndarray) – The centers of the histogram intervalls

Raises:

ValueError – If quantity is not ‘max’, ‘min’ or ‘mean’.

tobac.analysis.cell_analysis.lifetime_histogram(Track, bin_edges=array([0, 20, 40, 60, 80, 100, 120, 140, 160, 180]), density=False, return_values=False)#

Compute the lifetime histogram of tracked cells.

Parameters:

  • Track (pandas.DataFrame) – Dataframe of linked features, containing the columns ‘cell’ and ‘time_cell’.

  • bin_edges (int or ndarray, optional) – If bin_edges is an int, it defines the number of equal-width bins in the given range. If bins is a ndarray, it defines a monotonically increasing array of bin edges, including the rightmost edge. The unit is minutes. Default is np.arange(0, 200, 20).

  • density (bool, optional) – If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. Default is False.

  • return_values (bool, optional) – Bool determining wether the lifetimes of the features are returned from this function. Default is False.

Returns:

  • hist (ndarray) – The values of the histogram.

  • bin_edges (ndarray) – The edges of the histogram.

  • bin_centers (ndarray) – The centers of the histogram intervalls.

  • minutes, optional (ndarray) – Numpy.array of the lifetime of each feature in minutes. Returned if return_values is True.

tobac.analysis.cell_analysis.velocity_histogram(track, bin_edges=array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29]), density=False, method_distance=None, return_values=False)#

Create an velocity histogram of the tracked cells. If the DataFrame does not contain a velocity column, the velocities are calculated.

Parameters:

  • track (pandas.DataFrame) –

    DataFrame of the linked features, containing the columns ‘cell’,

    ’time’ and either ‘projection_x_coordinate’ and ‘projection_y_coordinate’ or ‘latitude’ and ‘longitude’.

  • bin_edges (int or ndarray, optional) – If bin_edges is an int, it defines the number of equal-width bins in the given range. If bins is a ndarray, it defines a monotonically increasing array of bin edges, including the rightmost edge. Default is np.arange(0, 30000, 500).

  • density (bool, optional) – If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. Default is False.

  • methods_distance ({None, 'xy', 'latlon'}, optional) – Method of distance calculation, used to calculate the velocity. ‘xy’ uses the length of the vector between the two features, ‘latlon’ uses the haversine distance. None checks wether the required coordinates are present and starts with ‘xy’. Default is None.

  • return_values (bool, optional) – Bool determining wether the velocities of the features are returned from this function. Default is False.

Returns:

  • hist (ndarray) – The values of the histogram.

  • bin_edges (ndarray) – The edges of the histogram.

  • velocities , optional (ndarray) – Numpy array with the velocities of each feature.

Functions

calculate_cog(tracks, mass, mask)

Calculate center of gravity and mass for each tracked cell.

calculate_distance(feature_1, feature_2[, ...])

Compute the distance between two features.

calculate_overlap(track_1, track_2[, ...])

Count the number of time frames in which the individual cells of two tracks are present together and calculate their mean and summed inverse distance.

calculate_velocity(track[, method_distance, ...])

Calculate the velocities of a set of linked features.

cell_statistics(input_cubes, track, mask, ...)

cell_statistics_all(input_cubes, track, ...)

cog_cell(cell[, Tracks, M_total, M_liquid, ...])

get_bounding_box(x[, buffer])

Finds the bounding box of a ndarray

histogram_cellwise(Track[, variable, ...])

Create a histogram of the maximum, minimum or mean of a variable for the cells (series of features linked together over multiple timesteps) of a track.

lifetime_histogram(Track[, bin_edges, ...])

Compute the lifetime histogram of tracked cells.

mask_cell(mask, cell, track[, masked])

Create mask for specific cell.

mask_cell_surface(mask, cell, track[, ...])

Create surface projection of 3d-mask for individual cell by collapsing one coordinate.

mask_cube_cell(variable_cube, mask, cell, track)

Mask cube for tracked volume of an individual cell.

velocity_histogram(track[, bin_edges, ...])

Create an velocity histogram of the tracked cells.