From 73e48a18ee34cf59fec7f667bac799cc52f84561 Mon Sep 17 00:00:00 2001
From: Andre Anjos <andre.dos.anjos@gmail.com>
Date: Mon, 20 Jul 2020 13:48:05 +0200
Subject: [PATCH] [utils.measure] Improved docs
---
bob/ip/binseg/utils/measure.py | 40 +++++++++++++++++++++++++++++-----
1 file changed, 34 insertions(+), 6 deletions(-)
diff --git a/bob/ip/binseg/utils/measure.py b/bob/ip/binseg/utils/measure.py
index 07a95a14..3871f695 100644
--- a/bob/ip/binseg/utils/measure.py
+++ b/bob/ip/binseg/utils/measure.py
@@ -58,22 +58,50 @@ def base_measures(tp, fp, tn, fn):
-------
precision : float
- P, AKA positive predictive value (PPV).
+ P, AKA positive predictive value (PPV). It corresponds arithmetically
+ to ``tp/(tp+fp)``. In the case ``tp+fp == 0``, this function returns
+ zero for precision.
recall : float
- R, AKA sensitivity, hit rate, or true positive rate (TPR).
+ R, AKA sensitivity, hit rate, or true positive rate (TPR). It
+ corresponds arithmetically to ``tp/(tp+fn)``. In the special case
+ where ``tp+fn == 0``, this function returns zero for recall.
specificity : float
- S, AKA selectivity or true negative rate (TNR).
+ S, AKA selectivity or true negative rate (TNR). It
+ corresponds arithmetically to ``tn/(tn+fp)``. In the special case
+ where ``tn+fp == 0``, this function returns zero for specificity.
accuracy : float
- A
+ A, see `Accuracy
+ <https://en.wikipedia.org/wiki/Evaluation_of_binary_classifiers>`_. is
+ the proportion of correct predictions (both true positives and true
+ negatives) among the total number of pixels examined. It corresponds
+ arithmetically to ``(tp+tn)/(tp+tn+fp+fn)``. This measure includes
+ both true-negatives and positives in the numerator, what makes it
+ sensitive to data or regions without annotations.
jaccard : float
- J, see `Jaccard Index <https://en.wikipedia.org/wiki/Jaccard_index>`_
+ J, see `Jaccard Index or Similarity
+ <https://en.wikipedia.org/wiki/Jaccard_index>`_. It corresponds
+ arithmetically to ``tp/(tp+fp+fn)``. In the special case where
+ ``tn+fp+fn == 0``, this function returns zero for the Jaccard index.
+ The Jaccard index depends on a TP-only numerator, similarly to the F1
+ score. For regions where there are no annotations, the Jaccard index
+ will always be zero, irrespective of the model output. Accuracy may be
+ a better proxy if one needs to consider the true abscence of
+ annotations in a region as part of the measure.
f1_score : float
- F1, see `F1-score <https://en.wikipedia.org/wiki/F1_score>`_
+ F1, see `F1-score <https://en.wikipedia.org/wiki/F1_score>`_. It
+ corresponds arithmetically to ``2*P*R/(P+R)`` or ``2*tp/(2*tp+fp+fn)``.
+ In the special case where ``P+R == (2*tp+fp+fn) == 0``, this function
+ returns zero for the Jaccard index. The F1 or Dice score depends on a
+ TP-only numerator, similarly to the Jaccard index. For regions where
+ there are no annotations, the F1-score will always be zero,
+ irrespective of the model output. Accuracy may be a better proxy if
+ one needs to consider the true abscence of annotations in a region as
+ part of the measure.
"""
--
GitLab