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.
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 precision_recall_f1_score for more details.

Note, that some of the metrics might run into zero division errors depending on the input data. The resulting value can be controlled by the zero_division parameter. See the documentation of specificity_score, accuracy_score, and npv_score for more details. Note, that you can only control the behavior of the zero division for all metrics at once. If you need individual control, you need to calculate the metrics separately.

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