Velocity

velocity(df=None, traces=None, per_traces=True, parallel=False, n_jobs=2)

Function to calculate velocity for either a single DataFrame or a traces dictionary.

If traces is None, they will be computed from the DataFrame.

Parameters:

• df (pd.DataFrame) – DataFrame containing ‘x’, ‘y’, and ‘timeStamp’ columns.

• traces (dict[str, list[pd.DataFrame]]) – Dictionary mapping session IDs to lists of DataFrames.

• per_traces (bool) – Whether to compute velocity per trace. If False, compute directly on df.

Returns:

Dictionary of traces with computed ‘velocity’ column.

Return type:

dict[str, list[pd.DataFrame]]

Practical Example

from pywib import velocity

 df = compute_space_time_diff(data_frame)
 # Calculate velocity
 df_velocity = velocity(df, per_traces=True)

 # Iterate over traces to obtain velocity values
 for session_id, traces in df_velocity.items():
     print(f"Session ID: {session_id}")
     for trace in traces:
         print(f"Velocity values:\n{trace['velocity']}")

Notes

The method can be either run with either per_traces=True or per_traces=False, the first one segments the data by movement traces, while the second one computes the velocity for the entire DataFrame.

This is important to consider for the specific given dataset, if the data contains anything else than movement data, then per_traces=True should be used to avoid incorrect velocity calculations. Whereas a dataset of consecutive movement events can be processed with per_traces=False to obtain a single velocity DataFrame.

Velocity Metrics

velocity_metrics(df, traces=None)

Calculate velocity metrics for the given DataFrame or traces. This function computes the mean, max, and min velocity for each session.

Parameters:

• df (pd.DataFrame) – DataFrame containing ‘velocity’ column.

• traces (dict) – A dictionary with keys as (sessionId) and values as lists of DataFrames. If None, traces will be computed from df.

Returns:

A dictionary with keys as (sessionId) and values as dictionaries with ‘mean ‘, ‘max’, and ‘min’ velocity.

Return type:

dict

Practical Example

from pywib import velocity_metrics

 metrics = velocity_metrics(data_frame)

 for _, session_id in metrics.items():
     print(f"Mean Velocity: {session_id['mean']}")
     print(f"Max Velocity: {session_id['max']}")
     print(f"Min Velocity: {session_id['min']}")