tobac.analysis.spatial.calculate_velocity_individual#

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