specificity_score#

mobgap.utils.evaluation.specificity_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 specificity.

The specificity is the ratio tn / (tn + fp) where tn is the number of true negatives and fp the number of false positives. Intuitively speaking, the specificity is the ability of the classifier to find all the negative samples.

The best value is 1 and the worst value is 0. Specificity can be also referred to as the true negative rate (TNR).

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:

specificity_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 specificity score is not meaningful.