mobgap.initial_contacts.evaluation.calculate_true_positive_icd_error#

mobgap.initial_contacts.evaluation.calculate_true_positive_icd_error(
ic_list_reference: DataFrame,
match_ics: DataFrame,
sampling_rate_hz: float,
groupby: Hashable | tuple[Hashable, ...] = 'wb_id',
) → dict[str, float | int][source]#

Calculate error metrics for initial contact detection results.

This function assumes that you already classified the detected initial contacts as true positive (tp), false positive (fp), or false negative (fn) matches using the categorize_ic_list function. The dataframe returned by categorize function can then be used as input to this function.

The following metrics are calculated for each true positive initial contact:

  • tp_absolute_timing_error_s: Absolute time difference (in seconds) between the detected and reference initial contact.

  • tp_relative_timing_error: All absolute errors, within a walking bout, divided by the average step duration estimated by the INDIP.

In case no ICs are detected, the error metrics will be 0. Note, that this will introduce a bias when comparing these values, because algorithms that don’t find any ICs will have a lower error than algorithms that find ICs but with a higher error. The value should always be considered together with the number of correctly detected ICs.

Parameters:
ic_list_reference: pd.DataFrame

The dataframe of reference initial contacts.

match_ics: pd.DataFrame

Initial contact true positives as output by get_matching_ics.

sampling_rate_hz: float

Sampling rate of the data.

groupby

A valid pandas groupby argument to group the initial contacts by to calculate the average step duration.

Returns:
error_metrics: dict