npv_score#

mobgap.utils.evaluation.npv_score( matches_df: DataFrame, *, n_overall_samples: int | None = None, zero_division: Literal['warn', 0, 1] = 'warn', tn_warning: bool = True, ) → float[source]#

Compute the negative predictive value (NPV).

The NPV is the ratio tn / (tn + fn) where tn is the number of true negatives and fn the number of false negatives. Intuitively speaking, the NPV is the ability of the classifier not to label a positive sample as negative.

The best value is 1 and the worst value is 0.

Parameters:

matches_df: A 3 column dataframe. Currently supported are dataframes resulting from the evaluation of gait sequence detection algorithms (results from categorize_intervals_per_sample). To be handled like a gait sequence detection evaluation dataframe, the matches_df must have columns “start”, “end”, and “match_type”. The match_type column indicates the type of match: “tp” (true positive), “fp” (false positives), “fn” (false negative), or “tn” (true negative), if no segmented counterpart exists. If the matches_df does not contain tn matches, the number of overall samples in the recording needs to be provided as n_overall_samples.
n_overall_samples: Union[int, None]: Number of overall samples. Must be provided if the matches_df does not contain tn matches. Needs to be kept as None if the matches_df contains tn matches.
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.
tn_warningbool, default=True: A warning is raised if matches_df does not contain tn matches and n_overall_samples is not provided. Otherwise, warning is suppressed and tn is set to 0.

Returns:

npv_score: float: Value between 0 and 1.

Notes

Initial contact detection evaluation dataframes (with the columns “ic_id_detected”, “ic_id_reference”, “match_type”) are rejected for this metric as the percentage of true negatives outweighs all other match types and thus the NPV score is not meaningful.