tobac.analysis.spatial#

Description

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, hdim1_coord=None, hdim2_coord=None, return_components=False, vertical_coord=None, use_3d=False)#

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.

  • hdim1_coord (str, optional (default: None)) – The names of the coordinates for the two horizontal dimensions to use. If None, tobac.utils.internal.general_internal.find_dataframe_horizontal_coords will be used to search for coordinate names present in both dataframes

  • hdim2_coord (str, optional (default: None)) – The names of the coordinates for the two horizontal dimensions to use. If None, tobac.utils.internal.general_internal.find_dataframe_horizontal_coords will be used to search for coordinate names present in both dataframes

  • return_components (bool, optional (default=False)) – Flag to control whether the velocity is calculated and returned as its vector components. If False, only the scalar (absolute) value is returned. If True, the function returns a dictionary containing the scalar value as well as its individual directional components (e.g., ‘vx’, ‘vy’, ‘vz’ for velocity).

  • vertical_coord (str, optional (default=None)) – Name of the column in the feature representing the vertical (z-axis) coordinate. If the tracking data includes a vertical dimension, it is identified by checking for common names such as ‘z’, ‘height’, or ‘altitude’. If none of these are present, vertical_coord is set to None, indicating that the data should be treated as 2D.

  • use_3d (bool, optional (default=False)) – If True and a vertical coordinate is available, compute full 3D distances and velocities. Otherwise, only 2D (horizontal) distances are used.

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 or dict

tobac.analysis.spatial.calculate_nearestneighbordistance(features, method_distance=None)#

Calculate the distance between a feature and the nearest other feature in the same timeframe.

Parameters:

  • features (pandas.DataFrame) – DataFrame of the features whose nearest neighbor distance is to be calculated. Needs 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:

features – DataFrame of the features with a new column ‘min_distance’, containing the calculated minimal distance to other features.

Return type:

pandas.DataFrame

tobac.analysis.spatial.calculate_velocity(track, method_distance=None, return_components=False, use_3d=False)#

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.

  • return_components (bool, optional (default=False)) – Flag to control whether the velocity is calculated and returned as its vector components. If False, only the scalar (absolute) value is returned. If True, the function returns a dictionary containing the scalar value as well as its individual directional components (e.g., ‘vx’, ‘vy’, ‘vz’ for velocity).

  • use_3d (bool, optional (default=False)) – If True and a vertical coordinate is available, compute full 3D distances and velocities. Otherwise, only 2D (horizontal) distances are used.

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, return_components=False, vertical_coord=None, use_3d=False)#

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.

  • return_components (bool, optional (default=False)) – Flag to control whether the velocity is calculated and returned as its vector components. If False, only the scalar (absolute) value is returned. If True, the function returns a dictionary containing the scalar value as well as its individual directional components (e.g., ‘vx’, ‘vy’, ‘vz’ for velocity).

  • vertical_coord (str, optional (default=None)) – Name of the column in the feature representing the vertical (z-axis) coordinate. If the tracking data includes a vertical dimension, it is identified by checking for common names such as ‘z’, ‘height’, or ‘altitude’. If none of these are present, vertical_coord is set to None, indicating that the data should be treated as 2D.

  • use_3d (bool, optional (default=False)) – If True and a vertical coordinate is available, compute full 3D distances and velocities. Otherwise, only 2D (horizontal) distances are used.

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

Classes

combinations(iterable, r)

Return successive r-length combinations of elements in the iterable.

Functions

calculate_area(features, mask[, ...])

Calculate the area of the segments for each feature.

calculate_areas_2Dlatlon(_2Dlat_coord, ...)

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

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

Compute the distance between two features.

calculate_nearestneighbordistance(features)

Calculate the distance between a feature and the nearest other feature in the same timeframe.

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

Calculate the velocities of a set of linked features.

calculate_velocity_individual(feature_old, ...)

Calculate the mean velocity of a feature between two timeframes.

find_dataframe_horizontal_coords(...[, ...])

Function to find the coordinates for the horizontal dimensions in a dataframe, either in Cartesian (xy) or Lat/Lon space.

find_vertical_coord_name(variable_cube[, ...])

Function to find the vertical coordinate in the iris cube

get_statistics_from_mask(features, ...[, ...])

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

haversine(lat1, lon1, lat2, lon2)

Computes the Haversine distance in kilometers.