tobac package

Submodules

tobac.analysis module

tobac.analysis.cell_analysis module

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.

tobac.analysis.feature_analysis module

Perform analysis on the properties of detected features

tobac.analysis.feature_analysis.area_histogram(features, mask, bin_edges=array([0, 500, 1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500, 5000, 5500, 6000, 6500, 7000, 7500, 8000, 8500, 9000, 9500, 10000, 10500, 11000, 11500, 12000, 12500, 13000, 13500, 14000, 14500, 15000, 15500, 16000, 16500, 17000, 17500, 18000, 18500, 19000, 19500, 20000, 20500, 21000, 21500, 22000, 22500, 23000, 23500, 24000, 24500, 25000, 25500, 26000, 26500, 27000, 27500, 28000, 28500, 29000, 29500]), density=False, method_area=None, return_values=False, representative_area=False)

Create an area histogram of the features. If the DataFrame does not contain an area column, the areas are calculated.

Parameters:

• features (pandas.DataFrame) – DataFrame of the features.

• mask (iris.cube.Cube) – Cube containing mask (int for tracked volumes 0 everywhere else). Needs to contain either projection_x_coordinate and projection_y_coordinate or latitude and longitude coordinates. The output of a segmentation should be used here.

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

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

• representive_area (bool, optional) – If False, no weights will associated to the values. If True, the weights for each area will be the areas itself, i.e. each bin count will have the value of the sum of all areas within the edges of the bin. 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.

• areas (ndarray, optional) – A numpy array approximating the area of each feature.

tobac.analysis.feature_analysis.histogram_featurewise(Track, variable=None, bin_edges=None, density=False)

Create a histogram of a variable from the features (detected objects at a single time step) 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 sequence, it defines a monotonically increasing array of bin edges, including the rightmost edge.

• 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

tobac.analysis.feature_analysis.nearestneighbordistance_histogram(features, bin_edges=array([0, 500, 1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500, 5000, 5500, 6000, 6500, 7000, 7500, 8000, 8500, 9000, 9500, 10000, 10500, 11000, 11500, 12000, 12500, 13000, 13500, 14000, 14500, 15000, 15500, 16000, 16500, 17000, 17500, 18000, 18500, 19000, 19500, 20000, 20500, 21000, 21500, 22000, 22500, 23000, 23500, 24000, 24500, 25000, 25500, 26000, 26500, 27000, 27500, 28000, 28500, 29000, 29500]), density=False, method_distance=None, return_values=False)

Create an nearest neighbor distance histogram of the features. If the DataFrame does not contain a ‘min_distance’ column, the distances are calculated.

bin_edgesint 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).

densitybool, 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.

method_distance{None, ‘xy’, ‘latlon’}, optional

Method of distance calculation. ‘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_valuesbool, optional

Bool determining wether the nearest neighbor distance 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.

• distances, optional (ndarray) – A numpy array with the nearest neighbor distances of each feature.

tobac.analysis.spatial module

Calculate spatial properties (distances, velocities, areas, volumes) of tracked objects

tobac.analysis.spatial.calculate_area(features, mask, method_area=None, vertical_coord=None)

Calculate the area of the segments for each feature.

Parameters:

• features (pandas.DataFrame) – DataFrame of the features whose area is to be calculated.

• mask (iris.cube.Cube) – Cube containing mask (int for tracked volumes 0 everywhere else). Needs to contain either projection_x_coordinate and projection_y_coordinate or latitude and longitude coordinates.

• method_area ({None, 'xy', 'latlon'}, optional) – Flag determining how the area is calculated. ‘xy’ uses the areas of the individual pixels, ‘latlon’ uses the area_weights method of iris.analysis.cartography, None checks wether the required coordinates are present and starts with ‘xy’. Default is None.

• vertical_coord (None | str, optional (default: None)) – Name of the vertical coordinate. If None, tries to auto-detect. It looks for the coordinate or the dimension name corresponding to the string.

Returns:

features – DataFrame of the features with a new column ‘area’, containing the calculated areas.

Return type:

pandas.DataFrame

Raises:

ValueError – If neither latitude/longitude nor projection_x_coordinate/projection_y_coordinate are present in mask_coords. If latitude/longitude coordinates are 2D. If latitude/longitude shapes are not supported. If method is undefined, i.e. method is neither None, ‘xy’ nor ‘latlon’.

tobac.analysis.spatial.calculate_areas_2Dlatlon(_2Dlat_coord, _2Dlon_coord)

Calculate an array of cell areas when given two 2D arrays of latitude and longitude values

NOTE: This currently assuems that the lat/lon grid is orthogonal, which is not strictly true! It’s close enough for most cases, but should be updated in future to use the cross product of the distances to the neighbouring cells. This will require the use of a more advanced calculation. I would advise using pyproj at some point in the future to solve this issue and replace haversine distance.

Parameters:

• _2Dlat_coord (AuxCoord) – Iris auxilliary coordinate containing a 2d grid of latitudes for each point.

• _2Dlon_coord (AuxCoord) – Iris auxilliary coordinate containing a 2d grid of longitudes for each point.

Returns:

area – A numpy array approximating the area of each cell.

Return type:

ndarray

tobac.analysis.spatial.calculate_distance(feature_1, feature_2, method_distance=None)

Compute the distance between two features. It is based on either lat/lon coordinates or x/y coordinates.

Parameters:

• feature_1 (pandas.DataFrame or pandas.Series) – Dataframes containing multiple features or pandas.Series of one feature. Need to contain either projection_x_coordinate and projection_y_coordinate or latitude and longitude coordinates.

• feature_2 (pandas.DataFrame or pandas.Series) – Dataframes containing multiple features or pandas.Series of one feature. Need to contain either projection_x_coordinate and projection_y_coordinate or latitude and longitude coordinates.

• method_distance ({None, 'xy', 'latlon'}, optional) – Method of distance calculation. ‘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.

Returns:

distance – Float with the distance between the two features in meters if the input are two pandas.Series containing one feature, pandas.Series of the distances if one of the inputs contains multiple features.

Return type:

float or pandas.Series

tobac.analysis.spatial.calculate_velocity(track, method_distance=None)

Calculate the velocities of a set of linked features.

Parameters:

• track (pandas.DataFrame) –

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

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

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

Returns:

track – DataFrame from the input, with an additional column ‘v’, contain the value of the velocity for every feature at every possible timestep

Return type:

pandas.DataFrame

tobac.analysis.spatial.calculate_velocity_individual(feature_old, feature_new, method_distance=None)

Calculate the mean velocity of a feature between two timeframes.

Parameters:

• feature_old (pandas.Series) – pandas.Series of a feature at a certain timeframe. Needs to contain a ‘time’ column and either projection_x_coordinate and projection_y_coordinate or latitude and longitude coordinates.

• feature_new (pandas.Series) – pandas.Series of the same feature at a later timeframe. Needs to contain a ‘time’ column and either projection_x_coordinate and projection_y_coordinate or latitude and longitude coordinates.

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

Returns:

velocity – Value of the approximate velocity.

Return type:

float

tobac.analysis.spatial.haversine(lat1, lon1, lat2, lon2)

Computes the Haversine distance in kilometers.

Calculates the Haversine distance between two points (based on implementation CIS https://github.com/cedadev/cis).

Parameters:

• lat1 (array of latitude, longitude) – First point or points as array in degrees.

• lon1 (array of latitude, longitude) – First point or points as array in degrees.

• lat2 (array of latitude, longitude) – Second point or points as array in degrees.

• lon2 (array of latitude, longitude) – Second point or points as array in degrees.

Returns:

arclen * RADIUS_EARTH – Array of Distance(s) between the two points(-arrays) in kilometers.

Return type:

array

tobac.centerofgravity module

Identify center of gravity and mass for analysis.

tobac.centerofgravity.calculate_cog(tracks, mass, mask)

Calculate center of gravity and mass for each tracked cell.

Parameters:

• tracks (pandas.DataFrame) – DataFrame containing trajectories of cell centers.

• mass (iris.cube.Cube) – Cube of quantity (need coordinates ‘time’, ‘geopotential_height’,’projection_x_coordinate’ and ‘projection_y_coordinate’).

• mask (iris.cube.Cube) – Cube containing mask (int > where belonging to area/volume of feature, 0 else).

Returns:

tracks_out – Dataframe containing t, x, y, z positions of center of gravity and total mass of each tracked cell at each timestep.

Return type:

pandas.DataFrame

tobac.centerofgravity.calculate_cog_domain(mass)

Calculate center of gravity and mass for entire domain.

Parameters:

mass (iris.cube.Cube) – Cube of quantity (need coordinates ‘time’, ‘geopotential_height’,’projection_x_coordinate’ and ‘projection_y_coordinate’).

Returns:

tracks_out – Dataframe containing t, x, y, z positions of center of gravity and total mass of the entire domain.

Return type:

pandas.DataFrame

tobac.centerofgravity.calculate_cog_untracked(mass, mask)

Calculate center of gravity and mass for untracked domain parts.

Parameters:

• mass (iris.cube.Cube) – Cube of quantity (need coordinates ‘time’, ‘geopotential_height’,’projection_x_coordinate’ and ‘projection_y_coordinate’).

• mask (iris.cube.Cube) – Cube containing mask (int > where belonging to area/volume of feature, 0 else).

Returns:

tracks_out – Dataframe containing t, x, y, z positions of center of gravity and total mass for untracked part of the domain.

Return type:

pandas.DataFrame

tobac.centerofgravity.center_of_gravity(cube_in)

Calculate center of gravity and sum of quantity.

Parameters:

cube_in (iris.cube.Cube) – Cube (potentially masked) of quantity (need coordinates ‘geopotential_height’,’projection_x_coordinate’ and ‘projection_y_coordinate’).

Returns:

• x (float) – X position of center of gravity.

• y (float) – Y position of center of gravity.

• z (float) – Z position of center of gravity.

• variable_sum (float) – Sum of quantity of over unmasked part of the cube.

tobac.feature_detection module

Provide feature detection.

This module can work with any two-dimensional field. To identify the features, contiguous regions above or below a threshold are determined and labelled individually. To describe the specific location of the feature at a specific point in time, different spatial properties are used to describe the identified region. [2]_

References

tobac.feature_detection.feature_detection_multithreshold(field_in: iris.cube.Cube, dxy: float = None, threshold: list[float] = None, min_num: int = 0, target: typing_extensions.Literal[maximum, minimum] = 'maximum', position_threshold: typing_extensions.Literal[center, extreme, weighted_diff, weighted abs] = 'center', sigma_threshold: float = 0.5, n_erosion_threshold: int = 0, n_min_threshold: int = 0, min_distance: float = 0, feature_number_start: int = 1, PBC_flag: typing_extensions.Literal[none, hdim_1, hdim_2, both] = 'none', vertical_coord: str = None, vertical_axis: int = None, detect_subset: dict = None, wavelength_filtering: tuple = None, dz: float | None = None, strict_thresholding: bool = False, statistic: dict[str, ~typing.Callable | tuple[~typing.Callable, dict]] | None = None) → pandas.DataFrame

Perform feature detection based on contiguous regions.

The regions are above/below a threshold.

Parameters:

• field_in (iris.cube.Cube) – 2D field to perform the tracking on (needs to have coordinate ‘time’ along one of its dimensions),

• dxy (float) – Grid spacing of the input data (in meter).

• thresholds (list of floats, optional) – Threshold values used to select target regions to track. The feature detection is inclusive of the threshold value(s), i.e. values greater/less than or equal are included in the target region. Default is None.

• target ({'maximum', 'minimum'}, optional) – Flag to determine if tracking is targetting minima or maxima in the data. Default is ‘maximum’.

• position_threshold ({'center', 'extreme', 'weighted_diff',) – ‘weighted_abs’}, optional Flag choosing method used for the position of the tracked feature. Default is ‘center’.

• sigma_threshold (float, optional) – Standard deviation for intial filtering step. Default is 0.5.

• n_erosion_threshold (int, optional) – Number of pixels by which to erode the identified features. Default is 0.

• n_min_threshold (int, optional) – Minimum number of identified contiguous pixels for a feature to be detected. Default is 0.

• min_distance (float, optional) – Minimum distance between detected features (in meters). Default is 0.

• feature_number_start (int, optional) – Feature id to start with. Default is 1.

• PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

• vertical_coord (str) – Name of the vertical coordinate. If None, tries to auto-detect. It looks for the coordinate or the dimension name corresponding to the string.

• vertical_axis (int or None.) – The vertical axis number of the data. If None, uses vertical_coord to determine axis. This must be >=0.

• detect_subset (dict-like or None) – Whether to run feature detection on only a subset of the data. If this is not None, it will subset the grid that we run feature detection on to the range specified for each axis specified. The format of this dict is: {axis-number: (start, end)}, where axis-number is the number of the axis to subset, start is inclusive, and end is exclusive. For example, if your data are oriented as (time, z, y, x) and you want to only detect on values between z levels 10 and 29, you would set: {1: (10, 30)}.

• wavelength_filtering (tuple, optional) – Minimum and maximum wavelength for horizontal spectral filtering in meter. Default is None.

• dz (float) – Constant vertical grid spacing (m), optional. If not specified and the input is 3D, this function requires that altitude is available in the features input. If you specify a value here, this function assumes that it is the constant z spacing between points, even if `z_coordinate_name` is specified.

• strict_thresholding (Bool, optional) – If True, a feature can only be detected if all previous thresholds have been met. Default is False.

Returns:

features – Detected features. The structure of this dataframe is explained here

Return type:

pandas.DataFrame

tobac.feature_detection.feature_detection_multithreshold_timestep(data_i: ~numpy.array, i_time: int, threshold: list[float] | None = None, min_num: int = 0, target: typing_extensions.Literal[maximum, minimum] = 'maximum', position_threshold: typing_extensions.Literal[center, extreme, weighted_diff, weighted abs] = 'center', sigma_threshold: float = 0.5, n_erosion_threshold: int = 0, n_min_threshold: int = 0, min_distance: float = 0, feature_number_start: int = 1, PBC_flag: typing_extensions.Literal[none, hdim_1, hdim_2, both] = 'none', vertical_axis: int | None = None, dxy: float = -1, wavelength_filtering: tuple[float] | None = None, strict_thresholding: bool = False, statistic: dict[str, ~typing.Callable | tuple[~typing.Callable, dict]] | None = None) → pandas.DataFrame

Find features in each timestep.

Based on iteratively finding regions above/below a set of thresholds. Smoothing the input data with the Gaussian filter makes output less sensitive to noisiness of input data.

Parameters:

• data_i (iris.cube.Cube) – 3D field to perform the feature detection (single timestep) on.

• i_time (int) – Number of the current timestep.

• threshold (list of floats, optional) – Threshold value used to select target regions to track. The feature detection is inclusive of the threshold value(s), i.e. values greater/less than or equal are included in the target region. Default is None.

• min_num (int, optional) – This parameter is not used in the function. Default is 0.

• target ({'maximum', 'minimum'}, optinal) – Flag to determine if tracking is targetting minima or maxima in the data. Default is ‘maximum’.

• position_threshold ({'center', 'extreme', 'weighted_diff',) – ‘weighted_abs’}, optional Flag choosing method used for the position of the tracked feature. Default is ‘center’.

• sigma_threshold (float, optional) – Standard deviation for intial filtering step. Default is 0.5.

• n_erosion_threshold (int, optional) – Number of pixels by which to erode the identified features. Default is 0.

• n_min_threshold (int, optional) – Minimum number of identified contiguous pixels for a feature to be detected. Default is 0.

• min_distance (float, optional) – Minimum distance between detected features (in meters). Default is 0.

• feature_number_start (int, optional) – Feature id to start with. Default is 1.

• PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

• vertical_axis (int) – The vertical axis number of the data.

• dxy (float) – Grid spacing in meters.

• wavelength_filtering (tuple, optional) – Minimum and maximum wavelength for spectral filtering in meters. Default is None.

• strict_thresholding (Bool, optional) – If True, a feature can only be detected if all previous thresholds have been met. Default is False.

• statistic (dict, optional) – Default is None. Optional parameter to calculate bulk statistics within feature detection. Dictionary with callable function(s) to apply over the region of each detected feature and the name of the statistics to appear in the feature ou tput dataframe. The functions should be the values and the names of the metric the keys (e.g. {‘mean’: np.mean})

Returns:

features_threshold – Detected features for individual timestep.

Return type:

pandas DataFrame

tobac.feature_detection.feature_detection_threshold(data_i: array, i_time: int, threshold: float | None = None, min_num: int = 0, target: typing_extensions.Literal[maximum, minimum] = 'maximum', position_threshold: typing_extensions.Literal[center, extreme, weighted_diff, weighted_abs] = 'center', sigma_threshold: float = 0.5, n_erosion_threshold: int = 0, n_min_threshold: int = 0, min_distance: float = 0, idx_start: int = 0, PBC_flag: typing_extensions.Literal[none, hdim_1, hdim_2, both] = 'none', vertical_axis: int = 0) → tuple[pandas.DataFrame, dict]

Find features based on individual threshold value.

Parameters:

• data_i (np.array) – 2D or 3D field to perform the feature detection (single timestep) on.

• i_time (int) – Number of the current timestep.

• threshold (float, optional) – Threshold value used to select target regions to track. The feature detection is inclusive of the threshold value(s), i.e. values greater/less than or equal are included in the target region. The feature detection is inclusive of the threshold value(s), i.e. values greater/less than or equal are included in the target region. Default is None.

• target ({'maximum', 'minimum'}, optional) – Flag to determine if tracking is targetting minima or maxima in the data. Default is ‘maximum’.

• position_threshold ({'center', 'extreme', 'weighted_diff',) – ‘weighted_abs’}, optional Flag choosing method used for the position of the tracked feature. Default is ‘center’.

• sigma_threshold (float, optional) – Standard deviation for intial filtering step. Default is 0.5.

• n_erosion_threshold (int, optional) – Number of pixels by which to erode the identified features. Default is 0.

• n_min_threshold (int, optional) – Minimum number of identified contiguous pixels for a feature to be detected. Default is 0.

• min_distance (float, optional) – Minimum distance between detected features (in meters). Default is 0.

• idx_start (int, optional) – Feature id to start with. Default is 0.

• PBC_flag ({'none', 'hdim_1', 'hdim_2', 'both'}) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

• vertical_axis (int) – The vertical axis number of the data.

Returns:

• features_threshold (pandas DataFrame) – Detected features for individual threshold.

• regions (dict) – Dictionary containing the regions above/below threshold used for each feature (feature ids as keys).

tobac.feature_detection.feature_position(hdim1_indices: list[int], hdim2_indices: list[int], vdim_indices: list[int] | None = None, region_small: ~numpy.ndarray | None = None, region_bbox: list[int] | tuple[int] | None = None, track_data: ~numpy.ndarray | None = None, threshold_i: float | None = None, position_threshold: typing_extensions.Literal[center, extreme, weighted_diff, weighted abs] = 'center', target: typing_extensions.Literal[maximum, minimum] | None = None, PBC_flag: typing_extensions.Literal[none, hdim_1, hdim_2, both] = 'none', hdim1_min: int = 0, hdim1_max: int = 0, hdim2_min: int = 0, hdim2_max: int = 0) → tuple[float]

Determine feature position with regard to the horizontal dimensions in pixels from the identified region above threshold values

Parameters:

• hdim1_indices (list) – indices of pixels in region along first horizontal dimension

• hdim2_indices (list) – indices of pixels in region along second horizontal dimension

• vdim_indices (list, optional) – List of indices of feature along optional vdim (typically `z`)

• region_small (2D or 3D array-like) – A true/false array containing True where the threshold is met and false where the threshold isn’t met. This array should be the the size specified by region_bbox, and can be a subset of the overall input array (i.e., `track_data`).

• region_bbox (list or tuple with length of 4 or 6) – The coordinates that region_small occupies within the total track_data array. This is in the order that the coordinates come from the `get_label_props_in_dict` function. For 2D data, this should be: (hdim1 start, hdim 2 start, hdim 1 end, hdim 2 end). For 3D data, this is: (vdim start, hdim1 start, hdim 2 start, vdim end, hdim 1 end, hdim 2 end).

• track_data (2D or 3D array-like) – 2D or 3D array containing the data

• threshold_i (float) – The threshold value that we are testing against

• position_threshold ({'center', 'extreme', 'weighted_diff', ') –

  weighted abs’} How to select the single point position from our data. ‘center’ picks the geometrical centre of the region, and is typically not recommended. ‘extreme’ picks the maximum or minimum value inside the region (max/min set by

  `target`) ‘weighted_diff’ picks the centre of the region weighted by the distance from the threshold value

  ’weighted_abs’ picks the centre of the region weighted by the absolute values of the field

• target ({'maximum', 'minimum'}) – Used only when position_threshold is set to ‘extreme’, this sets whether it is looking for maxima or minima.

• PBC_flag ({'none', 'hdim_1', 'hdim_2', 'both'}) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

• hdim1_min (int) – Minimum real array index of the first horizontal dimension (for PBCs)

• hdim1_max (int) – Maximum real array index of the first horizontal dimension (for PBCs) Note that this coordinate is INCLUSIVE, meaning that this is the maximum coordinate value, and it is not a length.

• hdim2_min (int) – Minimum real array index of the first horizontal dimension (for PBCs)

• hdim2_max (int) – Maximum real array index of the first horizontal dimension (for PBCs) Note that this coordinate is INCLUSIVE, meaning that this is the maximum coordinate value, and it is not a length.

Returns:

If input data is 2D, this will be a 2-element tuple of floats, where the first element is the feature position along the first horizontal dimension and the second element is the feature position along the second horizontal dimension. If input data is 3D, this will be a 3-element tuple of floats, where the first element is the feature position along the vertical dimension and the second two elements are the feature position on the first and second horizontal dimensions. Note for PBCs: this point can be >hdim1_max or hdim2_max if the point is between hdim1_max and hdim1_min. For example, if a feature lies exactly between hdim1_max and hdim1_min, the output could be between hdim1_max and hdim1_max+1. While a value between hdim1_min-1 and hdim1_min would also be valid, we choose to overflow on the max side of things.

Return type:

2-element or 3-element tuple of floats

tobac.feature_detection.filter_min_distance(features: pandas.DataFrame, dxy: float | None = None, dz: float | None = None, min_distance: float | None = None, x_coordinate_name: str | None = None, y_coordinate_name: str | None = None, z_coordinate_name: str | None = None, target: typing_extensions.Literal[maximum, minimum] = 'maximum', PBC_flag: typing_extensions.Literal[none, hdim_1, hdim_2, both] = 'none', min_h1: int = 0, max_h1: int = 0, min_h2: int = 0, max_h2: int = 0) → pandas.DataFrame

Function to remove features that are too close together. If two features are closer than min_distance, it keeps the larger feature.

Parameters:

• features (pandas DataFrame) – features

• dxy (float) – Constant horzontal grid spacing (meters).

• dz (float) – Constant vertical grid spacing (meters), optional. If not specified and the input is 3D, this function requires that z_coordinate_name is available in the features input. If you specify a value here, this function assumes that it is the constant z spacing between points, even if `z_coordinate_name` is specified.

• min_distance (float) – minimum distance between detected features (meters)

• x_coordinate_name (str) – The name of the x coordinate to calculate distance based on in meters. This is typically projection_x_coordinate. Currently unused.

• y_coordinate_name (str) – The name of the y coordinate to calculate distance based on in meters. This is typically projection_y_coordinate. Currently unused.

• z_coordinate_name (str or None) – The name of the z coordinate to calculate distance based on in meters. This is typically altitude. If None, tries to auto-detect.

• target ({'maximum', 'minimum'}, optional) – Flag to determine if tracking is targeting minima or maxima in the data. Default is ‘maximum’.

• PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

• min_h1 (int, optional) – Minimum real point in hdim_1, for use with periodic boundaries.

• max_h1 (int, optional) – Maximum point in hdim_1, exclusive. max_h1-min_h1 should be the size.

• min_h2 (int, optional) – Minimum real point in hdim_2, for use with periodic boundaries.

• max_h2 (int, optional) – Maximum point in hdim_2, exclusive. max_h2-min_h2 should be the size.

Returns:

features after filtering

Return type:

pandas DataFrame

tobac.feature_detection.remove_parents(features_thresholds: pandas.DataFrame, regions_i: dict, regions_old: dict, strict_thresholding: bool = False) → pandas.DataFrame

Remove parents of newly detected feature regions.

Remove features where its regions surround newly detected feature regions.

Parameters:

• features_thresholds (pandas.DataFrame) – Dataframe containing detected features.

• regions_i (dict) – Dictionary containing the regions greater/lower than and equal to threshold for the newly detected feature (feature ids as keys).

• regions_old (dict) – Dictionary containing the regions greater/lower than and equal to threshold from previous threshold (feature ids as keys).

• strict_thresholding (Bool, optional) – If True, a feature can only be detected if all previous thresholds have been met. Default is False.

Returns:

features_thresholds – Dataframe containing detected features excluding those that are superseded by newly detected ones.

Return type:

pandas.DataFrame

tobac.feature_detection.test_overlap(region_inner: list[tuple[int]], region_outer: list[tuple[int]]) → bool

Test for overlap between two regions

Parameters:

• region_1 (list) – list of 2-element tuples defining the indices of all cell in the region

• region_2 (list) – list of 2-element tuples defining the indices of all cell in the region

Returns:

overlap – True if there are any shared points between the two regions

Return type:

bool

tobac.merge_split module

Tobac merge and split This submodule is a post processing step to address tracked cells which merge/split. The first iteration of this module is to combine the cells which are merging but have received a new cell id (and are considered a new cell) once merged. In general this submodule will label merged/split cells with a TRACK number in addition to its CELL number.

tobac.merge_split.merge_split_MEST(TRACK, dxy, distance=None, frame_len=5)

function to postprocess tobac track data for merge/split cells using a minimum euclidian spanning tree

Parameters:

• TRACK (pandas.core.frame.DataFrame) – Pandas dataframe of tobac Track information

• dxy (float, mandatory) – The x/y grid spacing of the data. Should be in meters.

distancefloat, optional

Distance threshold determining how close two features must be in order to consider merge/splitting. Default is 25x the x/y grid spacing of the data, given in dxy. The distance should be in units of meters.

frame_lenfloat, optional

Threshold for the maximum number of frames that can separate the end of cell and the start of a related cell. Default is five (5) frames.

Returns:

d –

xarray dataset of tobac merge/split cells with parent and child designations.

Parent/child variables include:

• cell_parent_track_id: The associated track id for each cell. All cells that have merged or split will have the same parent track id. If a cell never merges/splits, only one cell will have a particular track id.

• feature_parent_cell_id: The associated parent cell id for each feature. All features in a given cell will have the same cell id. This is the original TRACK cell_id.

• feature_parent_track_id: The associated parent track id for each feature. This is not the same as the cell id number.

• track_child_cell_count: The total number of features belonging to all child cells of a given track id.

• cell_child_feature_count: The total number of features for each cell.

Return type:

xarray.core.dataset.Dataset

Example usage:

d = merge_split_MEST(Track) ds = tobac.utils.standardize_track_dataset(Track, refl_mask) both_ds = xr.merge([ds, d],compat =’override’) both_ds = tobac.utils.compress_all(both_ds) both_ds.to_netcdf(os.path.join(savedir,’Track_features_merges.nc’))

tobac.plotting module

Provide methods for plotting analyzed data.

Plotting routines including both visualizations for the entire dataset including all tracks, and detailed visualizations for individual cells and their properties.

References

tobac.plotting.animation_mask_field(track, features, field, mask, interval=500, figsize=(10, 10), **kwargs)

Create animation of field, features and segments of all timeframes.

Parameters:

• track (pandas.DataFrame) – Output of linking_trackpy.

• features (pandas.DataFrame) – Output of the feature detection.

• field (iris.cube.Cube) – Original input data.

• mask (iris.cube.Cube) – Cube containing mask (int id for tacked volumes 0 everywhere else), output of the segmentation step.

• interval (int, optional) – Delay between frames in milliseconds. Default is 500.

• figsize (tupel of float, optional) – Width, height of the plot in inches. Default is (10, 10).

• **kwargs –

Returns:

animation – Created animation as object.

Return type:

matplotlib.animation.FuncAnimation

tobac.plotting.make_map(axes)

Configure the parameters of cartopy for plotting.

Parameters:

axes (cartopy.mpl.geoaxes.GeoAxesSubplot) – GeoAxesSubplot to configure.

Returns:

axes – Cartopy axes to configure

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

tobac.plotting.map_tracks(track, axis_extent=None, figsize=None, axes=None, untracked_cell_value=-1)

Plot the trajectories of the cells on a map.

Parameters:

• track (pandas.DataFrame) – Dataframe containing the linked features with a column ‘cell’.

• axis_extent (matplotlib.axes, optional) – Array containing the bounds of the longitude and latitude values. The structure is [long_min, long_max, lat_min, lat_max]. Default is None.

• figsize (tuple of floats, optional) – Width, height of the plot in inches. Default is (10, 10).

• axes (cartopy.mpl.geoaxes.GeoAxesSubplot, optional) – GeoAxesSubplot to use for plotting. Default is None.

• untracked_cell_value (int or np.nan, optional) – Value of untracked cells in track[‘cell’]. Default is -1.

Returns:

axes – Axes with the plotted trajectories.

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

Raises:

ValueError – If no axes is passed.

tobac.plotting.plot_histogram_cellwise(track, bin_edges, variable, quantity, axes=None, density=False, **kwargs)

Plot the histogram of a variable based on the cells.

Parameters:

• track (pandas.DataFrame) – DataFrame of the features containing the variable as column and a column ‘cell’.

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

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

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

• axes (matplotlib.axes.Axes, optional) – Matplotlib axes to plot on. Default is None.

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

• **kwargs –

Returns:

plot_hist – List containing the matplotlib.lines.Line2D instance of the histogram

Return type:

list

tobac.plotting.plot_histogram_featurewise(Track, bin_edges, variable, axes=None, density=False, **kwargs)

Plot the histogram of a variable based on the features.

Parameters:

• Track (pandas.DataFrame) – DataFrame of the features containing the variable as column.

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

• variable (str) – Column of the DataFrame with the variable on which the histogram is to be based on.

• axes (matplotlib.axes.Axes, optional) – Matplotlib axes to plot on. Default is None.

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

• **kwargs –

Returns:

plot_hist – List containing the matplotlib.lines.Line2D instance of the histogram

Return type:

list

tobac.plotting.plot_lifetime_histogram(track, axes=None, bin_edges=array([0, 20, 40, 60, 80, 100, 120, 140, 160, 180]), density=False, **kwargs)

Plot the liftetime histogram of the cells.

Parameters:

• track (pandas.DataFrame) – DataFrame of the features containing the columns ‘cell’ and ‘time_cell’.

• axes (matplotlib.axes.Axes, optional) – Matplotlib axes to plot 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 sequence, it defines a monotonically increasing array of bin edges, including the rightmost edge. 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.

• **kwargs –

Returns:

plot_hist – List containing the matplotlib.lines.Line2D instance of the histogram

Return type:

list

tobac.plotting.plot_lifetime_histogram_bar(track, axes=None, bin_edges=array([0, 20, 40, 60, 80, 100, 120, 140, 160, 180]), density=False, width_bar=1, shift=0.5, **kwargs)

Plot the liftetime histogram of the cells as bar plot.

Parameters:

• track (pandas.DataFrame) – DataFrame of the features containing the columns ‘cell’ and ‘time_cell’.

• axes (matplotlib.axes.Axes, optional) – Matplotlib axes to plot 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 sequence, it defines a monotonically increasing array of bin edges, including the rightmost edge.

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

• width_bar (float) – Width of the bars. Default is 1.

• shift (float) – Value to shift the bin centers to the right. Default is 0.5.

• **kwargs –

Returns:

plot_hist – matplotlib.container.BarContainer instance of the histogram

Return type:

matplotlib.container.BarContainer

tobac.plotting.plot_mask_cell_individual_3Dstatic(cell_i, track, cog, features, mask_total, field_contour, field_filled, axes=None, xlim=None, ylim=None, label_field_contour=None, cmap_field_contour='Blues', norm_field_contour=None, linewidths_contour=0.8, contour_labels=False, vmin_field_contour=0, vmax_field_contour=50, levels_field_contour=None, nlevels_field_contour=10, label_field_filled=None, cmap_field_filled='summer', norm_field_filled=None, vmin_field_filled=0, vmax_field_filled=100, levels_field_filled=None, nlevels_field_filled=10, title=None, feature_number=False, ele=10.0, azim=210.0)

Make plots for cell in fixed frame and with one background field as filling and one background field as contrours Input: Output:

tobac.plotting.plot_mask_cell_individual_follow(cell_i, track, cog, features, mask_total, field_contour, field_filled, axes=None, width=10000, label_field_contour=None, cmap_field_contour='Blues', norm_field_contour=None, linewidths_contour=0.8, contour_labels=False, vmin_field_contour=0, vmax_field_contour=50, levels_field_contour=None, nlevels_field_contour=10, label_field_filled=None, cmap_field_filled='summer', norm_field_filled=None, vmin_field_filled=0, vmax_field_filled=100, levels_field_filled=None, nlevels_field_filled=10, title=None)

Make individual plot for cell centred around cell and with one background field as filling and one background field as contrours Input: Output:

tobac.plotting.plot_mask_cell_individual_static(cell_i, track, cog, features, mask_total, field_contour, field_filled, axes=None, xlim=None, ylim=None, label_field_contour=None, cmap_field_contour='Blues', norm_field_contour=None, linewidths_contour=0.8, contour_labels=False, vmin_field_contour=0, vmax_field_contour=50, levels_field_contour=None, nlevels_field_contour=10, label_field_filled=None, cmap_field_filled='summer', norm_field_filled=None, vmin_field_filled=0, vmax_field_filled=100, levels_field_filled=None, nlevels_field_filled=10, title=None, feature_number=False)

Make plots for cell in fixed frame and with one background field as filling and one background field as contrours Input: Output:

tobac.plotting.plot_mask_cell_track_2D3Dstatic(cell, track, cog, features, mask_total, field_contour, field_filled, width=10000, n_extend=1, name='test', plotdir='./', file_format=['png'], figsize=(3.937007874015748, 3.937007874015748), dpi=300, ele=10, azim=30, **kwargs)

Make plots for all cells with fixed frame including entire development of the cell and with one background field as filling and one background field as contrours Input: Output:

tobac.plotting.plot_mask_cell_track_3Dstatic(cell, track, cog, features, mask_total, field_contour, field_filled, width=10000, n_extend=1, name='test', plotdir='./', file_format=['png'], figsize=(3.937007874015748, 3.937007874015748), dpi=300, **kwargs)

Make plots for all cells with fixed frame including entire development of the cell and with one background field as filling and one background field as contrours Input: Output:

tobac.plotting.plot_mask_cell_track_follow(cell, track, cog, features, mask_total, field_contour, field_filled, width=10000, name='test', plotdir='./', file_format=['png'], figsize=(3.937007874015748, 3.937007874015748), dpi=300, **kwargs)

Make plots for all cells centred around cell and with one background field as filling and one background field as contrours Input: Output:

tobac.plotting.plot_mask_cell_track_static(cell, track, cog, features, mask_total, field_contour, field_filled, width=10000, n_extend=1, name='test', plotdir='./', file_format=['png'], figsize=(3.937007874015748, 3.937007874015748), dpi=300, **kwargs)

Make plots for all cells with fixed frame including entire development of the cell and with one background field as filling and one background field as contrours Input: Output:

tobac.plotting.plot_mask_cell_track_static_timeseries(cell, track, cog, features, mask_total, field_contour, field_filled, track_variable=None, variable=None, variable_ylabel=None, variable_label=[None], variable_legend=False, variable_color=None, width=10000, n_extend=1, name='test', plotdir='./', file_format=['png'], figsize=(7.874015748031496, 3.937007874015748), dpi=300, **kwargs)

Make plots for all cells with fixed frame including entire development of the cell and with one background field as filling and one background field as contrours Input: Output:

tobac.plotting.plot_tracks_mask_field(track, field, mask, features, axes=None, axis_extent=None, plot_outline=True, plot_marker=True, marker_track='x', markersize_track=4, plot_number=True, plot_features=False, marker_feature=None, markersize_feature=None, title=None, title_str=None, vmin=None, vmax=None, n_levels=50, cmap='viridis', extend='neither', orientation_colorbar='horizontal', pad_colorbar=0.05, label_colorbar=None, fraction_colorbar=0.046, rasterized=True, linewidth_contour=1)

Plot field, features and segments of a timeframe and on a map projection. It is required to pass vmin, vmax, axes and axis_extent as keyword arguments.

Parameters:

• track (pandas.DataFrame) – One or more timeframes of a dataframe generated by linking_trackpy.

• field (iris.cube.Cube) – One frame/time step of the original input data.

• mask (iris.cube.Cube) – One frame/time step of the Cube containing mask (int id for tracked volumes 0 everywhere else), output of the segmentation step.

• features (pandas.DataFrame) – Output of the feature detection, one or more frames/time steps.

• axes (cartopy.mpl.geoaxes.GeoAxesSubplot) – GeoAxesSubplot to use for plotting. Default is None.

• axis_extent (ndarray) – Array containing the bounds of the longitude and latitude values. The structure is [long_min, long_max, lat_min, lat_max]. Default is None.

• plot_outline (bool, optional) – Boolean defining whether the outlines of the segments are plotted. Default is True.

• plot_marker (bool, optional) – Boolean defining whether the positions of the features from the track dataframe are plotted. Default is True.

• marker_track (str, optional) – String defining the shape of the marker for the feature positions from the track dataframe. Default is ‘x’.

• markersize_track (int, optional) – Int defining the size of the marker for the feature positions from the track dataframe. Default is 4.

• plot_number (bool, optional) – Boolean defining wether the index of the cells is plotted next to the individual feature position. Default is True.

• plot_features (bool, optional) – Boolean defining wether the positions of the features from the features dataframe are plotted. Default is True.

• marker_feature (optional) – String defining the shape of the marker for the feature positions from the features dataframe. Default is None.

• markersize_feature (optional) – Int defining the size of the marker for the feature positions from the features dataframe. Default is None.

• title (str, optional) – Flag determining the title of the plot. ‘datestr’ uses date and time of the field. None sets not title. Default is None.

• title_str (str, optional) – Additional string added to the beginning of the title. Default is None.

• vmin (float) – Lower bound of the colorbar. Default is None.

• vmax (float) – Upper bound of the colorbar. Default is None.

• n_levels (int, optional) – Number of levels of the contour plot of the field. Default is 50.

• cmap ({'viridis',...}, optional) – Colormap of the countour plot of the field. matplotlib.colors. Default is ‘viridis’.

• extend (str, optional) – Determines the coloring of values that are outside the levels range. If ‘neither’, values outside the levels range are not colored. If ‘min’, ‘max’ or ‘both’, color the values below, above or below and above the levels range. Values below min(levels) and above max(levels) are mapped to the under/over values of the Colormap. Default is ‘neither’.

• orientation_colorbar (str, optional) – Orientation of the colorbar, ‘horizontal’ or ‘vertical’ Default is ‘horizontal’.

• pad_colorbar (float, optional) – Fraction of original axes between colorbar and new image axes. Default is 0.05.

• label_colorbar (str, optional) – Label of the colorbar. If none, name and unit of the field are used. Default is None.

• fraction_colorbar (float, optional) – Fraction of original axes to use for colorbar. Default is 0.046.

• rasterized (bool, optional) – True enables, False disables rasterization. Default is True.

• linewidth_contour (int, optional) – Linewidth of the contour plot of the segments. Default is 1.

Returns:

axes – Axes with the plot.

Return type:

cartopy.mpl.geoaxes.GeoAxesSubplot

Raises:

ValueError – If axes are not cartopy.mpl.geoaxes.GeoAxesSubplot. If mask.ndim is neither 2 nor 3.

tobac.plotting.plot_tracks_mask_field_loop(track, field, mask, features, axes=None, name=None, plot_dir='./', figsize=(3.937007874015748, 3.937007874015748), dpi=300, margin_left=0.05, margin_right=0.05, margin_bottom=0.05, margin_top=0.05, **kwargs)

Plot field, feature positions and segments onto individual maps for all timeframes and save them as pngs.

Parameters:

• track (pandas.DataFrame) – Output of linking_trackpy.

• field (iris.cube.Cube) – Original input data.

• mask (iris.cube.Cube) – Cube containing mask (int id for tacked volumes, 0 everywhere else). Output of the segmentation step.

• features (pandas.DataFrame) – Output of the feature detection.

• axes (cartopy.mpl.geoaxes.GeoAxesSubplot, optional) – Not used. Default is None.

• name (str, optional) – Filename without file extension. Same for all pngs. If None, the name of the field is used. Default is None.

• plot_dir (str, optional) – Path where the plots will be saved. Default is ‘./’.

• figsize (tuple of floats, optional) – Width, height of the plot in inches. Default is (10/2.54, 10/2.54).

• dpi (int, optional) – Plot resolution. Default is 300.

• margin_left (float, optional) – The position of the left edge of the axes, as a fraction of the figure width. Default is 0.05.

• margin_right (float, optional) – The position of the right edge of the axes, as a fraction of the figure width. Default is 0.05.

• margin_bottom (float, optional) – The position of the bottom edge of the axes, as a fraction of the figure width. Default is 0.05.

• margin_top (float, optional) – The position of the top edge of the axes, as a fraction of the figure width. Default is 0.05.

• **kwargs –

Return type:

None

tobac.segmentation module

Provide segmentation techniques.

Segmentation techniques are used to associate areas or volumes to each identified feature. The segmentation is implemented using watershedding techniques from the field of image processing with a fixed threshold value. This value has to be set specifically for every type of input data and application. The segmentation can be performed for both two-dimensional and three-dimensional data. At each timestep, a marker is set at the position (weighted mean center) of each feature identified in the detection step in an array otherwise filled with zeros. In case of the three-dimentional watershedding, all cells in the column above the weighted mean center position of the identified features fulfilling the threshold condition are set to the respective marker. The algorithm then fills the area (2D) or volume (3D) based on the input field starting from these markers until reaching the threshold. If two or more features are directly connected, the border runs along the watershed line between the two regions. This procedure creates a mask that has the same form as the input data, with the corresponding integer number at all grid points that belong to a feature, else with zero. This mask can be conveniently and efficiently used to select the volume of each feature at a specific time step for further analysis or visialization.

References

tobac.segmentation.add_markers(features: pandas.DataFrame, marker_arr: array, seed_3D_flag: typing_extensions.Literal[column, box], seed_3D_size: int | tuple[int] = 5, level: None | slice = None, PBC_flag: typing_extensions.Literal[none, hdim_1, hdim_2, both] = 'none') → array

Adds markers for watershedding using the features dataframe to the marker_arr.

Parameters:

• features (pandas.DataFrame) – Features for one point in time to add as markers.

• marker_arr (2D or 3D array-like) – Array to add the markers to. Assumes a (z, y, x) configuration.

• seed_3D_flag (str('column', 'box')) – Seed 3D field at feature positions with either the full column or a box of user-set size

• seed_3D_size (int or tuple (dimensions equal to dimensions of field)) – This sets the size of the seed box when seed_3D_flag is ‘box’. If it’s an integer (units of number of pixels), the seed box is identical in all dimensions. If it’s a tuple, it specifies the seed area for each dimension separately, in units of pixels. Note: we strongly recommend the use of odd numbers for this. If you give an even number, your seed box will be biased and not centered around the feature. Note: if two seed boxes overlap, the feature that is seeded will be the closer feature.

• level (slice or None) – If seed_3D_flag is ‘column’, the levels at which to seed the cells for the watershedding algorithm. If None, seeds all levels.

• PBC_flag ({'none', 'hdim_1', 'hdim_2', 'both'}) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

Returns:

The marker array

Return type:

2D or 3D array like (same type as marker_arr)

tobac.segmentation.check_add_unseeded_across_bdrys(dim_to_run: str, segmentation_mask: array, unseeded_labels: array, border_min: int, border_max: int, markers_arr: array, inplace: bool = True) → array

Add new markers to unseeded but eligible regions when they are bordering an appropriate boundary.

Parameters:

• dim_to_run ({'hdim_1', 'hdim_2'}) – what dimension to run

• segmentation_mask (np.array) – the incomming segmentation mask

• unseeded_labels (np.array) – The list of labels that are unseeded

• border_min (int) – minimum real point in the dimension we are running on

• border_max (int) – maximum real point in the dimension we are running on (inclusive)

• markers_arr (np.array) – The array of markers to re-run segmentation with

• inplace (bool) – whether or not to modify markers_arr in place

Return type:

markers_arr with new markers added

tobac.segmentation.segmentation(features: pandas.DataFrame, field: iris.cube.Cube, dxy: float, threshold: float = 0.003, target: typing_extensions.Literal[maximum, minimum] = 'maximum', level: None | slice = None, method: typing_extensions.Literal[watershed] = 'watershed', max_distance: None | float = None, vertical_coord: str | None = None, PBC_flag: typing_extensions.Literal[none, hdim_1, hdim_2, both] = 'none', seed_3D_flag: typing_extensions.Literal[column, box] = 'column', seed_3D_size: int | tuple[int] = 5, segment_number_below_threshold: int = 0, segment_number_unassigned: int = 0, statistic: dict[str, Callable | tuple[Callable, dict]] | None = None) → tuple[iris.cube.Cube, pandas.DataFrame]

Use watershedding to determine region above a threshold value around initial seeding position for all time steps of the input data. Works both in 2D (based on single seeding point) and 3D and returns a mask with zeros everywhere around the identified regions and the feature id inside the regions.

Calls segmentation_timestep at each individal timestep of the input data.

Parameters:

• features (pandas.DataFrame) – Output from trackpy/maketrack.

• field (iris.cube.Cube) – Containing the field to perform the watershedding on.

• dxy (float) – Grid spacing of the input data in meters.

• threshold (float, optional) – Threshold for the watershedding field to be used for the mask. Default is 3e-3.

• target ({'maximum', 'minimum'}, optional) – Flag to determine if tracking is targetting minima or maxima in the data. Default is ‘maximum’.

• level (slice of iris.cube.Cube, optional) – Levels at which to seed the cells for the watershedding algorithm. Default is None.

• method ({'watershed'}, optional) – Flag determining the algorithm to use (currently watershedding implemented). ‘random_walk’ could be uncommented.

• max_distance (float, optional) – Maximum distance from a marker allowed to be classified as belonging to that cell in meters. Default is None.

• vertical_coord ({'auto', 'z', 'model_level_number', 'altitude',) – ‘geopotential_height’}, optional Name of the vertical coordinate for use in 3D segmentation case

• PBC_flag ({'none', 'hdim_1', 'hdim_2', 'both'}) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

• seed_3D_flag (str('column', 'box')) – Seed 3D field at feature positions with either the full column (default) or a box of user-set size

• seed_3D_size (int or tuple (dimensions equal to dimensions of field)) – This sets the size of the seed box when seed_3D_flag is ‘box’. If it’s an integer (units of number of pixels), the seed box is identical in all dimensions. If it’s a tuple, it specifies the seed area for each dimension separately, in units of pixels. Note: we strongly recommend the use of odd numbers for this. If you give an even number, your seed box will be biased and not centered around the feature. Note: if two seed boxes overlap, the feature that is seeded will be the closer feature.

• segment_number_below_threshold (int) – the marker to use to indicate a segmentation point is below the threshold.

• segment_number_unassigned (int) – the marker to use to indicate a segmentation point is above the threshold but unsegmented.

• statistic (dict, optional) – Default is None. Optional parameter to calculate bulk statistics within feature detection. Dictionary with callable function(s) to apply over the region of each detected feature and the name of the statistics to appear in the feature output dataframe. The functions should be the values and the names of the metric the keys (e.g. {‘mean’: np.mean})

Returns:

• segmentation_out (iris.cube.Cube) – Mask, 0 outside and integer numbers according to track inside the area/volume of the feature.

• features_out (pandas.DataFrame) – Feature dataframe including the number of cells (2D or 3D) in the segmented area/volume of the feature at the timestep.

Raises:

ValueError – If field_in.ndim is neither 3 nor 4 and ‘time’ is not included in coords.

tobac.segmentation.segmentation_2D(features, field, dxy, threshold=0.003, target='maximum', level=None, method='watershed', max_distance=None, PBC_flag='none', seed_3D_flag='column', statistic=None)

Wrapper for the segmentation()-function.

tobac.segmentation.segmentation_3D(features, field, dxy, threshold=0.003, target='maximum', level=None, method='watershed', max_distance=None, PBC_flag='none', seed_3D_flag='column', statistic=None)

Wrapper for the segmentation()-function.

tobac.segmentation.segmentation_timestep(field_in: iris.cube.Cube, features_in: pandas.DataFrame, dxy: float, threshold: float = 0.003, target: typing_extensions.Literal[maximum, minimum] = 'maximum', level: None | slice = None, method: typing_extensions.Literal[watershed] = 'watershed', max_distance: None | float = None, vertical_coord: str | None = None, PBC_flag: typing_extensions.Literal[none, hdim_1, hdim_2, both] = 'none', seed_3D_flag: typing_extensions.Literal[column, box] = 'column', seed_3D_size: int | tuple[int] = 5, segment_number_below_threshold: int = 0, segment_number_unassigned: int = 0, statistic: dict[str, Callable | tuple[Callable, dict]] | None = None) → tuple[iris.cube.Cube, pandas.DataFrame]

Perform watershedding for an individual time step of the data. Works for both 2D and 3D data

Parameters:

• field_in (iris.cube.Cube) – Input field to perform the watershedding on (2D or 3D for one specific point in time).

• features_in (pandas.DataFrame) – Features for one specific point in time.

• dxy (float) – Grid spacing of the input data in metres

• threshold (float, optional) – Threshold for the watershedding field to be used for the mask. The watershedding is exclusive of the threshold value, i.e. values greater (less) than the threshold are included in the target region, while values equal to the threshold value are excluded. Default is 3e-3.

• target ({'maximum', 'minimum'}, optional) – Flag to determine if tracking is targeting minima or maxima in the data to determine from which direction to approach the threshold value. Default is ‘maximum’.

• level (slice of iris.cube.Cube, optional) – Levels at which to seed the cells for the watershedding algorithm. Default is None.

• method ({'watershed'}, optional) – Flag determining the algorithm to use (currently watershedding implemented).

• max_distance (float, optional) – Maximum distance from a marker allowed to be classified as belonging to that cell in meters. Default is None.

• vertical_coord (str, optional) – Vertical coordinate in 3D input data. If None, input is checked for one of {‘z’, ‘model_level_number’, ‘altitude’,’geopotential_height’} as a likely coordinate name

• PBC_flag ({'none', 'hdim_1', 'hdim_2', 'both'}) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

• seed_3D_flag (str('column', 'box')) – Seed 3D field at feature positions with either the full column (default) or a box of user-set size

• seed_3D_size (int or tuple (dimensions equal to dimensions of field)) – This sets the size of the seed box when seed_3D_flag is ‘box’. If it’s an integer (units of number of pixels), the seed box is identical in all dimensions. If it’s a tuple, it specifies the seed area for each dimension separately, in units of pixels. Note: we strongly recommend the use of odd numbers for this. If you give an even number, your seed box will be biased and not centered around the feature. Note: if two seed boxes overlap, the feature that is seeded will be the closer feature.

• segment_number_below_threshold (int) – the marker to use to indicate a segmentation point is below the threshold.

• segment_number_unassigned (int) – the marker to use to indicate a segmentation point is above the threshold but unsegmented. This can be the same as segment_number_below_threshold, but can also be set separately.

• statistics (boolean, optional) – Default is None. If True, bulk statistics for the data points assigned to each feature are saved in output.

Returns:

• segmentation_out (iris.cube.Cube) – Mask, 0 outside and integer numbers according to track inside the ojects.

• features_out (pandas.DataFrame) – Feature dataframe including the number of cells (2D or 3D) in the segmented area/volume of the feature at the timestep.

Raises:

ValueError – If target is neither ‘maximum’ nor ‘minimum’. If vertical_coord is not in {‘auto’, ‘z’, ‘model_level_number’, ‘altitude’, geopotential_height’}. If there is more than one coordinate name. If the spatial dimension is neither 2 nor 3. If method is not ‘watershed’.

tobac.segmentation.watershedding_2D(track, field_in, **kwargs)

Wrapper for the segmentation()-function.

tobac.segmentation.watershedding_3D(track, field_in, **kwargs)

Wrapper for the segmentation()-function.

tobac.testing module

Containing methods to make simple sample data for testing.

tobac.testing.generate_grid_coords(min_max_coords, lengths)

Generates a grid of coordinates, such as fake lat/lons for testing.

Parameters:

• min_max_coords (array-like, either length 2, length 4, or length 6.) – The minimum and maximum values in each dimension as: (min_dim1, max_dim1, min_dim2, max_dim2, min_dim3, max_dim3) to use all 3 dimensions. You can omit any dimensions that you aren’t using.

• lengths (array-like, either length 1, 2, or 3.) – The lengths of values in each dimension. Length must equal 1/2 the length of min_max_coords.

Returns:

array-like of grid coordinates in the number of dimensions requested and with the number of arrays specified (meshed coordinates)

Return type:

1, 2, or 3 array-likes

tobac.testing.generate_single_feature(start_h1, start_h2, start_v=None, spd_h1=1, spd_h2=1, spd_v=1, min_h1=0, max_h1=None, min_h2=0, max_h2=None, num_frames=1, dt=datetime.timedelta(seconds=300), start_date=datetime.datetime(2022, 1, 1, 0, 0), PBC_flag='none', frame_start=0, feature_num=1, feature_size=None, threshold_val=None)

Function to generate a dummy feature dataframe to test the tracking functionality

Parameters:

• start_h1 (float) – Starting point of the feature in hdim_1 space

• start_h2 (float) – Starting point of the feature in hdim_2 space

• start_v (float, optional) – Starting point of the feature in vdim space (if 3D). For 2D, set to None. Default is None

• spd_h1 (float, optional) – Speed (per frame) of the feature in hdim_1 Default is 1

• spd_h2 (float, optional) – Speed (per frame) of the feature in hdim_2 Default is 1

• spd_v (float, optional) – Speed (per frame) of the feature in vdim Default is 1

• min_h1 (int, optional) – Minimum value of hdim_1 allowed. If PBC_flag is not ‘none’, then this will be used to know when to wrap around periodic boundaries. If PBC_flag is ‘none’, features will disappear if they are above/below these bounds. Default is 0

• max_h1 (int, optional) – Similar to min_h1, but the max value of hdim_1 allowed. Default is 1000

• min_h2 (int, optional) – Similar to min_h1, but the minimum value of hdim_2 allowed. Default is 0

• max_h2 (int, optional) – Similar to min_h1, but the maximum value of hdim_2 allowed. Default is 1000

• num_frames (int, optional) – Number of frames to generate Default is 1

• dt (datetime.timedelta, optional) – Difference in time between each frame Default is datetime.timedelta(minutes=5)

• start_date (datetime.datetime, optional) – Start datetime Default is datetime.datetime(2022, 1, 1, 0)

• PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

• frame_start (int) – Number to start the frame at Default is 1

• feature_num (int, optional) – What number to start the feature at Default is 1

• feature_size (int or None) – ‘num’ column in output; feature size If None, doesn’t set this column

• threshold_val (float or None) – Threshold value of this feature

tobac.testing.get_single_pbc_coordinate(h1_min, h1_max, h2_min, h2_max, h1_coord, h2_coord, PBC_flag='none')

Function to get the PBC-adjusted coordinate for an original non-PBC adjusted coordinate.

Parameters:

• h1_min (int) – Minimum point in hdim_1

• h1_max (int) – Maximum point in hdim_1

• h2_min (int) – Minimum point in hdim_2

• h2_max (int) – Maximum point in hdim_2

• h1_coord (int) – hdim_1 query coordinate

• h2_coord (int) – hdim_2 query coordinate

• PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

Returns:

Returns a tuple of (hdim_1, hdim_2).

Return type:

tuple

Raises:

ValueError – Raises a ValueError if the point is invalid (e.g., h1_coord < h1_min when PBC_flag = ‘none’)

tobac.testing.get_start_end_of_feat(center_point, size, axis_min, axis_max, is_pbc=False)

Gets the start and ending points for a feature given a size and PBC conditions

Parameters:

• center_point (float) – The center point of the feature

• size (float) – The size of the feature in this dimension

• axis_min (int) – Minimum point on the axis (usually 0)

• axis_max (int) – Maximum point on the axis (exclusive). This is 1 after the last real point on the axis, such that axis_max - axis_min is the size of the axis

• is_pbc (bool) – True if we should give wrap around points, false if we shouldn’t.

Returns:

• tuple (start_point, end_point)

• Note that if is_pbc is True, start_point can be less than axis_min and

• end_point can be greater than or equal to axis_max. This is designed to be used with

• `get_pbc_coordinates`

tobac.testing.lists_equal_without_order(a, b)

This will make sure the inner list contain the same, but doesn’t account for duplicate groups. from: https://stackoverflow.com/questions/31501909/assert-list-of-list-equality-without-order-in-python/31502000

tobac.testing.make_dataset_from_arr(in_arr, data_type='xarray', time_dim_num=None, z_dim_num=None, z_dim_name='altitude', y_dim_num=0, x_dim_num=1)

Makes a dataset (xarray or iris) for feature detection/segmentation from a raw numpy/dask/etc. array.

Parameters:

• in_arr (array-like) – The input array to convert to iris/xarray

• data_type (str('xarray' or 'iris'), optional) – Type of the dataset to return Default is ‘xarray’

• time_dim_num (int or None, optional) – What axis is the time dimension on, None for a single timestep Default is None

• z_dim_num (int or None, optional) – What axis is the z dimension on, None for a 2D array

• z_dim_name (str) – What the z dimension name is named

• y_dim_num (int) – What axis is the y dimension on, typically 0 for a 2D array Default is 0

• x_dim_num (int, optional) – What axis is the x dimension on, typically 1 for a 2D array Default is 1

Return type:

Iris or xarray dataset with everything we need for feature detection/tracking.

tobac.testing.make_feature_blob(in_arr, h1_loc, h2_loc, v_loc=None, h1_size=1, h2_size=1, v_size=1, shape='rectangle', amplitude=1, PBC_flag='none')

Function to make a defined “blob” in location (zloc, yloc, xloc) with user-specified shape and amplitude. Note that this function will round the size and locations to the nearest point within the array.

Parameters:

• in_arr (array-like) – input array to add the “blob” to

• h1_loc (float) – Center hdim_1 location of the blob, required

• h2_loc (float) – Center hdim_2 location of the blob, required

• v_loc (float, optional) – Center vdim location of the blob, optional. If this is None, we assume that the dataset is 2D. Default is None

• h1_size (float, optional) – Size of the bubble in array coordinates in hdim_1 Default is 1

• h2_size (float, optional) – Size of the bubble in array coordinates in hdim_2 Default is 1

• v_size (float, optional) – Size of the bubble in array coordinates in vdim Default is 1

• shape (str('rectangle'), optional) – The shape of the blob that is added. For now, this is just rectangle ‘rectangle’ adds a rectangular/rectangular prism bubble with constant amplitude amplitude. Default is “rectangle”

• amplitude (float, optional) – Maximum amplitude of the blob Default is 1

• PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

Returns:

An array with the same type as in_arr that has the blob added.

Return type:

array-like

tobac.testing.make_sample_data_2D_3blobs(data_type='iris')

Create a simple dataset to use in tests.

The grid has a grid spacing of 1km in both horizontal directions and 100 grid cells in x direction and 200 in y direction. Time resolution is 1 minute and the total length of the dataset is 100 minutes around a arbitrary date (2000-01-01 12:00). The longitude and latitude coordinates are added as 2D aux coordinates and arbitrary, but in realisitic range. The data contains three individual blobs travelling on a linear trajectory through the dataset for part of the time.

Parameters:

data_type ({'iris', 'xarray'}, optional) – Choose type of the dataset that will be produced. Default is ‘iris’

Returns:

sample_data

Return type:

iris.cube.Cube or xarray.DataArray

tobac.testing.make_sample_data_2D_3blobs_inv(data_type='iris')

Create a version of the dataset with switched coordinates.

Create a version of the dataset created in the function make_sample_cube_2D, but with switched coordinate order for the horizontal coordinates for tests to ensure that this does not affect the results.

Parameters:

data_type ({'iris', 'xarray'}, optional) – Choose type of the dataset that will be produced. Default is ‘iris’

Returns:

sample_data

Return type:

iris.cube.Cube or xarray.DataArray

tobac.testing.make_sample_data_3D_3blobs(data_type='iris', invert_xy=False)

Create a simple dataset to use in tests.

The grid has a grid spacing of 1km in both horizontal directions and 100 grid cells in x direction and 200 in y direction. Time resolution is 1 minute and the total length of the dataset is 100 minutes around a abritraty date (2000-01-01 12:00). The longitude and latitude coordinates are added as 2D aux coordinates and arbitrary, but in realisitic range. The data contains three individual blobs travelling on a linear trajectory through the dataset for part of the time.

Parameters:

• data_type ({'iris', 'xarray'}, optional) – Choose type of the dataset that will be produced. Default is ‘iris’

• invert_xy (bool, optional) – Flag to determine wether to switch x and y coordinates Default is False

Returns:

sample_data

Return type:

iris.cube.Cube or xarray.DataArray

tobac.testing.make_simple_sample_data_2D(data_type='iris')

Create a simple dataset to use in tests.

The grid has a grid spacing of 1km in both horizontal directions and 100 grid cells in x direction and 500 in y direction. Time resolution is 1 minute and the total length of the dataset is 100 minutes around a abritraty date (2000-01-01 12:00). The longitude and latitude coordinates are added as 2D aux coordinates and arbitrary, but in realisitic range. The data contains a single blob travelling on a linear trajectory through the dataset for part of the time.

Parameters:

data_type ({'iris', 'xarray'}, optional) – Choose type of the dataset that will be produced. Default is ‘iris’

Returns:

sample_data

Return type:

iris.cube.Cube or xarray.DataArray

tobac.testing.set_arr_2D_3D(in_arr, value, start_h1, end_h1, start_h2, end_h2, start_v=None, end_v=None)

Function to set part of in_arr for either 2D or 3D points to value. If start_v and end_v are not none, we assume that the array is 3D. If they are none, we will set the array as if it is a 2D array.

Parameters:

• in_arr (array-like) – Array of values to set

• value (int, float, or array-like of size (end_v-start_v, end_h1-start_h1, end_h2-start_h2)) – The value to assign to in_arr. This will work to assign an array, but the array must have the same dimensions as the size specified in the function.

• start_h1 (int) – Start index to set for hdim_1

• end_h1 (int) – End index to set for hdim_1 (exclusive, so it acts like [start_h1:end_h1])

• start_h2 (int) – Start index to set for hdim_2

• end_h2 (int) – End index to set for hdim_2

• start_v (int, optional) – Start index to set for vdim Default is None

• end_v (int, optional) – End index to set for vdim Default is None

Returns:

in_arr with the new values set.

Return type:

array-like

tobac.tracking module

Provide tracking methods.

The individual features and associated area/volumes identified in each timestep have to be linked into trajectories to analyse the time evolution of their properties for a better understanding of the underlying physical processes. The implementations are structured in a way that allows for the future addition of more complex tracking methods recording a more complex network of relationships between features at different points in time.

References

tobac.tracking.add_cell_time(t: pandas.DataFrame, cell_number_unassigned: int)

add cell time as time since the initiation of each cell

Parameters:

• t (pandas.DataFrame) – trajectories with added coordinates

• cell_number_unassigned (int) – unassigned cell value

Returns:

t – trajectories with added cell time

Return type:

pandas.Dataframe

tobac.tracking.build_distance_function(min_h1, max_h1, min_h2, max_h2, PBC_flag)

Function to build a partial `calc_distance_coords_pbc` function suitable for use with trackpy

Parameters:

• min_h1 (int) – Minimum point in hdim_1

• max_h1 (int) – Maximum point in hdim_1

• min_h2 (int) – Minimum point in hdim_2

• max_h2 (int) – Maximum point in hdim_2

• PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

Returns:

A version of calc_distance_coords_pbc suitable to be called by just f(coords_1, coords_2)

Return type:

function object

tobac.tracking.fill_gaps(t, order=1, extrapolate=0, frame_max=None, hdim_1_max=None, hdim_2_max=None)

Add cell time as time since the initiation of each cell.

Parameters:

• t (pandas.DataFrame) – Trajectories from trackpy.

• order (int, optional) – Order of polynomial used to extrapolate trajectory into gaps and beyond start and end point. Default is 1.

• extrapolate (int, optional) – Number or timesteps to extrapolate trajectories. Default is 0.

• frame_max (int, optional) – Size of input data along time axis. Default is None.

• hdim_1_max (int, optional) – Size of input data along first and second horizontal axis. Default is None.

• hdim2_max (int, optional) – Size of input data along first and second horizontal axis. Default is None.

Returns:

t – Trajectories from trackpy with with filled gaps and potentially extrapolated.

Return type:

pandas.DataFrame

tobac.tracking.linking_trackpy(features, field_in, dt, dxy, dz=None, v_max=None, d_max=None, d_min=None, subnetwork_size=None, memory=0, stubs=1, time_cell_min=None, order=1, extrapolate=0, method_linking='random', adaptive_step=None, adaptive_stop=None, cell_number_start=1, cell_number_unassigned=-1, vertical_coord='auto', min_h1=None, max_h1=None, min_h2=None, max_h2=None, PBC_flag='none')

Perform Linking of features in trajectories.

The linking determines which of the features detected in a specific timestep is most likely identical to an existing feature in the previous timestep. For each existing feature, the movement within a time step is extrapolated based on the velocities in a number previous time steps. The algorithm then breaks the search process down to a few candidate features by restricting the search to a circular search region centered around the predicted position of the feature in the next time step. For newly initialized trajectories, where no velocity from previous time steps is available, the algorithm resorts to the average velocity of the nearest tracked objects. v_max and d_min are given as physical quantities and then converted into pixel-based values used in trackpy. This allows for tracking that is controlled by physically-based parameters that are independent of the temporal and spatial resolution of the input data. The algorithm creates a continuous track for the feature that is the most probable based on the previous cell path.

Parameters:

• features (pandas.DataFrame) – Detected features to be linked.

• field_in (None) – Input field. Not currently used; can be set to None.

• dt (float) – Time resolution of tracked features in seconds.

• dxy (float) – Horizontal grid spacing of the input data in meters.

• dz (float) – Constant vertical grid spacing (meters), optional. If not specified and the input is 3D, this function requires that vertical_coord is available in the features input. If you specify a value here, this function assumes that it is the constant z spacing between points, even if `vertical_coord` is specified.

• d_max (float, optional) – Maximum search range in meters. Only one of d_max, d_min, or v_max can be set. Default is None.

• d_min (float, optional) – Deprecated. Only one of d_max, d_min, or v_max can be set. Default is None.

• subnetwork_size (int, optional) – Maximum size of subnetwork for linking. This parameter should be adjusted when using adaptive search. Usually a lower value is desired in that case. For a more in depth explanation have look here If None, 30 is used for regular search and 15 for adaptive search. Default is None.

• v_max (float, optional) – Speed at which features are allowed to move in meters per second. Only one of d_max, d_min, or v_max can be set. Default is None.

• memory (int, optional) –

  Number of output timesteps features allowed to vanish for to be still considered tracked. Default is 0. .. warning :: This parameter should be used with caution, as it

  can lead to erroneous trajectory linking, espacially for data with low time resolution.

• stubs (int, optional) – Minimum number of timesteps of a tracked cell to be reported Default is 1

• time_cell_min (float, optional) – Minimum length in time that a cell must be tracked for to be considered a valid cell in seconds. Default is None.

• order (int, optional) – Order of polynomial used to extrapolate trajectory into gaps and ond start and end point. Default is 1.

• extrapolate (int, optional) – Number or timesteps to extrapolate trajectories. Currently unused. Default is 0.

• method_linking ({'random', 'predict'}, optional) – Flag choosing method used for trajectory linking. Default is ‘random’, although we typically encourage users to use ‘predict’.

• adaptive_step (float, optional) – Reduce search range by multiplying it by this factor. Needs to be used in combination with adaptive_stop. Default is None.

• adaptive_stop (float, optional) – If not None, when encountering an oversize subnet, retry by progressively reducing search_range by multiplying with adaptive_step until the subnet is solvable. If search_range becomes <= adaptive_stop, give up and raise a SubnetOversizeException. Needs to be used in combination with adaptive_step. Default is None.

• cell_number_start (int, optional) – Cell number for first tracked cell. Default is 1

• cell_number_unassigned (int) – Number to set the unassigned/non-tracked cells to. Note that if you set this to np.nan, the data type of ‘cell’ will change to float. Default is -1

• vertical_coord (str) – Name of the vertical coordinate. The vertical coordinate used must be meters. If None, tries to auto-detect. It looks for the coordinate or the dimension name corresponding to the string. To use dz, set this to None.

• min_h1 (int) – Minimum hdim_1 value, required when PBC_flag is ‘hdim_1’ or ‘both’

• max_h1 (int) – Maximum hdim_1 value, required when PBC_flag is ‘hdim_1’ or ‘both’

• min_h2 (int) – Minimum hdim_2 value, required when PBC_flag is ‘hdim_2’ or ‘both’

• max_h2 (int) – Maximum hdim_2 value, required when PBC_flag is ‘hdim_2’ or ‘both’

• PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

Returns:

trajectories_final – Dataframe of the linked features, containing the variable ‘cell’, with integers indicating the affiliation of a feature to a specific track, and the variable ‘time_cell’ with the time the cell has already existed.

Return type:

pandas.DataFrame

Raises:

ValueError – If method_linking is neither ‘random’ nor ‘predict’.

tobac.tracking.remap_particle_to_cell_nv(particle_cell_map, input_particle)

Remaps the particles to new cells given an input map and the current particle. Helper function that is designed to be vectorized with np.vectorize

Parameters:

• particle_cell_map (dict-like) – The dictionary mapping particle number to cell number

• input_particle (key for particle_cell_map) – The particle number to remap

tobac.utils modules

tobac.utils.bulk_statistics module

Support functions to compute bulk statistics of features, either as a postprocessing step or within feature detection or segmentation.

tobac.utils.bulk_statistics.get_statistics(features: pandas.DataFrame, labels: ~numpy.ndarray[int], *fields: tuple[~numpy.ndarray], statistic: dict[str, ~typing.Callable | tuple[~typing.Callable, dict]] = {'ncells': <function count_nonzero>}, index: list[int] | None = None, default: None | float = None, id_column: str = 'feature', collapse_axis: None | int | list[int] = None) → pandas.DataFrame

Get bulk statistics for objects (e.g. features or segmented features) given a labelled mask of the objects and any input field with the same dimensions or that can be broadcast with labels according to numpy-like broadcasting rules.

The statistics are added as a new column to the existing feature dataframe. Users can specify which statistics are computed by providing a dictionary with the column name of the metric and the respective function.

Parameters:

• features (pd.DataFrame) – Dataframe with features or segmented features (output from feature detection or segmentation), which can be for the specific timestep or for the whole dataset

• labels (np.ndarray[int]) – Mask with labels of each regions to apply function to (e.g. output of segmentation for a specific timestep)

• *fields (tuple[np.ndarray]) – Fields to give as arguments to each function call. If the shape does not match that of labels, numpy-style broadcasting will be applied.

• statistic (dict[str, Callable], optional (default: {'ncells':np.count_nonzero})) – Dictionary with function(s) to apply over each region as values and the name of the respective statistics as keys. Default is to just count the number of cells associated with each feature and write it to the feature dataframe.

• index (None | list[int], optional (default: None)) – list of indices of regions in labels to apply function to. If None, will default to all integer feature labels in labels.

• default (None | float, optional (default: None)) – default value to return in a region that has no values.

• id_column (str, optional (default: "feature")) – Name of the column in feature dataframe that contains IDs that match with the labels in mask. The default is the column “feature”.

• collapse_axis (None | int | list[int], optional (default: None):) – Index or indices of axes of labels to collapse. This will reduce the dimensionality of labels while allowing labelled features to overlap. This can be used, for example, to calculate the footprint area (2D) of 3D labels

Returns:

features – Updated feature dataframe with bulk statistics for each feature saved in a new column.

Return type:

pd.DataFrame

tobac.utils.bulk_statistics.get_statistics_from_mask(features: pandas.DataFrame, segmentation_mask: xarray.DataArray, *fields: xarray.DataArray, statistic: dict[str, tuple[~typing.Callable]] = {'Mean': <function mean>}, index: None | list[int] = None, default: None | float = None, id_column: str = 'feature', collapse_dim: None | str | list[str] = None) → pandas.DataFrame

Derives bulk statistics for each object in the segmentation mask, and returns a features Dataframe with these properties for each feature.

Parameters:

• features (pd.DataFrame) – Dataframe with segmented features (output from feature detection or segmentation). Timesteps must not be exactly the same as in segmentation mask but all labels in the mask need to be present in the feature dataframe.

• segmentation_mask (xr.DataArray) – Segmentation mask output

• *fields (xr.DataArray[np.ndarray]) – Field(s) with input data. If field does not have a time dimension it will be considered time invariant, and the entire field will be passed for each time step in segmentation_mask. If the shape does not match that of labels, numpy-style broadcasting will be applied.

• statistic (dict[str, Callable], optional (default: {'ncells':np.count_nonzero})) – Dictionary with function(s) to apply over each region as values and the name of the respective statistics as keys. Default is to calculate the mean value of the field over each feature.

• index (None | list[int], optional (default: None)) – list of indexes of regions in labels to apply function to. If None, will default to all integers between 1 and the maximum value in labels

• default (None | float, optional (default: None)) – default value to return in a region that has no values

• id_column (str, optional (default: "feature")) – Name of the column in feature dataframe that contains IDs that match with the labels in mask. The default is the column “feature”.

• collapse_dim (None | str | list[str], optional (defailt: None)) –

  Dimension names of labels to collapse, allowing, e.g. calulcation of statistics on 2D

  fields for the footprint of 3D objects

  features: pd.DataFrame

  Updated feature dataframe with bulk statistics for each feature saved in a new column

tobac.utils.decorators module

Decorators for use with other tobac functions

tobac.utils.decorators.convert_cube_to_dataarray(cube)

Convert an iris cube to an xarray dataarray, averting error for integer dtype cubes in xarray<v2023.06

Parameters:

cube (iris.cube.Cube) – Iris data cube

Returns:

dataarray – dataarray converted from cube. If the cube’s core data is a masked array and has integer dtype, the returned datarray will have a numpy array with masked values filled with the minimum value for that integer dtype. Otherwise the data will be identical to that produced using xr.DataArray.from_iris

Return type:

xr.DataArray

tobac.utils.decorators.iris_to_xarray(save_iris_info: bool = False)

tobac.utils.decorators.irispandas_to_xarray(save_iris_info: bool = False)

tobac.utils.decorators.njit_if_available(func, **kwargs)

Decorator to wrap a function with numba.njit if available. If numba isn’t available, it just returns the function.

Parameters:

• func (function object) – Function to wrap with njit

• kwargs – Keyword arguments to pass to numba njit

tobac.utils.decorators.xarray_to_iris()

tobac.utils.decorators.xarray_to_irispandas()

tobac.utils.general module

General tobac utilities

tobac.utils.general.add_coordinates(t, variable_cube)

Add coordinates from the input cube of the feature detection to the trajectories/features.

Parameters:

• t (pandas.DataFrame) – Trajectories/features from feature detection or linking step.

• variable_cube (iris.cube.Cube) – Input data used for the tracking with coordinate information to transfer to the resulting DataFrame. Needs to contain the coordinate ‘time’.

Returns:

t – Trajectories with added coordinates.

Return type:

pandas.DataFrame

tobac.utils.general.add_coordinates_3D(t, variable_cube, vertical_coord=None, vertical_axis=None, assume_coords_fixed_in_time=True)

Function adding coordinates from the tracking cube to the trajectories

for the 3D case: time, longitude&latitude, x&y dimensions, and altitude

Parameters:

• t (pandas DataFrame) – trajectories/features

• variable_cube (iris.cube.Cube) – Cube (usually the one you are tracking on) at least conaining the dimension of ‘time’. Typically, ‘longitude’,’latitude’,’x_projection_coordinate’,’y_projection_coordinate’, and ‘altitude’ (if 3D) are the coordinates that we expect, although this function will happily interpolate along any dimension coordinates you give.

• vertical_coord (str or int) – Name or axis number of the vertical coordinate. If None, tries to auto-detect. If it is a string, it looks for the coordinate or the dimension name corresponding to the string. If it is an int, it assumes that it is the vertical axis. Note that if you only have a 2D or 3D coordinate for altitude, you must pass in an int.

• vertical_axis (int or None) – Axis number of the vertical.

• assume_coords_fixed_in_time (bool) – If true, it assumes that the coordinates are fixed in time, even if the coordinates say they vary in time. This is, by default, True, to preserve legacy functionality. If False, it assumes that if a coordinate says it varies in time, it takes the coordinate at its word.

Returns:

trajectories with added coordinates

Return type:

pandas DataFrame

tobac.utils.general.combine_feature_dataframes(feature_df_list, renumber_features=True, old_feature_column_name=None, sort_features_by=None)

Function to combine a list of tobac feature detection dataframes into one combined dataframe that can be used for tracking or segmentation. :param feature_df_list: A list of dataframes (generated, for example, by

running feature detection on multiple nodes).

Parameters:

• renumber_features (bool, optional (default: True)) – If true, features are renumber with contiguous integers. If false, the old feature numbers will be retained, but an exception will be raised if there are any non-unique feature numbers. If you have non-unique feature numbers and want to preserve them, use the old_feature_column_name to save the old feature numbers to under a different column name.

• old_feature_column_name (str or None, optional (default: None)) – The column name to preserve old feature numbers in. If None, these old numbers will be deleted. Users may want to enable this feature if they have run segmentation with the separate dataframes and therefore old feature numbers.

• sort_features_by (list, str or None, optional (default: None)) – The sorting order to pass to Dataframe.sort_values for the merged dataframe. If None, will default to [“frame”, “idx”] if renumber_features is True, or “feature” if renumber_features is False.

Returns:

One combined DataFrame.

Return type:

pd.DataFrame

tobac.utils.general.combine_tobac_feats(list_of_feats, preserve_old_feat_nums=None)

WARNING: This function has been deprecated and will be removed in a future release, please use ‘combine_feature_dataframes’ instead

Function to combine a list of tobac feature detection dataframes into one combined dataframe that can be used for tracking or segmentation. :param list_of_feats: A list of dataframes (generated, for example, by

running feature detection on multiple nodes).

Parameters:

preserve_old_feat_nums (str or None) – The column name to preserve old feature numbers in. If None, these old numbers will be deleted. Users may want to enable this feature if they have run segmentation with the separate dataframes and therefore old feature numbers.

Returns:

One combined DataFrame.

Return type:

pd.DataFrame

tobac.utils.general.get_bounding_box(x, buffer=1)

Finds the bounding box of a ndarray, i.e. the smallest bounding rectangle for nonzero values as explained here: https://stackoverflow.com/questions/31400769/bounding-box-of-numpy-array :param x: Array for which the bounding box is to be determined. :type x: numpy.ndarray :param buffer: Number to set a buffer between the nonzero values and

the edges of the box. Default is 1.

Returns:

bbox – Dimensionwise list of the indices representing the edges of the bounding box.

Return type:

list

tobac.utils.general.get_spacings(field_in, grid_spacing=None, time_spacing=None, average_method='arithmetic')

Determine spatial and temporal grid spacing of the input data.

Parameters:

• field_in (iris.cube.Cube) – Input field where to get spacings.

• grid_spacing (float, optional) – Manually sets the grid spacing if specified. Default is None.

• time_spacing (float, optional) – Manually sets the time spacing if specified. Default is None.

• average_method (string, optional) –

  Defines how spacings in x- and y-direction are combined.

  • ’arithmetic’ : standard arithmetic mean like (dx+dy)/2

  • ’geometric’ : geometric mean; conserves gridbox area

  Default is ‘arithmetic’.

Returns:

• dxy (float) – Grid spacing in metres.

• dt (float) – Time resolution in seconds.

Raises:

ValueError – If input_cube does not contain projection_x_coord and projection_y_coord or keyword argument grid_spacing.

tobac.utils.general.spectral_filtering(dxy, field_in, lambda_min, lambda_max, return_transfer_function=False)

This function creates and applies a 2D transfer function that can be used as a bandpass filter to remove certain wavelengths of an atmospheric input field (e.g. vorticity, IVT, etc).

Parameters:

dxyfloat

Grid spacing in m.

field_in: numpy.array

2D field with input data.

lambda_min: float

Minimum wavelength in m.

lambda_max: float

Maximum wavelength in m.

return_transfer_function: boolean, optional

default: False. If set to True, then the 2D transfer function and the corresponding wavelengths are returned.

Returns:

filtered_field: numpy.array

Spectrally filtered 2D field of data (with same shape as input data).

transfer_function: tuple

Two 2D fields, where the first one corresponds to the wavelengths in the spectral space of the domain and the second one to the 2D transfer function of the bandpass filter. Only returned, if return_transfer_function is True.

tobac.utils.general.standardize_track_dataset(TrackedFeatures, Mask, Projection=None)

CAUTION: this function is experimental. No data structures output are guaranteed to be supported in future versions of tobac. Combine a feature mask with the feature data table into a common dataset. returned by tobac.segmentation with the TrackedFeatures dataset returned by tobac.linking_trackpy. Also rename the variables to be more descriptive and comply with cf-tree. Convert the default cell parent ID to an integer table. Add a cell dimension to reflect Projection is an xarray DataArray TODO: Add metadata attributes :param TrackedFeatures: xarray dataset of tobac Track information, the xarray dataset returned by tobac.tracking.linking_trackpy :type TrackedFeatures: xarray.core.dataset.Dataset :param Mask: xarray dataset of tobac segmentation mask information, the xarray dataset returned

by tobac.segmentation.segmentation

Parameters:

Projection (xarray.core.dataarray.DataArray, default = None) – array.DataArray of the original input dataset (gridded nexrad data for example). If using gridded nexrad data, this can be input as: data[‘ProjectionCoordinateSystem’] An example of the type of information in the dataarray includes the following attributes: latitude_of_projection_origin :29.471900939941406 longitude_of_projection_origin :-95.0787353515625 _CoordinateTransformType :Projection _CoordinateAxes :x y z time _CoordinateAxesTypes :GeoX GeoY Height Time grid_mapping_name :azimuthal_equidistant semi_major_axis :6370997.0 inverse_flattening :298.25 longitude_of_prime_meridian :0.0 false_easting :0.0 false_northing :0.0

Returns:

ds – xarray dataset of merged Track and Segmentation Mask datasets with renamed variables.

Return type:

xarray.core.dataset.Dataset

tobac.utils.general.transform_feature_points(features, new_dataset, latitude_name=None, longitude_name=None, altitude_name=None, max_time_away=None, max_space_away=None, max_vspace_away=None, warn_dropped_features=True)

Function to transform input feature dataset horizontal grid points to a different grid. The typical use case for this function is to transform detected features to perform segmentation on a different grid.

The existing feature dataset must have some latitude/longitude coordinates associated with each feature, and the new_dataset must have latitude/longitude available with the same name. Note that due to xarray/iris incompatibilities, we suggest that the input coordinates match the standard_name from Iris.

Parameters:

• features (pd.DataFrame) – Input feature dataframe

• new_dataset (iris.cube.Cube or xarray) – The dataset to transform the

• latitude_name (str) – The name of the latitude coordinate. If None, tries to auto-detect.

• longitude_name (str) – The name of the longitude coordinate. If None, tries to auto-detect.

• altitude_name (str) – The name of the altitude coordinate. If None, tries to auto-detect.

• max_time_away (datetime.timedelta) – The maximum time delta to associate feature points away from.

• max_space_away (float) – The maximum horizontal distance (in meters) to transform features to.

• max_vspace_away (float) – The maximum vertical distance (in meters) to transform features to.

• warn_dropped_features (bool) – Whether or not to print a warning message if one of the max_* options is going to result in features that are dropped.

Returns:

transformed_features – A new feature dataframe, with the coordinates transformed to the new grid, suitable for use in segmentation

Return type:

pd.DataFrame

tobac.utils.mask module

Provide essential methods for masking

tobac.utils.mask.column_mask_from2D(mask_2D, cube, z_coord='model_level_number')

Turn 2D watershedding mask into a 3D mask of selected columns.

Parameters:

• cube (iris.cube.Cube) – Data cube.

• mask_2D (iris.cube.Cube) – 2D cube containing mask (int id for tacked volumes 0 everywhere else).

• z_coord (str) – Name of the vertical coordinate in the cube.

Returns:

mask_2D – 3D cube containing columns of 2D mask (int id for tracked volumes, 0 everywhere else).

Return type:

iris.cube.Cube

tobac.utils.mask.mask_all_surface(mask, masked=False, z_coord='model_level_number')

Create surface projection of 3d-mask for all features by collapsing one coordinate.

Parameters:

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

• masked (bool, optional) – Bool determining whether to mask the mask for the cell where it is 0. Default is False

• z_coord (str, optional) – Name of the coordinate to collapse. Default is ‘model_level_number’.

Returns:

mask_i_surface – Collapsed Masked cube for the features with the maximum value along the collapsed coordinate.

Return type:

iris.cube.Cube (2D)

tobac.utils.mask.mask_cell(mask, cell, track, masked=False)

Create mask for specific cell.

Parameters:

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

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

• track (pandas.DataFrame) – Output of the linking.

• masked (bool, optional) – Bool determining whether to mask the mask for the cell where it is 0. Default is False.

Returns:

mask_i – Mask for a specific cell.

Return type:

numpy.ndarray

tobac.utils.mask.mask_cell_surface(mask, cell, track, masked=False, z_coord='model_level_number')

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

Parameters:

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

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

• track (pandas.DataFrame) – Output of the linking.

• masked (bool, optional) – Bool determining whether to mask the mask for the cell where it is 0. Default is False.

• z_coord (str, optional) – Name of the coordinate to collapse. Default is ‘model_level_number’.

Returns:

mask_i_surface – Collapsed Masked cube for the cell with the maximum value along the collapsed coordinate.

Return type:

iris.cube.Cube

tobac.utils.mask.mask_cube(cube_in, mask)

Mask cube where mask is not zero.

Parameters:

• cube_in (iris.cube.Cube) – Unmasked data cube.

• mask (iris.cube.Cube) – Mask to use for masking, >0 where cube is supposed to be masked.

Returns:

variable_cube_out – Masked cube.

Return type:

iris.cube.Cube

tobac.utils.mask.mask_cube_all(variable_cube, mask)

Mask cube (iris.cube) for tracked volume.

Parameters:

• variable_cube (iris.cube.Cube) – Unmasked data cube.

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

Returns:

variable_cube_out – Masked cube for untracked volume.

Return type:

iris.cube.Cube

tobac.utils.mask.mask_cube_cell(variable_cube, mask, cell, track)

Mask cube for tracked volume of an individual cell.

Parameters:

• variable_cube (iris.cube.Cube) – Unmasked data cube.

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

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

• track (pandas.DataFrame) – Output of the linking.

Returns:

variable_cube_out – Masked cube with data for respective cell.

Return type:

iris.cube.Cube

tobac.utils.mask.mask_cube_features(variable_cube, mask, feature_ids)

Mask cube for tracked volume of one or more specific features.

Parameters:

• variable_cube (iris.cube.Cube) – Unmasked data cube.

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

• feature_ids (int or list of ints) – Integer ids of features to create masked cube for.

Returns:

variable_cube_out – Masked cube with data for respective features.

Return type:

iris.cube.Cube

tobac.utils.mask.mask_cube_untracked(variable_cube, mask)

Mask cube (iris.cube) for untracked volume.

Parameters:

• variable_cube (iris.cube.Cube) – Unmasked data cube.

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

Returns:

variable_cube_out – Masked cube for untracked volume.

Return type:

iris.cube.Cube

tobac.utils.mask.mask_features(mask, feature_ids, masked=False)

Create mask for specific features.

Parameters:

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

• feature_ids (int or list of ints) – Integer ids of the features to create the masked cube for.

• masked (bool, optional) – Bool determining whether to mask the mask for the cell where it is 0. Default is False.

Returns:

mask_i – Masked cube for specific features.

Return type:

numpy.ndarray

tobac.utils.mask.mask_features_surface(mask, feature_ids, masked=False, z_coord='model_level_number')

Create surface projection of 3d-mask for specific features by collapsing one coordinate.

Parameters:

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

• feature_ids (int or list of ints) – Integer ids of the features to create the masked cube for.

• masked (bool, optional) – Bool determining whether to mask the mask for the cell where it is 0. Default is False

• z_coord (str, optional) – Name of the coordinate to collapse. Default is ‘model_level_number’.

Returns:

mask_i_surface – Collapsed Masked cube for the features with the maximum value along the collapsed coordinate.

Return type:

iris.cube.Cube

tobac.utils.periodic_boundaries module

tobac.utils.periodic_boundaries.adjust_pbc_point(in_dim: int, dim_min: int, dim_max: int) → int

Function to adjust a point to the other boundary for PBCs

Parameters:

• in_dim (int) – Input coordinate to adjust

• dim_min (int) – Minimum point for the dimension

• dim_max (int) – Maximum point for the dimension (inclusive)

Returns:

The adjusted point on the opposite boundary

Return type:

int

Raises:

ValueError – If in_dim isn’t on one of the boundary points

tobac.utils.periodic_boundaries.calc_distance_coords_pbc(coords_1, coords_2, min_h1, max_h1, min_h2, max_h2, PBC_flag)

Function to calculate the distance between cartesian coordinate set 1 and coordinate set 2. Note that we assume both coordinates are within their min/max already.

Parameters:

• coords_1 (2D or 3D array-like) – Set of coordinates passed in from trackpy of either (vdim, hdim_1, hdim_2) coordinates or (hdim_1, hdim_2) coordinates.

• coords_2 (2D or 3D array-like) – Similar to coords_1, but for the second pair of coordinates

• min_h1 (int) – Minimum point in hdim_1

• max_h1 (int) – Maximum point in hdim_1, exclusive. max_h1-min_h1 should be the size.

• min_h2 (int) – Minimum point in hdim_2

• max_h2 (int) – Maximum point in hdim_2, exclusive. max_h2-min_h2 should be the size.

• PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

Returns:

Distance between coords_1 and coords_2 in cartesian space.

Return type:

float

tobac.utils.periodic_boundaries.get_pbc_coordinates(h1_min: int, h1_max: int, h2_min: int, h2_max: int, h1_start_coord: int, h1_end_coord: int, h2_start_coord: int, h2_end_coord: int, PBC_flag: str = 'none') → list[tuple[int, int, int, int]]

Function to get the real (i.e., shifted away from periodic boundaries) coordinate boxes of interest given a set of coordinates that may cross periodic boundaries. This computes, for example, multiple bounding boxes to encompass the real coordinates when given periodic coordinates that loop around to the other boundary.

For example, if you pass in [as h1_start_coord, h1_end_coord, h2_start_coord, h2_end_coord] (-3, 5, 2,6) with PBC_flag of ‘both’ or ‘hdim_1’, h1_max of 10, and h1_min of 0 this function will return: [(0,5,2,6), (7,10,2,6)].

If you pass in something outside the bounds of the array, this will truncate your requested box. For example, if you pass in [as h1_start_coord, h1_end_coord, h2_start_coord, h2_end_coord] (-3, 5, 2,6) with PBC_flag of ‘none’ or ‘hdim_2’, this function will return: [(0,5,2,6)], assuming h1_min is 0.

Parameters:

• h1_min (int) – Minimum array value in hdim_1, typically 0.

• h1_max (int) – Maximum array value in hdim_1 (exclusive). h1_max - h1_min should be the size in h1.

• h2_min (int) – Minimum array value in hdim_2, typically 0.

• h2_max (int) – Maximum array value in hdim_2 (exclusive). h2_max - h2_min should be the size in h2.

• h1_start_coord (int) – Start coordinate in hdim_1. Can be < h1_min if dealing with PBCs.

• h1_end_coord (int) – End coordinate in hdim_1. Can be >= h1_max if dealing with PBCs.

• h2_start_coord (int) – Start coordinate in hdim_2. Can be < h2_min if dealing with PBCs.

• h2_end_coord (int) – End coordinate in hdim_2. Can be >= h2_max if dealing with PBCs.

• PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

Returns:

A list of tuples containing (h1_start, h1_end, h2_start, h2_end) of each of the boxes needed to encompass the coordinates.

Return type:

list of tuples

tobac.utils.periodic_boundaries.transfm_pbc_point(in_dim, dim_min, dim_max)

Function to transform a PBC-feature point for contiguity

Parameters:

• in_dim (int) – Input coordinate to adjust

• dim_min (int) – Minimum point for the dimension

• dim_max (int) – Maximum point for the dimension (inclusive)

Returns:

The transformed point

Return type:

int

tobac.utils.periodic_boundaries.weighted_circmean(values: np.ndarray, weights: np.ndarray, high: float = 6.283185307179586, low: float = 0, axis: int | None = None) → np.ndarray

Calculate the weighted circular mean over a set of values. If all the weights are equal, this function is equivalent to scipy.stats.circmean

Parameters:

• values (array-like) – Array of values to calculate the mean over

• weights (array-like) – Array of weights corresponding to each value

• high (float, optional) – Upper bound of the range of values. Defaults to 2*pi

• low (float, optional) – Lower bound of the range of values. Defaults to 0

• axis (int | None, optional) – Axis over which to take the average. If None, the average will be taken over the entire array. Defaults to None

Returns:

rescaled_average – The weighted, circular mean over the given values

Return type:

numpy.ndarray

tobac.wrapper module

tobac.wrapper.maketrack(field_in, grid_spacing=None, time_spacing=None, target='maximum', v_max=None, d_max=None, memory=0, stubs=5, order=1, extrapolate=0, method_detection='threshold', position_threshold='center', sigma_threshold=0.5, n_erosion_threshold=0, threshold=1, min_num=0, min_distance=0, method_linking='random', cell_number_start=1, subnetwork_size=None, adaptive_stop=None, adaptive_step=None, return_intermediate=False)

tobac.wrapper.tracking_wrapper(field_in_features, field_in_segmentation, time_spacing=None, grid_spacing=None, parameters_features=None, parameters_tracking=None, parameters_segmentation=None)

Module contents