Add confidence interval functionalities

bob/measure/test_utils.py

+#!/usr/bin/env python
+# vim: set fileencoding=utf-8 :
+
+import numpy
+from .utils import confidence_for_indicator_variable
+
+
+def test_confidence_interval():
+
+    def assert_confidence(x, n, expected_lower, expected_upper):
+        lower, upper = confidence_for_indicator_variable(x, n)
+        assert numpy.allclose(lower, expected_lower)
+        assert numpy.allclose(upper, expected_upper)
+
+    assert_confidence(1, 2, 0.01257911709342505, 0.98742088290657493)
+    assert_confidence(10, 10, 0.69150289218123917, 1)
+    assert_confidence(0, 10, 0, 0.30849710781876077)

bob/measure/utils.py

+''' Utilities functionalities'''
+
+import scipy.stats
+import numpy
+
+
+def confidence_for_indicator_variable(x, n, alpha=0.05):
+    '''Calculates the confidence interval for proportion estimates
+    The Clopper-Pearson interval method is used for estimating the confidence
+    intervals.
+
+    More info on confidence intervals
+    ---------------------------------
+    https://en.wikipedia.org/wiki/Confidence_interval
+    https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Clopper-Pearson_interval
+
+    Parameters
+    ----------
+    x : int
+        The number of successes.
+    n : int
+        The number of trials.
+    alpha : float, optional
+        The 1-confidence value that you want. For example, alpha should be 0.05
+        to obtain 95% confidence intervals.
+
+    Returns
+    -------
+    (float, float) Returns a tuple of (lower_bound, upper_bound) which
+        shows the limit of your success rate: lower_bound < x/n < upper_bound
+    '''
+    lower_bound = scipy.stats.beta.ppf(alpha / 2.0, x, n - x + 1)
+    upper_bound = scipy.stats.beta.ppf(1 - alpha / 2.0, x + 1, n - x)
+    if numpy.isnan(lower_bound):
+        lower_bound = 0
+    if numpy.isnan(upper_bound):
+        upper_bound = 1
+    return (lower_bound, upper_bound)

doc/py_api.rst

@@ -97,3 +97,4 @@ Details
 .. automodule:: bob.measure.calibration
 .. automodule:: bob.measure.plot
 .. automodule:: bob.measure.load
+.. automodule:: bob.measure.utils