[utils.measure] Improved docs

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.
 
     """