mobgap.gait_sequences.evaluation.calculate_matched_gsd_performance_metrics#

mobgap.gait_sequences.evaluation.calculate_matched_gsd_performance_metrics(
matches: DataFrame,
*,
zero_division: Literal['warn', 0, 1] = 'warn',
) → dict[str, float | int][source]#

Calculate commonly known performance metrics for based on the matched overlap with the reference.

This method assumes that you already calculated the overlapping regions between the ground truth and the detected gait sequences using the categorize_intervals_per_sample method. This function then calculates the performance metrics based on the number of true positive, false positive, false negative, and true negative matches between detected and reference. All calculations are performed on the sample level. This means the intervals provided by the input dataframe are used to calculate the number of samples in each category.

The following metrics are always returned:

  • tp_samples: Number of samples that are correctly detected as gait sequences.

  • fp_samples: Number of samples that are falsely detected as gait sequences.

  • fn_samples: Number of samples that are not detected as gait sequences.

  • precision: Precision of the detected gait sequences.

  • recall: Recall of the detected gait sequences.

  • f1_score: F1 score of the detected gait sequences.

See the documentation of precision_recall_f1_score for more details.

Further metrics are calculated if matches contains true negative intervals. This can be achieved by passing n_overall_samples as additional information to categorize_intervals_per_sample.

  • tn_samples: Number of samples that are correctly not detected as gait sequences.

  • specificity: Specificity of the detected gait sequences.

  • accuracy: Accuracy of the detected gait sequences.

  • npv: Negative predictive value of the detected gait sequences.

See the documentation of specificity_score,

accuracy_score, and npv_score for more details.

Parameters:
matches: pd.DataFrame

A DataFrame as returned by categorize_intervals_per_sample. It contains the matched intervals between algorithm output and reference with their start and end index and the respective match_type.

zero_division“warn”, 0 or 1, default=”warn”

Sets the value to return when there is a zero division. If set to “warn”, this acts as 0, but warnings are also raised.

Returns:
gsd_metrics: dict

See also

calculate_unmatched_gsd_performance_metrics

For calculating performance metrics without matching the detected and reference gait sequences.

categorize_intervals_per_sample

For categorizing the detected and reference gait sequences on a sample-wise level. This is required to calculate the matches parameter for this function.