tobac.analysis.cell_analysis.calculate_distance

tobac.analysis.cell_analysis.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