#include <boost/math/distributions/binomial.hpp>

namespace boost{ namespace math{ 

template <class RealType = double, 
          class Policy   = policies::policy<> >
class binomial_distribution;

typedef binomial_distribution<> binomial;

template <class RealType, class Policy>
class binomial_distribution
{
public:
   typedef RealType  value_type;
   typedef Policy    policy_type;
   
   static const unspecified-type cloppper_pearson_exact_interval;
   static const unspecified-type jeffreys_prior_interval;
   
   // 構造:
   binomial_distribution(RealType n, RealType p);
   
   // 參數訪問::
   RealType success_fraction() const;
   RealType trials() const;
   
   // 成功分數(success fraction)的界限:
   static RealType find_lower_bound_on_p(
      RealType trials, 
      RealType successes,
      RealType probability,
      unspecified-type method = clopper_pearson_exact_interval);
   static RealType find_upper_bound_on_p(
      RealType trials, 
      RealType successes,
      RealType probability,
      unspecified-type method = clopper_pearson_exact_interval);
      
   // 估算 最小/最大的試驗次數:
   static RealType find_minimum_number_of_trials(
      RealType k,     // 事件數
      RealType p,     // 成功分數(success fraction)
      RealType alpha); // 風險級別(risk level)
      
   static RealType find_maximum_number_of_trials(
      RealType k,     // 事件數
      RealType p,     // 成功分數(success fraction)
      RealType alpha); // 風險級別(risk level)
};

}} // namespaces

類型 binomial_distribution 表示一個二項分佈(binomial distribution)：當試驗結果有兩個互斥的結果時使用這個分佈。這些試驗結果標記為「成功」和「失敗」。 二項分佈(binomial distribution) 用於獲取在N次試驗中有K次成功的概率，其中，單次試驗的成功概率記為p。二項分佈假定對所有的試驗，p值都是固定不變的。

	注意
	二項分佈中的隨機變量是試驗成功的次數，(試驗次數是分佈的固定屬性)然而對於負的二項分佈，針對於一個固定的成功次數，隨機變量是試驗次數 。

對於二項分佈的 PDF函數(概率密度函數)由下面的等式給定：

下面的兩個圖像顯示了依賴於分佈參數，函數PDF是如何改變的，首先我們將成功分數值(success fraction)p設為0.5，改變樣本的大小：

另一方面，我們可以將樣本大小固定在 N=20 並改變成功分數p：

	警告
	二項分佈是一個離散分佈：內部函數(例如cdf和pdf)被當作它們「好像是」連續函數一樣，但實際上，僅當將整數值提供給隨機變量的時候這些函數才返回有意義的值。 分位點函數將會缺省返回一個向外捨入( rounded outwards)的整數值。也就是說，下分位點(lower quantiles)(概率小於0.5)向下捨入;上分位點(upper quantiles)(概率大於0.5)向上捨入。這種行為確保如果返回一個X%分位點值，那麼至少目標的覆蓋範圍將會在中心區域顯示，不是要求的覆蓋範圍將會在尾部(tails)顯示。 這種行為可以改變，使得分位點函數可以進行不同的捨入，或者使用策略來返回一個實值(real-valued)。在你使用二項分佈的分位點函數之前，強烈推薦你閱讀理解分佈的分位點 。參考文檔 描述了如何為這些分佈改變捨入策略。

成員函數

構造

binomial_distribution(RealType n, RealType p);

構造函數: n 是試驗的總數，p 是單次試驗成功的概率。

要求：0 <= p <= 1， 且 n >= 0， 否則調用定義域錯誤。

訪問函數(Accessors)

RealType success_fraction() const;

返回構造分佈的參數p。

RealType trials() const;

返回構造分佈的參數n 。

成功分數下邊界值(Lower Bound on the Success Fraction)

static RealType find_lower_bound_on_p(
   RealType trials, 
   RealType successes,
   RealType alpha,
   unspecified-type method = clopper_pearson_exact_interval);

返回成功分數(success fraction)的一個下邊界值：

例如，如果你想觀察 n 次試驗中的 k 次成功，最簡單地估算成功分數的方法是k/n，如果你想要有95%的把握：實值(true value)大於某個值，p_min，那麼：

pmin = binomial_distribution<RealType>::find_lower_bound_on_p(
                    n, k, 0.05);

參考可執行的例子.

對於method可選參數(optional parameter)，當前有兩個可以使用的值：clopper_pearson_exact_interval 或者jeffreys_prior_interval。這些常量是類模板binomial_distribution的成員變量，使用方法如下：

p = binomial_distribution<RealType>::find_lower_bound_on_p(
    n, k, 0.05, binomial_distribution<RealType>::jeffreys_prior_interval);

如果這個method參數沒有指定，那麼缺省的method參數是 Clopper Pearson "精確(exact)" 區間。這種方法產生的區間確保至少100(1-alpha)% 覆蓋(coverage)，但這也是過分保守的，有時這種方法會產生比要求的範圍更大的區間。

這種可選的計算方法產生一個non-informative Jeffreys Prior 區間。它僅在平均情況下才產生100(1-alpha)% 覆蓋(coverage)，雖然通常非常接近於標示的覆蓋層次(coverage level)。它是Brown, Cai 和 DasGupta在複審(review)的過程中推薦的主要的計算方法之一。

請注意：「教科書(textbock)」中使用的正態近似(normal approximation)計算方法 (Wald 區間)有意地沒有提供：這種方法據說始終產生較差的結果，即使是樣本很大的時候。參看Brown, Cai 和 DasGupta的論文獲取一個全面的解釋。 也有許多其它的計算方法，在特定情況下可能也更合適一些。不幸的是在統計學家之間並有一個統一的標準：參看Brown, Cai 和 DasGuptait 的討論的最後部分。

這裡提供了兩種方法主要是因為它們可以針對單側(one sided)和雙側(two sided)區間使用而被選擇。參考：

Lawrence D. Brown, T. Tony Cai 和 Anirban DasGupta (2001), Interval Estimation for a Binomial Proportion, Statistical Science, Vol. 16, No. 2, 101-133.

T. Tony Cai (2005), One-sided confidence intervals in discrete distributions, Journal of Statistical Planning and Inference 131, 63-88.

Agresti, A. and Coull, B. A. (1998). Approximate is better than "exact" for interval estimation of binomial proportions. Amer. Statist. 52 119-126.

Clopper, C. J. and Pearson, E. S. (1934). The use of confidence or fiducial limits illustrated in the case of the binomial. Biometrika 26 404-413.

成功分數(Success Fraction)的上邊界(Upper Bound on the Success Fraction)

static RealType find_upper_bound_on_p(
   RealType trials, 
   RealType successes,
   RealType alpha,
   unspecified-type method = clopper_pearson_exact_interval);

返回成功分數( success fraction)的上邊界：

例如，如果你想觀察 n 次試驗中的 k 次成功，最簡單地估算成功分數的方法是k/n，如果你想要有95%的把握：實值(true value)小於某個值，p_max，那麼：

pmax = binomial_distribution<RealType>::find_upper_bound_on_p(
                    n, k, 0.05);

參照可執行的例子.

	注意
	為了獲取成功部分(success fraction)的雙邊(two sided)邊界，你將使用相同參數來調用函數find_lower_bound_on_p 和 函數find_upper_bound_on_p。 如果真實的成功分數(success fraction)超出邊界的預期風險水平(desired risk level)是α，那麼你將α/2 傳遞給這些函數。 通過將α = 0.025傳遞給每一個函數，你將獲得一個雙邊界(two sided)的95%的置信區間(confidence interval) . 參考可執行的例子.

估算試驗中發生特定次數成功所需要的總試驗次數(Estimating the Number of Trials Required for a Certain Number of Successes)

static RealType find_minimum_number_of_trials(
   RealType k,     // 事件數
   RealType p,     // 成功分數(success fraction)
   RealType alpha); // 概率起始值(probability threshold)

這個函數用於估算在試驗中確保成功發生超過k次所需要進行的試驗的最小次數，成功的次數為k次或少於k次的風險水平為alpha。

例如：

binomial_distribution<RealType>::find_number_of_trials(10, 0.5, 0.05);

返回具有95%把握的以1/2頻率發生的10次成功試驗的最小的試驗次數。

估計最大的試驗次數來確保超過特定的成功次數

static RealType find_maximum_number_of_trials(
   RealType k,     // 事件數
   RealType p,     // 成功部分
   RealType alpha); // 概率起始值(threshold)

這個函數用來估算試驗中有k次或少於k次發生的最大的試驗次數，成功試驗次數大於k次的風險為alpha。

例如：

binomial_distribution<RealType>::find_maximum_number_of_trials(0, 1e-6, 0.05);

返回最大的試驗次數，並且仍然有95%的可能性不能觀察(observing)任何發生頻率為百萬分之一的事件。這通常用在故障分析( failure analysis)中。

參考可執行例子.

非成員訪問函數(Accessors)

支持所有的分佈都通用的 常見的非成員訪問函數 ： 累積分佈函數(Cumulative Distribution Function)，概率密度函數(Probability Density Function)，分位點(Quantile)， 故障率函數(Hazard Function)， 累積危險函數(Cumulative Hazard Function)， 均值(mean)， 中位數(median)， 眾數(mode)， 方差(variance)， 標準差(standard deviation)， 偏斜(skewness)， 峰態(kurtosis)， 峰態超越(kurtosis_excess)， 值域(range) 以及 支持(support)。

隨機變量k 的定義域是：0 <= k <= N, 否則返回定義域錯誤 。

值得花一時間來定義在二項分佈中的這些訪問函數的實際含義：

例子

有許多說明如何使用二項分佈的可執行例子 。

精確度

二項分佈使用不完全β函數ibeta 和ibetac來實現，請參看這些函數瞭解關於精度的信息。

實現

在下面的表中，p 是單次試驗的成功概率(成功分數)，n 是試驗次數，k 是試驗成功的次數，p 是概率 且 q = 1-p.

p = I[sub 1-p](n - k, k + 1)
  = 1 - I[sub p](k + 1, n - k)
  = ibetac(k + 1, n - k, p)

參考資料