Jerkiness

jerkiness(df=None, traces=None, per_traces=True)

Compute jerkiness for either a single DataFrame or multiple traces.

If traces is not provided, they are extracted from df using extract_traces_by_session().

Parameters:

• df (pd.DataFrame, optional) – DataFrame containing ‘acceleration’ and ‘dt’ columns.

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

Returns:

Dictionary of traces, each containing the computed ‘jerkiness’ column.

Return type:

dict[str, list[pd.DataFrame]]

Practical Example

from pywib import jerkiness
jk_df = jerkiness(data_df, per_traces=True)

for _, traces in jk_df.items():
    for trace in traces:
        print(trace[['time', 'x', 'y', 'jerkiness']].head())

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 jerkiness 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 jerkiness calculations. Whereas a dataset of consecutive movement events can be processed with per_traces=False to obtain a single jerkiness DataFrame.

Jerkiness Metrics

jerkiness_metrics(df, traces=None)

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

Parameters:

• df (pd.DataFrame) – DataFrame containing interaction data. Optionally already including ‘jerkiness’ 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’ jerkiness.

Return type:

dict

Practical Example

from pywib import jerkiness_metrics
metrics = jerkiness_metrics(data_df)

for session, session in metrics.items():
    print(f"Session: {session}, Mean Jerkiness: {session['mean']}, Max Jerkiness: {session['max']}, Min Jerkiness: {session['min']}")