View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.math.distribution;
18  
19  import java.io.Serializable;
20  
21  import org.apache.commons.math.MathException;
22  import org.apache.commons.math.MathRuntimeException;
23  import org.apache.commons.math.special.Beta;
24  import org.apache.commons.math.util.MathUtils;
25  
26  /**
27   * The default implementation of {@link BinomialDistribution}.
28   *
29   * @version $Revision: 772119 $ $Date: 2009-05-06 05:43:28 -0400 (Wed, 06 May 2009) $
30   */
31  public class BinomialDistributionImpl
32      extends AbstractIntegerDistribution
33      implements BinomialDistribution, Serializable {
34  
35      /** Serializable version identifier */
36      private static final long serialVersionUID = 6751309484392813623L;
37  
38      /** The number of trials. */
39      private int numberOfTrials;
40  
41      /** The probability of success. */
42      private double probabilityOfSuccess;
43  
44      /**
45       * Create a binomial distribution with the given number of trials and
46       * probability of success.
47       * @param trials the number of trials.
48       * @param p the probability of success.
49       */
50      public BinomialDistributionImpl(int trials, double p) {
51          super();
52          setNumberOfTrials(trials);
53          setProbabilityOfSuccess(p);
54      }
55  
56      /**
57       * Access the number of trials for this distribution.
58       * @return the number of trials.
59       */
60      public int getNumberOfTrials() {
61          return numberOfTrials;
62      }
63  
64      /**
65       * Access the probability of success for this distribution.
66       * @return the probability of success.
67       */
68      public double getProbabilityOfSuccess() {
69          return probabilityOfSuccess;
70      }
71  
72      /**
73       * Change the number of trials for this distribution.
74       * @param trials the new number of trials.
75       * @throws IllegalArgumentException if <code>trials</code> is not a valid
76       *         number of trials.
77       */
78      public void setNumberOfTrials(int trials) {
79          if (trials < 0) {
80              throw MathRuntimeException.createIllegalArgumentException(
81                    "number of trials must be non-negative ({0})", trials);
82          }
83          numberOfTrials = trials;
84      }
85  
86      /**
87       * Change the probability of success for this distribution.
88       * @param p the new probability of success.
89       * @throws IllegalArgumentException if <code>p</code> is not a valid
90       *         probability.
91       */
92      public void setProbabilityOfSuccess(double p) {
93          if (p < 0.0 || p > 1.0) {
94              throw MathRuntimeException.createIllegalArgumentException(
95                    "{0} out of [{1}, {2}] range", p, 0.0, 1.0);
96          }
97          probabilityOfSuccess = p;
98      }
99  
100     /**
101      * Access the domain value lower bound, based on <code>p</code>, used to
102      * bracket a PDF root.
103      * 
104      * @param p the desired probability for the critical value
105      * @return domain value lower bound, i.e.
106      *         P(X &lt; <i>lower bound</i>) &lt; <code>p</code> 
107      */
108     @Override
109     protected int getDomainLowerBound(double p) {
110         return -1;
111     }
112 
113     /**
114      * Access the domain value upper bound, based on <code>p</code>, used to
115      * bracket a PDF root.
116      * 
117      * @param p the desired probability for the critical value
118      * @return domain value upper bound, i.e.
119      *         P(X &lt; <i>upper bound</i>) &gt; <code>p</code> 
120      */
121     @Override
122     protected int getDomainUpperBound(double p) {
123         return getNumberOfTrials();
124     }
125 
126     /**
127      * For this distribution, X, this method returns P(X &le; x).
128      * @param x the value at which the PDF is evaluated.
129      * @return PDF for this distribution. 
130      * @throws MathException if the cumulative probability can not be
131      *            computed due to convergence or other numerical errors.
132      */
133     @Override
134     public double cumulativeProbability(int x) throws MathException {
135         double ret;
136         if (x < 0) {
137             ret = 0.0;
138         } else if (x >= getNumberOfTrials()) {
139             ret = 1.0;
140         } else {
141             ret =
142                 1.0 - Beta.regularizedBeta(
143                         getProbabilityOfSuccess(),
144                         x + 1.0,
145                         getNumberOfTrials() - x);
146         }
147         return ret;
148     }
149 
150     /**
151      * For this distribution, X, this method returns P(X = x).
152      * 
153      * @param x the value at which the PMF is evaluated.
154      * @return PMF for this distribution. 
155      */
156     public double probability(int x) {
157         double ret;
158         if (x < 0 || x > getNumberOfTrials()) {
159             ret = 0.0;
160         } else {
161             ret = MathUtils.binomialCoefficientDouble(
162                     getNumberOfTrials(), x) *
163                   Math.pow(getProbabilityOfSuccess(), x) *
164                   Math.pow(1.0 - getProbabilityOfSuccess(),
165                         getNumberOfTrials() - x);
166         }
167         return ret;
168     }
169     
170     /**
171      * For this distribution, X, this method returns the largest x, such
172      * that P(X &le; x) &le; <code>p</code>.
173      * <p>
174      * Returns <code>-1</code> for p=0 and <code>Integer.MAX_VALUE</code> for
175      * p=1.</p>
176      *
177      * @param p the desired probability
178      * @return the largest x such that P(X &le; x) <= p
179      * @throws MathException if the inverse cumulative probability can not be
180      *            computed due to convergence or other numerical errors.
181      * @throws IllegalArgumentException if p < 0 or p > 1
182      */
183     @Override
184     public int inverseCumulativeProbability(final double p) throws MathException {
185         // handle extreme values explicitly
186         if (p == 0) {
187             return -1;
188         } 
189         if (p == 1) {
190             return Integer.MAX_VALUE; 
191         }
192         
193         // use default bisection impl
194         return super.inverseCumulativeProbability(p);
195     }
196 }