Merge pull request #41 from cthoyt/annotate-duplicates

Annotate redundant functions

Author: benedekrozemberczki

rexmex/metrics/classification.py

@@ -96,61 +96,48 @@ def false_negative(y_true: np.array, y_score: np.array) -> float:
     higher_is_better=True,
     description="TN / (TN + FP)",
     link="https://en.wikipedia.org/wiki/Specificity_(tests)",
-    binarize=True,
 )
-def specificity(y_true: np.array, y_score: np.array) -> float:
+def true_negative_rate(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the specificity (same as selectivity and true negative rate).
+    Calculate the true negative rate (duplicated in :func:`specificity` and :func:`selectivity`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
         y_score (array-like):  An N x 1 array of predicted values.
     Returns:
-        tnr (float): The specificity score.
+        tnr (float): The true negative rate.
     """
-    n = condition_negative(y_true)
-    tn = true_negative(y_true, y_score)
-    tnr = tn / n
+    tnr = specificity(y_true, y_score)
     return tnr
 
 
-@classifications.annotate(
-    lower=0.0,
-    upper=1.0,
-    higher_is_better=True,
-    description="TN / (TN + FP)",
-    link="https://en.wikipedia.org/wiki/Specificity_(tests)",
-)
-def selectivity(y_true: np.array, y_score: np.array) -> float:
+@classifications.duplicate(true_negative_rate)
+def specificity(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the selectivity (same as specificity and true negative rate).
+    Calculate the specificity (duplicate of :func:`true_negative_rate`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
         y_score (array-like):  An N x 1 array of predicted values.
     Returns:
-        tnr (float): The selectivity score.
+        tnr (float): The specificity score.
     """
-    tnr = specificity(y_true, y_score)
+    n = condition_negative(y_true)
+    tn = true_negative(y_true, y_score)
+    tnr = tn / n
     return tnr
 
 
-@classifications.annotate(
-    lower=0.0,
-    upper=1.0,
-    higher_is_better=True,
-    description="TN / (TN + FP)",
-    link="https://en.wikipedia.org/wiki/Specificity_(tests)",
-)
-def true_negative_rate(y_true: np.array, y_score: np.array) -> float:
+@classifications.duplicate(true_negative_rate)
+def selectivity(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the true negative rate (same as specificity and selectivity).
+    Calculate the selectivity (duplicate of :func:`true_negative_rate`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
         y_score (array-like):  An N x 1 array of predicted values.
     Returns:
-        tnr (float): The true negative rate.
+        tnr (float): The selectivity score.
     """
     tnr = specificity(y_true, y_score)
     return tnr
@@ -163,32 +150,24 @@ def true_negative_rate(y_true: np.array, y_score: np.array) -> float:
     description="TP / (TP + FN)",
     link="https://en.wikipedia.org/wiki/Sensitivity_(test)",
 )
-def sensitivity(y_true: np.array, y_score: np.array) -> float:
+def true_positive_rate(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the sensitivity (same as recall, hit rate and true positive rate).
+    Calculate the true positive rate (duplicated in :func:`hit_rate`, :func:`sensitivity`, and :func:`recall_score`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
         y_score (array-like):  An N x 1 array of predicted values.
     Returns:
-        tpr (float): The sensitivity score.
+        tpr (float): The true positive rate.
     """
-    p = condition_positive(y_true)
-    tp = true_positive(y_true, y_score)
-    tpr = tp / p
+    tpr = sensitivity(y_true, y_score)
     return tpr
 
 
-@classifications.annotate(
-    lower=0.0,
-    upper=1.0,
-    higher_is_better=True,
-    description="TP / (TP + FN)",
-    link="https://en.wikipedia.org/wiki/Sensitivity_(test)",
-)
+@classifications.duplicate(true_positive_rate)
 def hit_rate(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the hit rate (same as recall, sensitivity and true positive rate).
+    Calculate the hit rate (duplicate of :func:`true_positive_rate`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
@@ -200,27 +179,46 @@ def hit_rate(y_true: np.array, y_score: np.array) -> float:
     return tpr
 
 
-@classifications.annotate(
-    lower=0.0,
-    upper=1.0,
-    higher_is_better=True,
-    description="TP / (TP + FN)",
-    link="https://en.wikipedia.org/wiki/Sensitivity_(test)",
-)
-def true_positive_rate(y_true: np.array, y_score: np.array) -> float:
+@classifications.duplicate(true_positive_rate)
+def sensitivity(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the true positive rate (same as recall, sensitivity and hit rate).
+    Calculate the sensitivity (duplicate of :func:`true_positive_rate`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
         y_score (array-like):  An N x 1 array of predicted values.
     Returns:
-        tpr (float): The true positive rate.
+        tpr (float): The sensitivity score.
     """
-    tpr = sensitivity(y_true, y_score)
+    p = condition_positive(y_true)
+    tp = true_positive(y_true, y_score)
+    tpr = tp / p
     return tpr
 
 
+@classifications.duplicate(true_positive_rate, name="Recall", binarize=True)
+def recall_score(y_true: np.array, y_score: np.array) -> float:
+    """
+    Calculate the recall for a ground-truth prediction vector pair.
+
+    Duplicate of :func:`true_positive_rate`, but with alternate
+    implementation from :mod:`sklearn`.
+
+    Args:
+        y_true (array-like): An N x 1 array of ground truth values.
+        y_score (array-like):  An N x 1 array of predicted values.
+    Returns:
+        recall (float): The value of recall.
+
+    .. note::
+
+        It's surprising that the sklearn implementation of TPR needs
+        to be binarized but the rexmex implementation does not
+    """
+    recall = sklearn.metrics.recall_score(y_true, y_score)
+    return recall
+
+
 @classifications.annotate(
     lower=0.0,
     upper=1.0,
@@ -231,7 +229,7 @@ def true_positive_rate(y_true: np.array, y_score: np.array) -> float:
 )
 def positive_predictive_value(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the positive predictive value (same as precision).
+    Calculate the positive predictive value (duplicated in :func:`precision_score`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
@@ -248,6 +246,24 @@ def positive_predictive_value(y_true: np.array, y_score: np.array) -> float:
     return ppv
 
 
+@classifications.duplicate(positive_predictive_value, name="Precision")
+def precision_score(y_true: np.array, y_score: np.array) -> float:
+    """
+    Calculate the precision for a ground-truth prediction vector pair.
+
+    Duplicate of :func:`positive_predictive_value`, but with an
+    alternate implementation using :mod:`sklearn`.
+
+    Args:
+        y_true (array-like): An N x 1 array of ground truth values.
+        y_score (array-like):  An N x 1 array of predicted values.
+    Returns:
+        precision (float): The value of precision.
+    """
+    precision = sklearn.metrics.precision_score(y_true, y_score)
+    return precision
+
+
 @classifications.annotate(
     lower=0.0,
     upper=1.0,
@@ -257,7 +273,7 @@ def positive_predictive_value(y_true: np.array, y_score: np.array) -> float:
 )
 def negative_predictive_value(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the negative predictive value (same as precision).
+    Calculate the negative predictive value (duplicted in :func:`precision_score`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
@@ -278,40 +294,34 @@ def negative_predictive_value(y_true: np.array, y_score: np.array) -> float:
     description="FN / (FN + TP)",
     link="https://en.wikipedia.org/wiki/Type_I_and_type_II_errors#False_positive_and_false_negative_rates",
 )
-def miss_rate(y_true: np.array, y_score: np.array) -> float:
+def false_negative_rate(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the miss rate (same as false negative rate).
+    Calculate the false negative rate (duplicated in :func:`miss_rate`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
         y_score (array-like):  An N x 1 array of predicted values.
     Returns:
-        fnr (float): The miss rate value.
+        fnr (float): The false negative rate value.
     """
-    fn = false_negative(y_true, y_score)
-    p = condition_positive(y_true)
-    fnr = fn / p
+    fnr = miss_rate(y_true, y_score)
     return fnr
 
 
-@classifications.annotate(
-    lower=0.0,
-    upper=1.0,
-    higher_is_better=False,
-    description="FN / (FN + TP)",
-    link="https://en.wikipedia.org/wiki/Type_I_and_type_II_errors#False_positive_and_false_negative_rates",
-)
-def false_negative_rate(y_true: np.array, y_score: np.array) -> float:
+@classifications.duplicate(false_negative_rate)
+def miss_rate(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the false negative rate (same as miss rate).
+    Calculate the miss rate (duplicate of :func:`false_negative_rate`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
         y_score (array-like):  An N x 1 array of predicted values.
     Returns:
-        fnr (float): The false negative rate value.
+        fnr (float): The miss rate value.
     """
-    fnr = miss_rate(y_true, y_score)
+    fn = false_negative(y_true, y_score)
+    p = condition_positive(y_true)
+    fnr = fn / p
     return fnr
 
 
@@ -322,40 +332,34 @@ def false_negative_rate(y_true: np.array, y_score: np.array) -> float:
     description="FP / (FP + TN)",
     link="https://en.wikipedia.org/wiki/False_positive_rate",
 )
-def fall_out(y_true: np.array, y_score: np.array) -> float:
+def false_positive_rate(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the fall out (same as false positive rate).
+    Calculate the false positive rate (duplicated in :func:`false_positive_rate`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
         y_score (array-like):  An N x 1 array of predicted values.
     Returns:
-        fpr (float): The fall out value.
+        fpr (float): The false positive rate value.
     """
-    fp = false_positive(y_true, y_score)
-    n = condition_negative(y_true)
-    fpr = fp / n
+    fpr = fall_out(y_true, y_score)
     return fpr
 
 
-@classifications.annotate(
-    lower=0.0,
-    upper=1.0,
-    higher_is_better=False,
-    description="FP / (FP + TN)",
-    link="https://en.wikipedia.org/wiki/False_positive_rate",
-)
-def false_positive_rate(y_true: np.array, y_score: np.array) -> float:
+@classifications.duplicate(false_positive_rate)
+def fall_out(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the false positive rate (same as fall out).
+    Calculate the fall out (duplicate of :func:`false_positive_rate`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
         y_score (array-like):  An N x 1 array of predicted values.
     Returns:
-        fpr (float): The false positive rate value.
+        fpr (float): The fall out value.
     """
-    fpr = fall_out(y_true, y_score)
+    fp = false_positive(y_true, y_score)
+    n = condition_negative(y_true)
+    fpr = fp / n
     return fpr
 
 
@@ -505,16 +509,10 @@ def threat_score(y_true: np.array, y_score: np.array) -> float:
     return ts
 
 
-@classifications.annotate(
-    lower=0.0,
-    upper=1.0,
-    higher_is_better=True,
-    description="TP / (TP + FN + FP)",
-    link="https://rexmex.readthedocs.io/en/latest/modules/root.html#rexmex.metrics.classification.threat_score",
-)
+@classifications.duplicate(threat_score)
 def critical_success_index(y_true: np.array, y_score: np.array) -> float:
     """
-    Calculate the critical success index (same as the theat score).
+    Calculate the critical success index (duplicate of :func:`threat_score`).
 
     Args:
         y_true (array-like): An N x 1 array of ground truth values.
@@ -714,52 +712,6 @@ def f1_score(y_true: np.array, y_score: np.array) -> float:
     return f1
 
 
-@classifications.annotate(
-    name="Precision",
-    lower=0.0,
-    upper=1.0,
-    higher_is_better=True,
-    description="TP / (TP + FP)",
-    link="https://en.wikipedia.org/wiki/Positive_predictive_value",
-    binarize=True,
-)
-def precision_score(y_true: np.array, y_score: np.array) -> float:
-    """
-    Calculate the precision for a ground-truth prediction vector pair.
-
-    Args:
-        y_true (array-like): An N x 1 array of ground truth values.
-        y_score (array-like):  An N x 1 array of predicted values.
-    Returns:
-        precision (float): The value of precision.
-    """
-    precision = sklearn.metrics.precision_score(y_true, y_score)
-    return precision
-
-
-@classifications.annotate(
-    name="Recall",
-    lower=0.0,
-    upper=1.0,
-    higher_is_better=True,
-    description="TP / (TP + FN)",
-    link="https://en.wikipedia.org/wiki/Sensitivity_(test)",
-    binarize=True,
-)
-def recall_score(y_true: np.array, y_score: np.array) -> float:
-    """
-    Calculate the recall for a ground-truth prediction vector pair.
-
-    Args:
-        y_true (array-like): An N x 1 array of ground truth values.
-        y_score (array-like):  An N x 1 array of predicted values.
-    Returns:
-        recall (float): The value of recall.
-    """
-    recall = sklearn.metrics.recall_score(y_true, y_score)
-    return recall
-
-
 @classifications.annotate(
     name="Average precision",
     lower=0.0,