Added thirdparty: boost library

thirdparty/include/boost/histogram/utility/wilson_interval.hpp

@@ -0,0 +1,86 @@
+// Copyright 2022 Jay Gohil, Hans Dembinski
+//
+// Distributed under the Boost Software License, version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+#ifndef BOOST_HISTOGRAM_UTILITY_WILSON_INTERVAL_HPP
+#define BOOST_HISTOGRAM_UTILITY_WILSON_INTERVAL_HPP
+
+#include <boost/histogram/fwd.hpp>
+#include <boost/histogram/utility/binomial_proportion_interval.hpp>
+#include <cmath>
+#include <utility>
+
+namespace boost {
+namespace histogram {
+namespace utility {
+
+/**
+  Wilson interval.
+
+  The Wilson score interval is simple to compute, has good coverage. Intervals are
+  automatically bounded between 0 and 1 and never empty. The interval is asymmetric.
+
+  Wilson, E. B. (1927). "Probable inference, the law of succession, and statistical
+  inference". Journal of the American Statistical Association. 22 (158): 209-212.
+  doi:10.1080/01621459.1927.10502953. JSTOR 2276774.
+
+  The coverage probability for a random ensemble of fractions is close to the nominal
+  value. Unlike the Clopper-Pearson interval, the Wilson score interval is not
+  conservative. For some values of the fractions, the interval undercovers and overcovers
+  for neighboring values. This is a shared property of all alternatives to the
+  Clopper-Pearson interval.
+
+  The Wilson score intervals is widely recommended for general use in the literature. For
+  a review of the literature, see R. D. Cousins, K. E. Hymes, J. Tucker, Nucl. Instrum.
+  Meth. A 612 (2010) 388-398.
+*/
+template <class ValueType>
+class wilson_interval : public binomial_proportion_interval<ValueType> {
+public:
+  using value_type = typename wilson_interval::value_type;
+  using interval_type = typename wilson_interval::interval_type;
+
+  /** Construct Wilson interval computer.
+
+    @param d Number of standard deviations for the interval. The default value 1
+    corresponds to a confidence level of 68 %. Both `deviation` and `confidence_level`
+    objects can be used to initialize the interval.
+  */
+  explicit wilson_interval(deviation d = deviation{1.0}) noexcept
+      : z_{static_cast<value_type>(d)} {}
+
+  using binomial_proportion_interval<ValueType>::operator();
+
+  /** Compute interval for given number of successes and failures.
+
+    @param successes Number of successful trials.
+    @param failures Number of failed trials.
+  */
+  interval_type operator()(value_type successes, value_type failures) const noexcept {
+    // See https://en.wikipedia.org/wiki/
+    //   Binomial_proportion_confidence_interval
+    //   #Wilson_score_interval
+
+    // We make sure calculation is done in single precision if value_type is float
+    // by converting all literals to value_type. Double literals in the equation
+    // would turn intermediate values to double.
+    const value_type half{0.5}, quarter{0.25}, zsq{z_ * z_};
+    const value_type total = successes + failures;
+    const value_type minv = 1 / (total + zsq);
+    const value_type t1 = (successes + half * zsq) * minv;
+    const value_type t2 =
+        z_ * minv * std::sqrt(successes * failures / total + quarter * zsq);
+    return {t1 - t2, t1 + t2};
+  }
+
+private:
+  value_type z_;
+};
+
+} // namespace utility
+} // namespace histogram
+} // namespace boost
+
+#endif